ליבה API

ליבה API

מדריך זה מראה כיצד לפתוח, לערוך, לאסוף ולשמור מסמכי PDF עם המחלקות Document ו-Page — נקודות הכניסה לכל פעולה ב-Aspose.PDF FOSS עבור TypeScript. Document טוען, יוצר, מאסף ושומר קבצי PDF שלמים; Page, המגיע דרך doc.Pages, חושף פעולות של טקסט, תמונה, annotation ו-content-stream לכל עמוד.

מחזור חיי המסמך

Document.OpenFile() פותח PDF משנת נתיב קובץ; Document.Open() מקבל Uint8Array בזיכרון. ניתן לבדוק ולעדכן דפים במקום, ו-Document.WriteTo() כותב את התוצאה חזרה — באופן אופציונלי עם דחיסת xref-stream ו-object-stream.

import { Document } from '@asposefoss/pdf';

// Open from disk (or Document.Open(uint8array) for in-memory data)
const doc = Document.OpenFile('input.pdf');

// Inspect and edit pages
const pages = doc.Pages;
console.log(pages.length);
pages[0].Rotate = 90;
doc.RemovePage(2);                 // 1-based page number
doc.Reorder([3, 1, 2]);

// Metadata
doc.SetMetadata({ title: 'Report', author: 'Jane', custom: { Dept: 'R&D' } });

// Save
doc.WriteTo('output.pdf');         // or: const bytes = doc.Save();
doc.WriteTo('small.pdf', { compressed: true }); // xref stream + object streams

פיצול, מיזוג והוצאת דפים

Document.Split() מחזיר Document אחד לכל דף. Document.ExtractPages() מקבל רשימת דפים שמתחילה מ-1, ומאפשר חזרות, ומחזיר Document חדש המכיל רק את הדפים האלה. Document.Append() ו-Document.InsertPage() מעתיקים דפים בין מסמכים, ו-Document.Merge() משלב כמה מסמכים למסמך אחד.

const parts = doc.Split();                       // one Document per page
const chapter = doc.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

docA.Append(docB);                               // copy all of docB's pages onto docA
docA.InsertPage(1, docB.Pages[0]);               // copy a single page across documents

יצירת מסמך חדש

Document.New() מתחיל מסמך ריק ב-PageFormat נתון. Page.AddText() ממקם טקסט, ו-Document.AddPage() מוסיף דפים נוספים, כולל פורמט מסובב כגון PageFormat.A4.landscape().

import { Document, PageFormat } from '@asposefoss/pdf';
const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

סימני מים ומספרי עמודים

Page.AddText() תומך גם בסיבוב, צבע ושקיפות, מה שמספיק ליצירת מספר עמוד וסימן מים אלכסוני ללא צורך במחלקות נוספות.

const doc = Document.OpenFile('in.pdf');
const page = doc.Pages[0];

// Page number, right-aligned near the bottom-right corner.
const w = page.Rect[2] - page.Rect[0];
page.AddText(`Page ${page.Number}`, w - 40, 20, { fontSize: 10, align: 'right' });

// Semi-transparent diagonal watermark, centered on the page.
page.AddText('DRAFT', page.Rect[2] / 2, page.Rect[3] / 2, {
  font: 'Times-Bold', fontSize: 64, color: [0.7, 0.7, 0.7], opacity: 0.4, rotate: 45, align: 'center',
});

doc.WriteTo('out.pdf');

תצפית על זרם תוכן

parseContentStream() מפענח את זרם /Contents הגולמי של דף לרשימת זוגות מפעיל/אופרנד, ו-serializeContentStream() ממיר רשימת מפעילים ערוכה בחזרה לבייטים.

import { parseContentStream, serializeContentStream } from '@asposefoss/pdf';

const ops = parseContentStream(doc.Pages[0].Contents);
// ops: { operator: string, operands: PdfObject[], inlineImage?: {...} }[]
for (const op of ops) {
  if (op.operator === 'Tj') console.log('text op:', op.operands);
}
const bytes = serializeContentStream(ops);       // round-trips operators + operands

זרימת טקסט מרובה עמודות

Page.AddTextBlock() מזרם מחרוזת טקסט ארוכה לאזור מלבני ומחזיר כל טקסט שלא נכנס, שניתן להעביר לקריאה שנייה כדי להמשיך את הזרימה לעמודה נוספת.

const rest = page.AddTextBlock(longText, [72, 600, 200, 150], {
  font: 'Times-Roman', fontSize: 11, align: 'justify', valign: 'top', leading: 14,
});
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // continue into a 2nd column

טיפים ושיטות מומלצות

• השתמש ב-Document.OpenFile() בשביל נתיבי קבצים ו-Document.Open() בשביל נתונים בזיכרון Uint8Array.
• מספרי העמודים המועברים לשיטות כגון RemovePage() ו-ExtractPages() הם מבוססי 1, בעוד doc.Pages הוא מערך מבוסס 0.
• העבר את { compressed: true } ל-Document.WriteTo() כדי לאפשר דחיסת xref-stream ו-object-stream בפלט.
• Document.ExtractPages() מקבל מספרי עמודים חוזרים, ולכן אפשר שהעמוד המקור יופיע יותר מפעם אחת בתוצאה.
• קרא את page.Rect כדי לחשב מיקומים יחסיים לרוחב ולגובה האמיתי של העמוד במקום לקודד קואורדינטות באופן קבוע.

בעיות נפוצות

FAQ

האם Document.Open() מקבל גם נתיבי קבצים וגם נתונים בזיכרון?

Document.OpenFile() נפתח מנתיב קובץ; Document.Open() מקבל Uint8Array של בתים בזיכרון.

האם מספור העמודים הוא מבוסס 0 או מבוסס 1?

שניהם, בהתאם ל-API: doc.Pages הוא מערך פשוט מבוסס 0, אך שיטות כגון RemovePage() ו-ExtractPages() מקבלות מספרי עמודים מבוססי 1.

האם אפשר להצפין מסמך בזמן שמירתו?

כן — העבר אפשרות encrypt ל-WriteTo() / Save() עם algorithm: 'aes256' | 'aes128' | 'rc4' וסיסמאות משתמש/בעלים אופציונליות.

איך אני מקטין את גודל קובץ הפלט?

העבר { compressed: true } ל-Document.WriteTo() כדי להפעיל דחיסת xref-stream ו-object-stream.

האם אפשר לבדוק את המפעילים של זרם התוכן הגולמי של דף?

כן — parseContentStream(doc.Pages[0].Contents) מחזיר את רשימת האופרטורים, ו-serializeContentStream() ממיר רשימה ערוכה חזרה לבייטים.

API Reference סיכום

ראה גם

• Aspose.PDF — Enterprise Documentation