النواة API

النواة API

يُظهر هذا الدليل كيفية فتح وتحرير وتجميع وحفظ مستندات PDF باستخدام الفئتين Document و Page — نقاط الدخول لكل عملية في Aspose.PDF مفتوح المصدر لـ 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() يأخذ قائمة صفحات تبدأ من 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