Structure

Structure

Trang này bao gồm việc điều hướng tài liệu và cấu trúc logic: đề mục (bookmarks), mục lục, đích được đặt tên, và cây cấu trúc có thẻ được sử dụng cho khả năng truy cập và việc tái bố trí.

Đề mục (Bookmarks)

Document.GetOutlines() trả về cây đề mục hiện tại dưới dạng OutlineItem[] ([] khi không có /Outlines); Document.SetOutlines() thay thế nó — truyền [] sẽ xóa hoàn toàn đề mục. Mỗi OutlineItem có một Title, một Dest (một số trang hoặc một đích được đặt tên), tùy chọn Children để lồng nhau, và định dạng (Color, Bold, Italic, Open).

const items: OutlineItem[] = sections.map((s) => {
  const item: OutlineItem = { Title: s.title, Dest: { name: s.dest } };
  if (s.subtype === 'sales') {
    item.Open = true;
    item.Children = ['Pasta', 'Pizza', 'Antipasti']
      .map((cat) => ({ Title: cat, Dest: { name: s.dest } }));
  }
  return item;
});
doc.SetOutlines(items);

Mục lục

Page.AddTOC() vẽ một danh sách các đối tượng TOCEntry — mỗi đối tượng có một title và một số page mục tiêu — vào một hình chữ nhật trên trang, với tiêu đề được gói lại, dấu chấm nối, và nhãn trang căn phải. Nó trả về một AddTOCResult báo cáo số mục đã được vẽ và, khi hộp quá nhỏ, remainder không vừa.

page.AddTOC(
  sections.map((s, i) => ({ title: `${i + 1}. ${s.title}`, page: s.page.Number })),
  [72, 160, 400, 400],
  { font: 'Helvetica', fontSize: 13, rowGap: 18 },
);

Đích được đặt tên

Document.GetNamedDestinations() trả về mọi điểm đến có tên — hợp nhất cây tên /Names /Dests và từ điển /Dests kế thừa — dưới dạng các cặp { name, dest }, trong đó dest là một PageDest ({ page, view }). Đây là cùng các mục tiêu có tên mà một OutlineItem.Dest hoặc chú thích liên kết có thể tham chiếu bằng tên thay vì số trang cụ thể.

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));
for (const { name, dest } of doc.GetNamedDestinations()) {
  console.log(name, '-> page', dest.page);
}

Cây Cấu trúc Đánh dấu

Document.AutoTag() suy ra và tạo một /StructTreeRoot từ bố cục trang — tiêu đề dựa trên cụm kích thước phông chữ, đoạn văn dựa trên khối văn bản, bảng dựa trên hình học đường kẻ, và quyết định /Figure vs. /Artifact cho mỗi hình ảnh — và trả về một AutoTagReport với số lượng cho mỗi loại phần tử. Document.GetStructTree() đọc lại StructTreeRoot kết quả, hoặc null khi tài liệu không có thẻ.

const report = doc.AutoTag({ lang: 'en-US', title: 'Quarterly Report', tables: true });
console.log(report.headings, report.paragraphs, report.tables, report.figures);

const tree = doc.GetStructTree();
console.log(tree ? tree.GetText() : '(no structure tree)');

Nội dung được thêm sau khi AutoTag() đã chạy — ví dụ một trang được lấp đầy sau đó — không được bao phủ bởi lần chạy đó và sẽ không được gắn thẻ đôi. StructTreeRoot.Append() và StructElement.MarkContent() là API tạo thủ công bên cạnh phương pháp heuristic: Append() thêm một phần tử con của loại được chỉ định, và MarkContent() đánh dấu một vùng trang là thuộc về phần tử đó.

Mẹo và Thực hành Tốt nhất

• Chạy Document.AutoTag() một lần, sau khi nội dung trang đã hoàn thiện — nó không gắn thẻ lại nội dung được thêm sau, vì vậy hãy tự gắn thẻ bất kỳ nội dung nào được thêm sau bằng StructTreeRoot.Append() / StructElement.MarkContent().
• Chuyển opts.title cho AutoTag() — nó cũng đặt /ViewerPreferences /DisplayDocTitle, mà PDF/UA yêu cầu cùng với tiêu đề tài liệu.
• Một OutlineItem.Dest có thể nhắm mục tiêu vào một trang cụ thể hoặc một điểm đến có tên ({ name: '...' }) — hãy sử dụng các điểm đến có tên khi số trang mục tiêu có thể thay đổi khi nội dung thay đổi.
• Kiểm tra AddTOCResult.remainder khi tự động phân trang bị tắt — hộp mục lục quá nhỏ cho mọi mục nhập sẽ dừng vẽ im lặng thay vì tràn ra ngoài hộp.

Các vấn đề thường gặp

FAQ

Làm thế nào để thêm dấu trang vào PDF?

Tạo một mảng các đối tượng OutlineItem (Title, Dest, tùy chọn Children) và truyền nó cho Document.SetOutlines().

Mục lục có thể trải qua nhiều trang không?

Có — truyền autoPaginate: true trong tùy chọn của Page.AddTOC(), hoặc kiểm tra AddTOCResult.remainder và gọi lại AddTOC() trên một trang mới cho những gì không vừa.

Làm thế nào để làm cho PDF có thể truy cập được (được gắn thẻ)?

Gọi Document.AutoTag(), công cụ này suy luận tiêu đề, đoạn văn, bảng và hình ảnh từ bố cục trang. Đối với nội dung được thêm vào sau, hoặc khi kết quả heuristic cần chỉnh sửa, hãy sử dụng StructTreeRoot.Append() và StructElement.MarkContent() trực tiếp.

Sự khác nhau giữa điểm đến theo số trang và điểm đến có tên là gì?

Một điểm đến theo số trang (PageDest) chỉ tới một trang cụ thể được đánh số bắt đầu từ 1. Một điểm đến có tên (NamedDest) chỉ tới một tên mà trình xem sẽ giải quyết thông qua các bảng điểm đến có tên của tài liệu — hữu ích khi trang đích có thể di chuyển.

API Reference Tóm tắt

Xem thêm

• Aspose.PDF — Enterprise Documentation