Cách làm việc với cấu trúc PDF trong TypeScript

Hướng dẫn này chỉ cách xây dựng điều hướng tài liệu và cấu trúc logic trong các tệp PDF bằng Aspose.PDF FOSS cho TypeScript: một mục lục có thể nhấp trên một trang, một dàn phác thảo dấu trang ở mức độ tài liệu, các đích được đặt tên, và một cây cấu trúc được gắn thẻ để hỗ trợ khả năng truy cập. Yêu cầu Node.js 22 trở lên.

Hướng dẫn từng bước

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

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

const page = doc.Pages[0];

page.AddTOC(
  [
    { title: '1.  Introduction', page: 2 },
    { title: '2.  Methodology', page: 5 },
    { title: '3.  Results', page: 9 },
  ],
  [72, 160, 400, 600],
  { font: 'Helvetica', fontSize: 13, color: [0.1, 0.1, 0.15], rowGap: 18 },
);

const items: OutlineItem[] = [
  { Title: 'Sales', Dest: { name: 'section.sales' }, Open: true, Color: [0.1, 0.4, 0.1] },
  { Title: 'Appendix', Dest: { name: 'section.appendix' } },
];

doc.SetOutlines(items);

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));

const walk = (nodes: OutlineItem[]): void => {
  for (const item of nodes) {
    if (item.Dest && 'name' in item.Dest) {
      console.log(destNames.has(item.Dest.name), item.Title);
    }
    if (item.Children) walk(item.Children);
  }
};
walk(doc.GetOutlines());

function tagPage(doc: Document, page: Page, headingText: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('tagPage: 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(headingText) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

Các vấn đề phổ biến và cách khắc phục

Document.GetStructTree() returns null. Tài liệu chưa được gắn thẻ — gọi Document.CreateStructTree() (hoặc Document.AutoTag()) trước khi tự tạo các phần tử bằng StructTreeRoot.Append() / StructElement.MarkContent().

Mục đề mục không nhảy tới trang đúng. OutlineItem.Dest phải đặt tên cho một đích mà thực sự tồn tại — kiểm tra chéo item.Dest.name against Document.GetNamedDestinations() trước khi lưu, như đã chỉ ra ở Bước 5.

Page.AddTOC() các mục trỏ tới trang sai. page trong mỗi mục mục lục là số trang của trang đích — xác nhận với page.Number trên mục tiêu thực tế Page, không phải một chỉ mục mảng được giả định.

Các dấu trang biến mất sau một lần gọi sau Document.SetOutlines() gọi. SetOutlines() thay thế toàn bộ cây dấu trang — đọc cây hiện tại bằng Document.GetOutlines() đầu tiên, sửa đổi mảng, sau đó truyền toàn bộ mảng trở lại nếu các dấu trang đang được thêm vào thay vì được thay thế.

Câu hỏi thường gặp

Liệu một dấu trang có thể mở sẵn ở trạng thái mở rộng không?

Có — đặt Open: true trên OutlineItem để các nút con của nút đó hiển thị mặc định trong bảng dấu trang.

Sự khác nhau giữa dấu trang và đích đặt tên là gì?

Một dấu trang (OutlineItem) là một mục hiển thị trong bảng điều hướng; một đích đặt tên (Document.GetNamedDestinations() / SetNamedDestination()) là một mục tiêu trang nội bộ, có thể tái sử dụng mà dấu trang, mục mục lục, hoặc chú thích liên kết đều có thể trỏ tới bằng tên.

Việc gắn thẻ tài liệu có ảnh hưởng đến cách hiển thị của nó không?

Không — cây cấu trúc (StructTreeRoot, StructElement) là một lớp logic song song mô tả thứ tự đọc và ngữ nghĩa; nó không thay đổi nội dung hiển thị của trang.

Tôi có thể lồng dấu trang không?

Có — đặt Children trên một OutlineItem thành một mảng các đối tượng OutlineItem tiếp theo để xây dựng một cây có thể thu gọn, đa cấp.

Xem thêm

• Core API
• Installation
• FAQ
• API Reference
• Aspose.PDF — Enterprise Knowledge Base