TypeScript'te PDF Yapısı ile Çalışma

Bu kılavuz, TypeScript için Aspose.PDF FOSS ile PDF dosyalarında belge navigasyonu ve mantıksal yapı oluşturmayı gösterir: bir sayfada tıklanabilir içerik tablosu, belge seviyesinde yer imi taslağı, adlandırılmış hedefler ve erişilebilirlik için etiketli bir yapı ağacı. Node.js 22 veya daha yeni bir sürüm gerektirir.

Adım Adım Kılavuz

Adım 1: Paketi Kurun

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

Kurulumu, yeni bir TypeScript dosyasında Document sınıfını içe aktararak doğrulayın — paket yüklendikten sonra bu satır hatasız çözülmelidir:

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

Adım 2: Gerekli Sınıfları İçe Aktarın

Dosyayı açmak için Document içe aktarın ve Adım 4’te oluşturulan yer imi girişleri için OutlineItem kullanın:

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

Adım 3: İçindekiler Tablosu Ekle

Page.AddTOC(), bir dizi { title, page } girişi, bir sınırlayıcı rect ve stil seçenekleri alır; noktalı liderler ve hedef sayfalara tıklanabilir bağlantılar çizer:

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

Adım 4: Yer İmleri Ekle

Document.SetOutlines(), belgenin yer imi panelini bir dizi OutlineItem nesnesiyle değiştirir. Her öğe bir Dest (sayfa hedefi), stil (Color, Bold) ve katlanabilir bir ağaç için iç içe Children taşıyabilir:

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

Adım 5: Taslakları ve Adlandırılmış Hedefleri Oku

Document.GetOutlines(), mevcut yer imi ağacını döndürür. Document.GetNamedDestinations(), belgede kaydedilmiş tüm adlandırılmış hedefleri döndürür — her bir taslak hedefi ve İçindekiler Tablosu bağlantısının gerçekten gerçek bir sayfaya çözüldüğünü doğrulamak için faydalıdır:

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

Adım 6: Etiketli Bir Yapı Ağacı Oluştur

Document.GetStructTree() mevcut yapı ağacını döndürür (veya belge etiketlenmemişse null). StructTreeRoot.Append(tag), 'H2' veya 'P' gibi bir alt öğe ekler ve bir StructElement döndürür, ve StructElement.MarkContent(page, quad) bu öğeyi tanımladığı sayfa içeriğiyle ilişkilendirir:

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

Yaygın Sorunlar ve Çözümler

Document.GetStructTree() returns null. Belge henüz etiketlenmedi — çağır Document.CreateStructTree() (veya Document.AutoTag()) el ile öğeler oluşturulmadan önce StructTreeRoot.Append() / StructElement.MarkContent().

Bir anahat öğesi doğru sayfaya atlamıyor. OutlineItem.Dest gerçekten var olan bir hedef adı vermeli — çapraz kontrol edin item.Dest.name against Document.GetNamedDestinations() kaydetmeden önce, Adım 5’te gösterildiği gibi.

Page.AddTOC() girdiler yanlış sayfaya işaret ediyor. page her TOC girdisindeki hedef sayfanın kendi sayfa numarasıdır — bunu karşılaştırarak doğrulayın page.Number gerçek hedefte Page, varsayılan bir dizi indeksi değil.

Yer imleri daha sonraki bir Document.SetOutlines() çağrı. SetOutlines() tüm yer imi ağacını değiştirir — mevcut ağacı şununla okuyun Document.GetOutlines() ilk önce diziyi değiştirin, ardından yer imleri değiştirilmeyip ekleniyorsa tüm diziyi geri gönderin.

Sıkça Sorulan Sorular

Yer imi zaten genişletilmiş olarak açılabilir mi?

Evet — OutlineItem üzerindeki Open: true ayarlayarak, o düğümün alt öğelerinin yer imi panelinde varsayılan olarak görünür olmasını sağlayabilirsiniz.

Yer imi ile named destination arasındaki fark nedir?

Bir yer imi (OutlineItem) navigasyon panelinde görünen bir giriştir; bir named destination (Document.GetNamedDestinations() / SetNamedDestination()) ise bir yer imi, bir TOC girişi veya bir bağlantı açıklaması tarafından isimle işaretlenebilen, dahili, yeniden kullanılabilir bir sayfa hedefidir.

Bir belgeye etiket eklemek görünümünü etkiler mi?

Hayır — bir yapı ağacı (StructTreeRoot, StructElement) okuma sırasını ve anlamsallığı tanımlayan paralel bir mantıksal katmandır; sayfanın görünen içeriğini değiştirmez.

Yer imlerini iç içe yerleştirebilir miyim?

Evet — bir OutlineItem üzerindeki Children değerini ek OutlineItem nesnelerinin bir dizisine ayarlayarak, katlanabilir çok seviyeli bir ağaç oluşturabilirsiniz.