TypeScript에서 PDF 구조를 사용하는 방법

TypeScript에서 PDF 구조를 사용하는 방법

이 가이드는 TypeScript용 Aspose.PDF FOSS를 사용하여 PDF 파일에 문서 탐색 및 논리 구조를 구축하는 방법을 보여줍니다: 페이지 내 클릭 가능한 목차, 문서 수준 북마크 개요, 명명된 목적지, 접근성을 위한 태그된 구조 트리. Node.js 22 이상이 필요합니다.

단계별 가이드

1단계: 패키지 설치

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

패키지를 설치한 후 새 TypeScript 파일에 Document 클래스를 가져와 설치를 확인하십시오 — 패키지가 설치되면 이 줄이 오류 없이 해결됩니다:

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

2단계: 필요한 클래스 가져오기

파일을 열기 위해 Document을(를) 가져오고, Step 4에서 만든 북마크 항목에 대해 OutlineItem을(를) 사용합니다:

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

Step 3: 목차 추가

Page.AddTOC()은(는) { title, page } 항목 배열, 경계 rect, 그리고 스타일 옵션을 받아들이며; 점선 리더와 대상 페이지로 연결되는 클릭 가능한 링크를 그립니다:

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

Step 4: 북마크 추가

Document.SetOutlines()은(는) 문서의 북마크 패널을 OutlineItem 객체 배열로 교체합니다. 각 항목은 Dest(페이지 목적지), 스타일(Color, Bold) 및 접을 수 있는 트리를 위한 중첩 Children를 가질 수 있습니다:

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

Step 5: 개요 및 명명된 목적지 읽기

Document.GetOutlines()은(는) 현재 북마크 트리를 반환합니다. Document.GetNamedDestinations()은(는) 문서에 등록된 모든 명명된 목적지를 반환합니다 — 각 개요 대상과 목차 링크가 실제 페이지로 올바르게 연결되는지 확인하는 데 유용합니다:

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

Step 6: 태그 구조 트리 구축

Document.GetStructTree()은(는) 기존 구조 트리를 반환합니다(문서에 태그가 없을 경우 null). StructTreeRoot.Append(tag)는 'H2' 또는 'P'와 같은 자식 요소를 추가하고 StructElement를 반환하며, StructElement.MarkContent(page, quad)는 해당 요소를 설명하는 페이지 콘텐츠와 연결합니다:

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

일반적인 문제 및 해결책

Document.GetStructTree() returns null. 문서에 아직 태그가 지정되지 않았습니다 — 호출 Document.CreateStructTree() (또는 Document.AutoTag()) 수동으로 요소를 작성하기 전에 StructTreeRoot.Append() / StructElement.MarkContent().

개요 항목이 올바른 페이지로 이동하지 않습니다. OutlineItem.Dest 실제로 존재하는 목적지를 지정해야 합니다 — 교차 확인 item.Dest.name against Document.GetNamedDestinations() 저장하기 전에, 5단계에 표시된 대로.

Page.AddTOC() 항목이 잘못된 페이지를 가리키고 있습니다. page 각 TOC 항목에 있는 것은 대상 페이지 자체의 페이지 번호입니다 — 대조하여 확인하십시오 page.Number 실제 대상에서 Page, 가정된 배열 인덱스가 아닙니다.

북마크는 나중에 사라집니다 Document.SetOutlines() 호출. SetOutlines() 전체 북마크 트리를 교체합니다 — 현재 트리를 다음으로 읽으세요 Document.GetOutlines() 먼저 배열을 수정하고, 북마크를 교체하는 것이 아니라 추가하는 경우 전체 배열을 다시 전달하십시오.

자주 묻는 질문

북마크를 이미 확장된 상태로 열 수 있나요?

예 — OutlineItem에 Open: true를 설정하면 해당 노드의 자식이 북마크 패널에 기본적으로 표시됩니다.

북마크와 명명된 목적지의 차이점은 무엇인가요?

북마크(OutlineItem)는 탐색 패널에 표시되는 항목이며; 명명된 목적지(Document.GetNamedDestinations() / SetNamedDestination())는 북마크, 목차 항목, 혹은 링크 어노테이션이 이름으로 지정할 수 있는 내부 재사용 가능한 페이지 대상입니다.

문서에 태그를 지정하면 표시 방식에 영향을 줍니까?

아니요 — 구조 트리(StructTreeRoot, StructElement)는 읽기 순서와 의미를 설명하는 병렬 논리 레이어이며, 페이지의 보이는 내용은 변경하지 않습니다.

북마크를 중첩할 수 있나요?

예 — OutlineItem에 Children를 추가하여 추가 OutlineItem 객체들의 배열로 설정하면, 접을 수 있는 다단계 트리를 만들 수 있습니다.

참조

 한국어