هسته API

API اصلی

این راهنما نشان می‌دهد چگونه اسناد PDF را با کلاس‌های Document و Page باز، ویرایش، ترکیب و ذخیره کنید — نقطه‌های ورودی برای هر عملیات در Aspose.PDF FOSS برای TypeScript. Document فایل‌های PDF کامل را بارگیری، ایجاد، ترکیب و ذخیره می‌کند؛ Page که از طریق doc.Pages قابل دسترسی است، عملیات متن، تصویر، حاشیه‌نویسی و جریان محتوا برای هر صفحه را در دسترس می‌گذارد.

دوره حیات سند

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() یک فهرست صفحه‌ای ۱-پایه که تکرارها اجازه‌دارند می‌گیرد و یک 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() ارسال می‌شوند، به صورت یک‌پایه هستند، در حالی که doc.Pages یک آرایه صفرپایه است.
• { compressed: true } را به Document.WriteTo() پاس بدهید تا فشرده‌سازی xref-stream و object-stream بر روی خروجی فعال شود.
• Document.ExtractPages() شماره‌های صفحه تکراری را می‌پذیرد، بنابراین همان صفحه منبع می‌تواند بیش از یک بار در نتیجه ظاهر شود.
• برای محاسبه موقعیت‌ها نسبت به عرض و ارتفاع واقعی صفحه به جای کدگذاری ثابت مختصات، page.Rect را بخوانید.

مشکلات رایج

FAQ

آیا Document.Open() هم مسیرهای فایل و هم داده‌های در-حافظه را می‌پذیرد؟

Document.OpenFile() از مسیر فایل باز می‌شود؛ Document.Open() یک Uint8Array از بایت‌های در-حافظه را می‌پذیرد.

شماره‌گذاری صفحات صفر مبنایی است یا یک مبنایی؟

هر دو، بسته به API: doc.Pages یک آرایهٔ سادهٔ صفر-مبنایی است، اما متدهایی مانند RemovePage() و ExtractPages() شماره‌های صفحهٔ یک-مبنایی را می‌پذیرند.

آیا می‌توانم سند را هنگام ذخیره‌سازی رمزگذاری کنم؟

بله — گزینهٔ 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