Structure

Structure

หน้านี้ครอบคลุมการนำทางเอกสารและโครงสร้างเชิงตรรกะ: outlines (bookmarks), tables of contents, named destinations, และ tagged structure tree ที่ใช้สำหรับ accessibility และ reflow.

เค้าโครง (บุ๊กมาร์ก)

Document.GetOutlines() คืนค่าโครงร่างปัจจุบันเป็น OutlineItem[] ([] เมื่อไม่มี /Outlines); Document.SetOutlines() แทนที่มัน — การส่ง [] จะลบโครงร่างออกโดยสิ้นเชิง. แต่ละ OutlineItem มี Title, Dest (หมายเลขหน้า หรือ named destination), ตัวเลือก Children สำหรับ nesting, และ styling (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);

สารบัญ

Page.AddTOC() renders รายการของ TOCEntry objects — แต่ละที่มี title และ target page number — ลงในสี่เหลี่ยมบนหน้า, พร้อมชื่อเรื่องที่ห่อ, dot leaders, และ right-aligned page labels. มันคืนค่า AddTOCResult ที่รายงานจำนวนรายการที่วาดและ, เมื่อกล่องเล็กเกิน, remainder ที่ไม่พอดี.

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 },
);

ปลายทางที่กำหนดชื่อ

Document.GetNamedDestinations() คืนค่าการกำหนดปลายทางที่ตั้งชื่อทั้งหมด — การผสานต้นไม้ชื่อ /Names /Dests กับพจนานุกรม /Dests แบบดั้งเดิม — เป็นคู่ { name, dest } ที่ dest เป็น PageDest ({ page, view }) เหล่านี้เป็นเป้าหมายที่ตั้งชื่อเดียวกันที่ OutlineItem.Dest หรือ annotation ลิงก์สามารถอ้างอิงโดยใช้ชื่อแทนหมายเลขหน้าโดยตรง.

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

ต้นไม้โครงสร้างที่มีแท็ก

Document.AutoTag() สรุปและสร้าง /StructTreeRoot จากการจัดหน้า — หัวเรื่องโดยการจัดกลุ่มตามขนาดฟอนต์, ย่อหน้าด้วยบล็อกข้อความ, ตารางด้วยเรขาคณิตของเส้นกริด, และการตัดสินใจ /Figure vs. /Artifact ต่อภาพแต่ละภาพ — และคืนค่า AutoTagReport พร้อมจำนวนของแต่ละประเภทองค์ประกอบ. Document.GetStructTree() อ่านกลับ StructTreeRoot ที่ได้, หรือ null เมื่อเอกสารไม่มีแท็ก.

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

เนื้อหาที่เพิ่มหลังจากที่ AutoTag() ทำงานแล้ว — เช่น หน้าที่เติมเต็มภายหลัง — จะไม่ได้รับการครอบคลุมโดยการทำงานนั้นและจะไม่ทำการแท็กซ้ำ. StructTreeRoot.Append() และ StructElement.MarkContent() คือ API การเขียนด้วยตนเองเคียงคู่กับวิธีเชิงอรรถ: Append() เพิ่มองค์ประกอบลูกของชนิดที่กำหนด, และ MarkContent() ทำเครื่องหมายบริเวณหน้าให้เป็นขององค์ประกอบนั้น.

เคล็ดลับและแนวปฏิบัติที่ดีที่สุด

• เรียกใช้ Document.AutoTag() ครั้งเดียว หลังจากเนื้อหาหน้าสิ้นสุดแล้ว — มันจะไม่ทำการแท็กใหม่สำหรับเนื้อหาที่เพิ่มภายหลัง, ดังนั้นให้ทำการแท็กด้วยมือสำหรับสิ่งที่เพิ่มต่อมาด้วย StructTreeRoot.Append() / StructElement.MarkContent().
• ส่ง opts.title ไปยัง AutoTag() — มันยังตั้งค่า /ViewerPreferences /DisplayDocTitle ด้วย, ซึ่ง PDF/UA ต้องการพร้อมกับชื่อเอกสาร.
• OutlineItem.Dest สามารถกำหนดเป้าหมายได้ทั้งหน้าแบบชัดเจนหรือปลายทางที่ตั้งชื่อ ({ name: '...' }) — ใช้ปลายทางที่ตั้งชื่อเมื่อหมายเลขหน้าที่เป็นเป้าหมายอาจเปลี่ยนแปลงตามการเปลี่ยนแปลงของเนื้อหา.
• ตรวจสอบ AddTOCResult.remainder เมื่อปิดการแบ่งหน้าอัตโนมัติ — กล่องสารบรรณที่เล็กเกินกว่าทุกรายการจะหยุดวาดอย่างเงียบ ๆ แทนที่จะล้นออกจากกล่อง.

ปัญหาทั่วไป

FAQ

ฉันจะเพิ่มที่คั่นหน้าใน PDF อย่างไร?

สร้างอาเรย์ของอ็อบเจ็กต์ OutlineItem (Title, Dest, Children ที่เป็นทางเลือก) และส่งไปยัง Document.SetOutlines().

สารบรรณสามารถขยายหลายหน้าได้หรือไม่?

ได้ — ส่ง autoPaginate: true ในตัวเลือกของ Page.AddTOC(), หรือ ตรวจสอบ AddTOCResult.remainder และเรียก AddTOC() อีกครั้งในหน้ใหม่สำหรับสิ่งที่ไม่พอดี.

ฉันจะทำให้ PDF สามารถเข้าถึงได้ (tagged) อย่างไร?

เรียก Document.AutoTag() ซึ่งจะสรุปหัวข้อ ย่อหน้า ตาราง และรูปภาพจากการจัดหน้า สำหรับเนื้อหาที่เพิ่มเข้ามาภายหลัง หรือเมื่อผลลัพธ์เชิงปริมาณต้องการการแก้ไข ให้ใช้ StructTreeRoot.Append() และ StructElement.MarkContent() โดยตรง.

ความแตกต่างระหว่างปลายทางแบบหมายเลขหน้าและปลายทางที่ตั้งชื่อคืออะไร?

ปลายทางแบบหมายเลขหน้า (PageDest) ชี้ไปยังหน้าที่ระบุอย่างชัดเจนโดยเริ่มจาก 1. ปลายทางที่ตั้งชื่อ (NamedDest) ชี้ไปยังชื่อที่โปรแกรมดูเอกสารจะค้นหาในตารางปลายทางที่ตั้งชื่อของเอกสารเอง — มีประโยชน์เมื่อหน้าที่เป็นเป้าหมายอาจย้ายตำแหน่ง.

API Reference สรุป

ดูเพิ่มเติม

• Aspose.PDF — Enterprise Documentation