介绍

introductory post 展示了转换的基本形态:Document.ToHtml()、Document.ToMarkdown() 和 Document.ToDocx(),每个在不传入参数的情况下调用,以获得合理的默认值。所有这些方法都接受一个选项对象,用以改变实际输出——语义化标记与像素精确复制、可重排的 Word 文档与逐页精确布局的文档之间的选择。

本文涵盖了这些选项,以及引言中完全未涉及的一个转换方向:针对 PDF/A、PDF/X 和 PDF/UA 标准对文档进行验证,并对其进行修正,使其符合 Document.ConvertToPdfA() 及其相关标准。


包含内容

HTML 导出:语义 vs 固定

Document.ToHtml() 在未提供选项的情况下会遍历文档的结构树并输出可重排的标记——在任何宽度的浏览器中都能自然阅读的标题和段落。该模式依赖于文档先被标记(Document.CreateStructTree() 或等效的标记过程);如果没有结构树,导出将回退为普通的启发式正文,而非真正的语义化标记。传入 { mode: 'fixed', fonts: 'embed' } 则完全切换为另一种渲染策略:每页被转换为定位的 SVG 并以绝对定位的文本呈现,所有可嵌入的字体程序都以内嵌的 base64 WOFF @font-face 形式嵌入,从而即使阅读器未安装这些字体,页面外观也保持一致。

// Semantic mode reflows from the structure tree, so this must run after the
// tagging pass: ToHtml falls back to a heuristic body when GetStructTree() is
// null, and the export loses its heading structure silently.
const semantic = doc.ToHtml();
const fixed = doc.ToHtml({ mode: 'fixed', fonts: 'embed' });

这两种输出服务于不同的目的:语义化的 HTML 适用于在网页上阅读或重新发布内容,而固定的 HTML 则适用于需要在浏览器中保持页面精确视觉布局不变的场景。

Word 和向量导出

Document.ToDocx() 在未提供选项的情况下调用会生成可重排的 .docx:段落和图像,可由文字处理器重新换行并像普通文档一样编辑。改为传入 { mode: 'textbox' } 则保留每页自身的几何布局,将内容放入固定文本框中,而不是让其重排——更接近忠实的视觉副本而非可编辑文档。Page.ToSvg() 将单页渲染为独立的 <svg> 字符串,当需要某页的向量、分辨率无关的副本而非光栅图像时非常有用。

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

const doc = Document.OpenFile('in.pdf');
const svg = doc.Pages[0].ToSvg();               // standalone <svg> string
const docx = doc.ToDocx();                       // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' });   // .docx keeping each page's own geometry

验证并转换为 PDF/A、PDF/X 和 PDF/UA

Document.ValidatePdfA()、Document.ValidatePdfX() 和 Document.ValidatePdfUa() 分别将文档与相应标准的精心挑选、机器可检验的子集进行对照——PDF/A(ISO 19005)用于长期归档,PDF/X(ISO 15930)用于印刷生产,PDF/UA(ISO 14289-1)用于可访问性——并返回一个带有 Passed 标志的 ValidationReport,概述结果。Document.ConvertToPdfA()(以及等价的 ConvertToPdfX()/ConvertToPdfUa())尝试将文档修复至该级别,然后重新验证,返回一个 ConversionReport,列出实际应用的操作以及仍未解决的问题。

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

const doc = Document.OpenFile('in.pdf');
const pdfa = doc.ValidatePdfA('2b');
console.log(`validate: PDF/A-2b ${pdfa.Passed ? 'passes' : 'fails'}`);

// Conversion runs against a copy: the live document is still saved
// unconverted, so ConvertToPdfA must never touch it directly.
const pages = doc.Pages;
const allPages: number[] = [];
for (let i = 1; i <= pages.length; i++) allPages.push(i);
const copy = doc.ExtractPages(allPages);
const conversion = copy.ConvertToPdfA('2b');

console.log(`pdf/a convert: ${conversion.applied.length} action(s) applied, `
  + `${conversion.unresolved.length} unresolved`);
console.log(`result: ${conversion.passed ? 'passes' : 'still fails'} PDF/A-2b`);

转换并不保证一次就能完全符合规范——导致仍然失败的常见原因包括未嵌入的字体和缺失的输出意图,这两者都会在 conversion.unresolved 中显示。


快速入门

安装该软件包,然后将单页渲染为 SVG,将整个文档渲染为可重排的 HTML 和 DOCX:

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('in.pdf');

const svg = doc.Pages[0].ToSvg();   // standalone <svg> string
const html = doc.ToHtml();          // reflowable HTML (falls back without a structure tree)
const docx = doc.ToDocx();          // .docx bytes, reflowed, images in the package

// fs.writeFileSync('page1.svg', svg);
// fs.writeFileSync('out.html', html);
// fs.writeFileSync('out.docx', docx);

支持的格式

格式扩展名读取写入
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

开源与许可

Aspose.PDF FOSS for TypeScript 在 MIT 许可证下发布,源码已发布在 GitHub。没有评估水印、使用限制或需要管理的单独许可证文件,且该库可在商业产品中使用且无需支付版税。

该软件包当前版本为 0.1.0,反映了积极的早期开发阶段。Node.js (>=22) 是唯一的运行时要求,且该软件包没有其他第三方依赖。


快速入门

相关资源