Cara Bekerja dengan Struktur PDF di TypeScript

Panduan ini menunjukkan cara membangun navigasi dokumen dan struktur logis dalam file PDF dengan Aspose.PDF FOSS untuk TypeScript: tabel isi yang dapat diklik pada sebuah halaman, outline bookmark tingkat dokumen, tujuan bernama, dan pohon struktur bertanda untuk aksesibilitas. Diperlukan Node.js 22 atau lebih baru.

Panduan Langkah demi Langkah

Langkah 1: Pasang Paket

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

Verifikasi instalasi dengan mengimpor kelas Document dalam file TypeScript baru — baris ini harus dapat diselesaikan tanpa error setelah paket dipasang:

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

Langkah 2: Impor Kelas yang Diperlukan

Impor Document untuk membuka file dan OutlineItem untuk entri bookmark yang dibangun pada Langkah 4:

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

Langkah 3: Tambahkan Daftar Isi

Page.AddTOC() menerima sebuah array entri { title, page }, sebuah rect pembatas, dan opsi gaya; ia menggambar pemimpin titik-titik dan tautan yang dapat diklik ke halaman target:

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

Langkah 4: Tambahkan Bookmark

Document.SetOutlines() menggantikan panel bookmark dokumen dengan sebuah array objek OutlineItem. Setiap item dapat membawa Dest (tujuan halaman), styling (Color, Bold), dan Children bersarang untuk pohon yang dapat dilipat:

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

Langkah 5: Baca Garis Besar dan Tujuan Bernama

Document.GetOutlines() mengembalikan pohon bookmark saat ini. Document.GetNamedDestinations() mengembalikan setiap tujuan bernama yang terdaftar pada dokumen — berguna untuk memverifikasi bahwa setiap target outline dan tautan TOC memang mengarah ke halaman yang nyata:

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

Langkah 6: Bangun Pohon Struktur Bertag

Document.GetStructTree() mengembalikan struktur pohon yang ada (atau null jika dokumen belum ditandai). StructTreeRoot.Append(tag) menambahkan elemen anak seperti 'H2' atau 'P' dan mengembalikan StructElement, dan StructElement.MarkContent(page, quad) mengaitkan elemen tersebut dengan konten halaman yang dijelaskannya:

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

Masalah Umum dan Solusinya

Document.GetStructTree() returns null. Dokumen belum ditandai — panggil Document.CreateStructTree() (atau Document.AutoTag()) sebelum menulis manual elemen dengan StructTreeRoot.Append() / StructElement.MarkContent().

Item kerangka tidak melompat ke halaman yang tepat. OutlineItem.Dest harus memberi nama tujuan yang memang ada — periksa silang item.Dest.name against Document.GetNamedDestinations() sebelum menyimpan, seperti yang ditunjukkan pada Langkah 5.

Page.AddTOC() entri mengarah ke halaman yang salah. page di setiap entri TOC adalah nomor halaman sendiri dari halaman target — konfirmasikan dengan page.Number pada target sebenarnya Page, bukan indeks array yang diasumsikan.

Penanda menghilang setelah yang berikutnya Document.SetOutlines() panggilan. SetOutlines() menggantikan seluruh pohon penanda — baca pohon saat ini dengan Document.GetOutlines() pertama, ubah array, lalu kirim seluruh array kembali jika penanda sedang ditambahkan bukan diganti.

Pertanyaan yang Sering Diajukan

Apakah bookmark dapat terbuka dengan keadaan sudah diperluas?

Ya — atur Open: true pada OutlineItem agar anak node tersebut terlihat secara default di panel bookmark.

Apa perbedaan antara bookmark dan tujuan bernama?

Bookmark (OutlineItem) adalah entri yang terlihat di panel navigasi; tujuan bernama (Document.GetNamedDestinations() / SetNamedDestination()) adalah target halaman internal yang dapat digunakan kembali yang dapat dituju oleh bookmark, entri TOC, atau anotasi tautan dengan menggunakan nama.

Apakah menandai dokumen memengaruhi tampilannya?

Tidak — struktur pohon (StructTreeRoot, StructElement) adalah lapisan logis paralel yang menggambarkan urutan baca dan semantik; ia tidak mengubah konten yang terlihat pada halaman.

Bisakah saya menumpuk bookmark?

Ya — atur Children pada sebuah OutlineItem menjadi array dari objek OutlineItem lanjutan untuk membangun pohon berlapis yang dapat dilipat.