TypeScript에서 PDF 문서를 변환하는 방법
이 가이드는 Aspose.PDF FOSS for TypeScript를 사용하여 PDF 콘텐츠를 다른 형식으로 변환하는 방법을 보여줍니다. Page은 단일 페이지를 SVG 또는 래스터 이미지로 내보냅니다; Document은 전체 파일을 HTML, Markdown 또는 DOCX로 내보내며, 문서를 PDF/A로 검증하고 변환할 수 있습니다. 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하여 설치를 확인하십시오 — 이 줄은 패키지가 설치되면 오류 없이 해결되어야 합니다:
import { Document } from '@asposefoss/pdf';단계 2: 필요한 클래스 가져오기
Document을(를) 가져와 파일을 엽니다; 아래에서 사용되는 변환 메서드는 반환된 Document 및 Page 인스턴스에서 직접 호출되므로 추가 가져오기가 필요하지 않습니다:
import { Document } from '@asposefoss/pdf';3단계: 페이지를 SVG 또는 래스터 이미지로 변환
Page.ToSvg()은(는) 독립적인 <svg> 문자열을 반환합니다. Page.ToImage()는 페이지를 래스터 바이트로 렌더링합니다; scale은(는) PDF의 기본 72 DPI를 기준으로 하므로 scale: 2는 144 DPI에서 렌더링됩니다:
import { Document } from '@asposefoss/pdf';
const doc = Document.OpenFile('input.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const png = doc.Pages[0].ToImage({ scale: 2 }); // Uint8Array of PNG bytes @144 DPI
4단계: 문서를 HTML 또는 Markdown으로 변환
기본(semantic) 모드에서 Document.ToHtml()은 구조 트리의 내용을 제목과 단락으로 재배열합니다; 대신 { mode: 'fixed' }을 전달하면 각 페이지를 위치 지정된 SVG와 절대 위치 텍스트로 재생성합니다. Document.ToMarkdown()는 전체 문서에 대한 GFM Markdown을 생성합니다:
const semanticHtml = doc.ToHtml(); // reflowable markup, all pages
const fixedHtml = doc.ToHtml({ mode: 'fixed', fonts: 'embed' }); // positioned, fonts embedded
const markdown = doc.ToMarkdown(); // GFM Markdown, all pages
Semantic 모드는 Document.GetStructTree() / Document.CreateStructTree()에 의해 구축된 구조 트리를 읽습니다 — 태그가 지정되지 않은 문서에서는 휴리스틱 본문으로 대체되며, 이 경우 내보내기에서 제목 구조가 손실됩니다.
5단계: 문서를 DOCX로 변환
Document.ToDocx()은(는) 내용이 재배열되고 이미지가 내부에 패키징된 .docx 바이트를 반환합니다; 대신 { mode: 'textbox' }를 전달하면 재배열하지 않고 각 페이지의 고정된 기하학을 유지합니다:
const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' }); // .docx keeping each page's own geometry
단계 6: 유효성을 검증하고 PDF/A로 변환
Document.ValidatePdfA(level), Document.ValidatePdfX(level), 및 Document.ValidatePdfUa()는 문서가 지정된 표준을 통과했는지 여부를 설명하는 ValidationReport을 반환합니다. Document.ConvertToPdfA(level, opts)는 적용한 수정 사항과 아직 해결되지 않은 문제를 나열한 ConversionReport을 반환합니다. 실시간 문서를 변환하지 않은 상태로 저장해야 할 경우 Document.ExtractPages() 사본에서 변환을 실행하십시오:
const report = doc.ValidatePdfA('2b');
console.log(report.Passed);
const copy = doc.ExtractPages(doc.Pages.map((_, i) => i + 1));
const conversion = copy.ConvertToPdfA('2b');
console.log(conversion.applied.length, conversion.unresolved.length, conversion.passed);
copy.Save();일반적인 문제 및 해결책
Document.ToHtml() 제목 구조를 잃어버립니다. Semantic 모드는 구조 트리를 순회하므로, 태깅 단계 이후에 실행되어야 합니다 — 또는 Document.AutoTag() 또는 직접 작성한 태깅을 통해 StructTreeRoot.Append(). ToHtml() 다음과 같은 경우에 휴리스틱 본문으로 대체됩니다 GetStructTree() returns null.
ConvertToPdfA() 변환되지 않은 상태로 유지하려던 파일을 변경합니다. 복사본에서 변환을 실행합니다 Document.ExtractPages(), 그런 다음 복사본을 별도로 저장합니다 — ConvertToPdfA() 호출된 문서를 변경합니다.
ValidatePdfA() 첫 번째 실행 시 실패를 보고합니다. 일반적인 원인은 포함되지 않은 표준 글꼴과 누락된 /OutputIntent — 확인 report.Passed 및 개별 규칙 결과를 확인하여 어떤 조건이 충족되지 않았는지 확인하십시오.
Page.ToImage() 출력이 저해상도로 보입니다. scale 72 DPI를 기준으로 합니다; 이를 높이세요(예 { scale: 2 } 144 DPI의 경우) 인쇄 품질 출력용.
자주 묻는 질문
semantic과 fixed HTML 내보내기의 차이점은 무엇인가요?
Semantic mode는 문서의 구조 트리에서 마크업으로 재배열하여 어떤 너비에서도 브라우저에서 잘 읽히도록 합니다. Fixed mode는 각 페이지를 위치가 지정된 SVG와 절대 위치 텍스트로 재현하여 원래 레이아웃과 정확히 일치시킵니다.
Document.ToDocx()이(가) 원본 페이지 레이아웃을 보존합니까?
기본적으로 ToDocx()은(는) 콘텐츠를 재배열합니다. 대신 각 페이지의 고정된 기하학을 유지하려면 { mode: 'textbox' }을(를) 전달하세요.
문서를 변환하기 전에 PDF/A을(를) 충족하는지 어떻게 확인할 수 있나요?
Document.ValidatePdfA(level)을(를) 호출하고(예: '2b') 반환된 ValidationReport을(를) 검사하십시오 — 이는 문서를 수정하지 않고 현재 상태를 보고합니다.
페이지의 일부만 변환할 수 있나요?
예 — 먼저 Document 하위 집합을 Document.ExtractPages()으로 만들고, 그런 다음 해당 하위 집합에 변환 메서드(ToHtml(), ToDocx(), ConvertToPdfA() 등)를 호출합니다.
