Core Document 및 Page API는 Aspose.PDF FOSS for TypeScript에 있습니다

소개

TypeScript용 Aspose.PDF FOSS의 모든 기능은 두 클래스, Document와 Page을 통해 접근합니다. Document는 페이지 컬렉션과 문서 수준의 모든 것을 담당합니다 — 메타데이터, 북마크, 페이지 라벨, 저장/로드 — 반면 doc.Pages의 각 Page는 해당 페이지에 한정된 모든 것을 담당합니다: 콘텐츠, 주석, 폼 필드. 이 두 클래스를 익히면, 라이브러리의 나머지 영역 — 변환, 주석, 폼, 보안 — 은 실제로 동일한 두 객체에 대한 추가 메서드에 불과합니다.

이 게시물은 해당 핵심 영역 중 introductory post에서 간략히 언급한 부분을 자세히 살펴봅니다: 다른 문서로부터 문서를 조합하기, 빈 페이지를 생성하기, 탐색을 위한 북마크 트리 추가하기, 접근성을 위한 콘텐츠 태깅하기. 네 가지 모두 별도의 모듈을 임포트할 필요 없이 단순 메서드 호출이며, @asposefoss/pdf 패키지 자체 외에 추가 의존성이 없습니다.

PDF 파이프라인이 “파일 하나 열고, 수정하고, 저장한다”를 넘어설 때 등장하는 작업입니다: 여러 소스의 보고서를 하나의 문서로 결합하기, 템플릿 대신 프로그래밍 방식으로 페이지 생성하기, 그리고 출력물을 시각적으로만 맞추는 것이 아니라 탐색 가능하고 접근 가능하게 만들기.

포함 내용

문서 조립 및 재구성

Document.Split()는 문서를 페이지 순서대로 각 페이지마다 새로운 단일 페이지 Document 하나씩으로 나눕니다. Document.ExtractPages()는 지정된 1부터 시작하는 페이지 번호 집합을 새로운 독립형 Document에 복사하며, 주어진 순서대로 복사합니다 — 같은 페이지를 여러 번 포함시킬 수 있습니다. 한 문서의 페이지를 다른 문서로 복사할 수도 있습니다: Document.Append()는 소스 문서의 모든 페이지를 대상 문서 끝에 복사하고, Document.InsertPage()는 특정 1 기반 위치에 단일 페이지를 문서 간에 복사합니다.

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

const report = Document.OpenFile('report.pdf');

const parts = report.Split();                      // one Document per page
const chapter = report.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

const cover = Document.OpenFile('cover.pdf');
report.InsertPage(1, cover.Pages[0]);               // copy a single page across documents
report.Append(chapter);                             // copy chapter's pages onto report

report.WriteTo('assembled.pdf');

여러 문서를 Document.Merge()를 한 번 호출하여 하나로 결합할 수도 있으며, 이는 전달된 모든 문서의 각 페이지 복사본을 순서대로 사용하여 새로운 Document를 생성합니다.

페이지를 처음부터 만들기

Document.New()는 아무것도 없는 상태에서 문서를 생성합니다: 포맷이 생략되면 페이지가 0개이며, 포맷이 지정되면 해당 PageFormat의 빈 페이지 1장을 생성합니다. 추가 빈 페이지는 Document.AddPage()에서 제공되며, 여기서는 PageFormat(또는 크기를 복사할 기존 Page)도 받을 수 있습니다. 텍스트는 Page.AddText()를 사용하여 페이지에 그려지며, PDF 사용자 공간의 (x, y) 좌표에 배치됩니다.

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

const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

북마크 및 문서 탐색

문서 개요(대부분의 PDF 리더에서 페이지 옆에 표시되는 북마크 패널)는 Document.GetOutlines()로 읽어들인 뒤, Document.SetOutlines()으로 전체 교체됩니다. 각각은 OutlineItem 값들의 트리를 사용합니다. 각 OutlineItem에는 Title, Dest 목적지, 선택적으로 중첩 항목을 위한 Children이 포함되며, Open(기본적으로 확장) 및 Bold과 같은 표시 힌트도 포함됩니다.

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

const items: OutlineItem[] = [
  { Title: 'Introduction', Dest: { name: 'intro' } },
  {
    Title: 'Chapters',
    Open: true,
    Children: [
      { Title: 'Chapter 1', Dest: { name: 'ch1' } },
      { Title: 'Chapter 2', Dest: { name: 'ch2' } },
    ],
  },
];
doc.SetOutlines(items);

이와 같이 명명된 목적지({ name: 'intro' })는 문서의 명명된 목적지 테이블을 통해 해석되며, 페이지 내용과 연결되지 않은 목적지를 북마크가 가리킬 필요가 있을 때 Document.GetNamedDestinations()과 Document.SetNamedDestination()가 이를 직접 관리합니다.

구조화된 텍스트 및 접근성 태깅

Document.GetStructTree()는 문서의 논리 구조 트리를 반환합니다(문서에 태그가 없을 경우 null). Document.CreateStructTree()는 이를 구축하여 문서를 Tagged 상태로 표시합니다. 구조 트리가 존재하면, Page.GetStructuredText()는 페이지의 텍스트를 TextBlock 값으로 반환합니다—이미 라인 및 문단과 유사한 블록으로 그룹화된 위치 지정 조각들—이는 수작업 태깅 단계가 사용하는 입력으로, 블록을 순회하면서 헤딩인지 본문 텍스트인지 판단하고 해당 요소를 트리에 추가합니다.

function handTagPage(doc: Document, page: Page, heading: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('handTagPage: 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(heading) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

태그가 지정된 구조 트리는 하위 기능들이 기반으로 삼는 것입니다: 의미론적 HTML 내보내기는 일반적인 휴리스틱 레이아웃으로 되돌아가는 대신 여기서 재배치되며, Document.ValidatePdfUa()는 태그가 존재함에 의존하는 PDF/UA 접근성 표준의 하위 집합에 대해 문서를 검사합니다.

빠른 시작

패키지를 설치한 후 문서를 열고, 페이지의 일부를 추출하여 재조합한 뒤 결과를 저장합니다:

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

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

const doc = Document.OpenFile('report.pdf');

const chapter = doc.ExtractPages([3, 4, 5]);   // subset (1-based, repeats allowed) as a new Document
const cover = Document.OpenFile('cover.pdf');

doc.InsertPage(1, cover.Pages[0]);             // copy a single page across documents
doc.Append(chapter);                           // copy chapter's pages onto doc

doc.WriteTo('assembled.pdf');

지원되는 형식

오픈 소스 및 라이선스

Aspose.PDF FOSS for TypeScript은 MIT 라이선스로 출시되었으며, 소스는 GitHub에 공개됩니다. 평가 워터마크, 사용 제한, 별도의 라이선스 파일 관리가 없으며, 이 라이브러리는 로열티 없이 상용 제품에 사용할 수 있습니다.

이 패키지는 현재 버전 0.1.0이며, 활발한 초기 단계 개발을 반영합니다. Node.js (>=22)만이 유일한 런타임 요구 사항이며, 이 패키지는 다른 서드파티 의존성이 없습니다.

시작하기

• 시작하기
• 개발자 가이드
• KB 기사
• API Reference

관련 리소스

• Aspose.PDF Enterprise Product Family
• Aspose.PDF — Enterprise Blog