مقدمه

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

این پست نگاهی دقیق‌تر به بخش‌های آن سطح اصلی دارد که introductory post تنها به‌طور گذرا به آن‌ها اشاره کرده است: ترکیب اسناد از اسناد دیگر، ساخت صفحات از صفر، افزودن درخت نشانک برای ناوبری، و برچسب‌گذاری محتوا برای دسترس‌پذیری. هر چهار مورد فقط فراخوانی‌های سادهٔ متد هستند — بدون ماژول جداگانه برای وارد کردن، بدون وابستگی اضافه‌ای جز خود بستهٔ @asposefoss/pdf.

این‌ها عملیاتی هستند که پس از این‌که یک خط لولهٔ PDF فراتر از «یک فایل را باز کن، تغییر بده، ذخیره کن» رفت: ترکیب گزارش‌ها از چند منبع در یک سند، تولید صفحات به‌صورت برنامه‌نویسی به‌جای شروع از یک قالب، و قابل‌ناوبری و دسترس‌پذیر کردن خروجی به‌جای صرفاً صحیح بودن بصری.

چه مواردی گنجانده شده

ترکیب و بازسازماندهی اسناد

Document.Split() یک سند را به Document تک‌صفحه‌ای جدید برای هر صفحه، به ترتیب صفحات، تقسیم می‌کند. Document.ExtractPages() مجموعه‌ای از شماره‌های صفحهٔ ۱-پایهٔ داده‌شده را به یک Document خودکفا جدید کپی می‌کند، به ترتیب داده‌شده — می‌توان همان صفحه را تکرار کرد. صفحات یک سند نیز می‌توانند به سند دیگری کپی شوند: Document.Append() هر صفحهٔ سند منبع را به انتهای هدف می‌کپی‌کند، و Document.InsertPage() یک صفحهٔ تک را در موقعیت ۱-پایهٔ مشخص بین اسناد کپی می‌کند.

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

const report = Document.OpenFile('report.pdf');

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

const cover = Document.OpenFile('cover.pdf');
report.InsertPage(1, cover.Pages[0]);               // copy a single page across documents
report.Append(chapter);                             // copy chapter's pages onto report

report.WriteTo('assembled.pdf');

چندین سند نیز می‌توانند در یک فراخوانی واحد با Document.Merge() ترکیب شوند، که یک Document جدید را از نسخه‌های هر صفحه از هر سندی که به آن پاس داده می‌شود، به ترتیب می‌سازد.

ساخت صفحات از ابتدا

Document.New() یک سند را از هیچ چیز ایجاد می‌کند: صفر صفحه وقتی فرمت حذف شده باشد، یا یک صفحه خالی از PageFormat داده‌شده وقتی یکی پاس داده شود. صفحات خالی اضافی از Document.AddPage() می‌آید، که همچنین یک PageFormat می‌پذیرد (یا یک Page موجود برای کپی اندازه). متن با Page.AddText() روی صفحه کشیده می‌شود، که در نقطه (x, y) در فضای کاربر PDF قرار دارد.

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');

نشانک‌ها و ناوبری سند

طرح کلی سند (پنل نشانک که اکثر خوانندگان PDF در کنار صفحه نشان می‌دهند) با Document.GetOutlines() خوانده می‌شود و به‌صورت کامل با Document.SetOutlines() جایگزین می‌شود، که هر کدام با درختی از مقادیر OutlineItem کار می‌کنند. هر OutlineItem شامل یک Title، یک مقصد Dest، و به‌اختیار Children برای ورودی‌های تو در تو، به‌همراه نکات نمایش مانند Open (به‌صورت پیش‌فرض باز شده) و Bold است.

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

const items: OutlineItem[] = [
  { Title: 'Introduction', Dest: { name: 'intro' } },
  {
    Title: 'Chapters',
    Open: true,
    Children: [
      { Title: 'Chapter 1', Dest: { name: 'ch1' } },
      { Title: 'Chapter 2', Dest: { name: 'ch2' } },
    ],
  },
];
doc.SetOutlines(items);

مقاصد به این شکل نام‌گذاری شده ({ name: 'intro' }) از طریق جدول مقاصد نام‌دار سند حل می‌شوند، که Document.GetNamedDestinations() و Document.SetNamedDestination() به‌صورت مستقیم مدیریت می‌کنند وقتی یک نشانک نیاز دارد به مقصدی اشاره کند که به محتوای صفحه مرتبط نیست.

متن ساختار یافته و برچسب‌گذاری دسترسی‌پذیری

Document.GetStructTree() درخت ساختار منطقی سند را برمی‌گرداند (یا null وقتی سند برچسب‌گذاری نشده باشد)، و Document.CreateStructTree() یکی را می‌سازد، سند را به‌عنوان Tagged علامت‌گذاری می‌کند. هنگامی که درخت ساختار وجود داشته باشد، Page.GetStructuredText() متن صفحه را به‌صورت مقادیر TextBlock برمی‌گرداند — قطعات موقعیت‌یافته که پیشاپیش به خطوط و بلوک‌های شبیه پاراگراف گروه‌بندی شده‌اند — که ورودی یک مرحله برچسب‌گذاری دستی است: عبور از بلوک‌ها، تصمیم‌گیری درباره اینکه کدامیک عنوان هستند و کدام متن اصلی، و افزودن عناصر مرتبط به درخت.

function handTagPage(doc: Document, page: Page, heading: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('handTagPage: the document is not tagged yet');
  for (const block of page.GetStructuredText()) {
    const text = block.text.trim();
    if (text.length === 0) continue;
    const el = root.Append(text.startsWith(heading) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

درخت ساختار برچسب‌دار، پایه‌ای است که ویژگی‌های پایین‌دستی بر آن ساخته می‌شوند: خروجی معنایی HTML بازخوانی می‌شود تا به جای بازگشت به یک چیدمان سادهٔ هوریستیک، از آن استفاده کند، و Document.ValidatePdfUa() سند را نسبت به زیرمجموعه‌ای از استاندارد دسترسی‌پذیری PDF/UA که به وجود برچسب‌ها وابسته است، بررسی می‌کند.

شروع سریع

بسته را نصب کنید، سپس یک سند را باز کنید، زیرمجموعه‌ای از صفحات آن را استخراج و ترکیب کنید، و نتیجه را ذخیره کنید:

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('report.pdf');

const chapter = doc.ExtractPages([3, 4, 5]);   // subset (1-based, repeats allowed) as a new Document
const cover = Document.OpenFile('cover.pdf');

doc.InsertPage(1, cover.Pages[0]);             // copy a single page across documents
doc.Append(chapter);                           // copy chapter's pages onto doc

doc.WriteTo('assembled.pdf');

قالب‌های پشتیبانی‌شده

قالبپسوندخواندننوشتن
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

منبع باز و مجوزدهی

Aspose.PDF FOSS برای TypeScript تحت لیسانس MIT منتشر شده است، با کد منبع که در GitHub منتشر شده است. هیچ علامت آب‌نمای ارزیابی، محدودیت استفاده، یا فایل مجوز جداگانه‌ای برای مدیریت وجود ندارد و کتابخانه می‌تواند در محصولات تجاری بدون حق‌الامتیاز استفاده شود.

این بسته در حال حاضر در نسخهٔ 0.1.0 است که نشان‌دهنده توسعه فعال در مراحل اولیه می‌باشد. Node.js (>=22) تنها نیازمندی زمان اجرا است و این بسته هیچ وابستگی دیگری به کتابخانه‌های شخص ثالث ندارد.

شروع کار

منابع مرتبط