Structure

Structure

이 페이지에서는 문서 탐색 및 논리적 구조에 대해 다룹니다: 개요(북마크), 목차, 명명된 목적지, 그리고 접근성 및 재배치를 위해 사용되는 태그된 구조 트리.

개요(북마크)

Document.GetOutlines()은 현재 개요 트리를 OutlineItem[]으로 반환합니다([]는 /Outlines가 없을 때); Document.SetOutlines()는 이를 교체합니다 — []를 전달하면 개요가 완전히 제거됩니다. 각 OutlineItem은 Title, Dest(페이지 번호 또는 명명된 목적지), 중첩을 위한 선택적 Children, 그리고 스타일(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()은 TOCEntry 객체 리스트를 페이지의 사각형에 렌더링합니다 — 각각은 title와 대상 page 번호를 가지고 — 줄 바꿈된 제목, 점선 리더, 오른쪽 정렬된 페이지 레이블과 함께. 이는 그려진 항목 수를 보고하는 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 또는 링크 주석이 명시적인 페이지 번호 대신 이름으로 참조할 수 있는 동일한 명명된 대상입니다.

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()는 페이지 레이아웃에서 — 글꼴 크기 클러스터링에 의한 제목, 텍스트 블록에 의한 단락, 규칙 기하학에 의한 표, 이미지별 /Figure 대 /Artifact 결정 — /StructTreeRoot을 추론하고 작성하며, 각 요소 종류에 대한 개수를 포함한 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()에 전달하십시오.

목차가 여러 페이지에 걸칠 수 있습니까?

예 — Page.AddTOC()의 옵션에 autoPaginate: true을 전달하거나, AddTOCResult.remainder를 확인하고 맞지 않은 부분에 대해 새 페이지에서 다시 AddTOC()을 호출하십시오.

PDF를 접근 가능하게(태그 지정) 만들려면 어떻게 해야 하나요?

Call Document.AutoTag()을 호출하면 페이지 레이아웃에서 제목, 단락, 표 및 그림을 추론합니다. 추가된 콘텐츠이거나 휴리스틱 결과를 수정해야 할 경우에는 StructTreeRoot.Append()와 StructElement.MarkContent()를 직접 사용하십시오.

페이지 번호 대상과 명명된 대상의 차이점은 무엇입니까?

페이지 번호 대상(PageDest)은 명시적인 1부터 시작하는 페이지를 지정합니다. 명명된 대상(NamedDest)은 뷰어가 문서 자체의 명명된 대상 테이블을 통해 해석하는 이름을 지정합니다 — 대상 페이지가 이동할 수 있을 때 유용합니다.

API Reference 요약

참조

• Aspose.PDF — Enterprise Documentation