Aspose.PDF FOSS for TypeScript 功能

本页概览了 Aspose.PDF FOSS for TypeScript 的主要功能领域以及充当入口点的类，帮助您找到对应任务的开发者指南页面。每个领域都有独立页面进行深入阐述。

文档与页面管理

Document 是所有操作的入口点：Document.New() 在指定的 PageFormat 上启动一个空白文档，Document.OpenFile() / Document.Open() 从文件路径或内存字节加载已有文档。doc.Pages 是一个 Page 对象数组，Document.WriteTo() / Document.Save() 将结果写回。

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

const doc = Document.New(PageFormat.A4);
doc.Pages[0].AddText('Hello from Aspose.PDF FOSS!', 72, 720, { fontSize: 14 });
doc.WriteTo('hello.pdf');

请参阅核心 API 用于文档生命周期、拆分、合并和页面组装。

格式转换

Document.ToHtml()、Document.ToDocx() 和 Document.ToMarkdown() 将文档的每一页渲染为其他格式；在 Page 上也提供相同的方法用于渲染单页，另外 Page.ToImage() 用于 PNG 栅格输出，Page.ToSvg() 用于独立的 SVG。

const doc = Document.OpenFile('report.pdf');
const html = doc.ToHtml();                       // standalone HTML, all pages
const png = doc.Pages[0].ToImage({ scale: 2 });   // PNG bytes for page 1

请参阅 Conversion 用于完整的导出格式和选项。

注释

Page.AddHighlight() 和其兄弟 Page.Add*() 方法创建标记和形状注释；每个方法返回一个实时的 Annotation 句柄。Annotation.Flatten() 将注释的外观直接烘焙到页面的内容流中，并从 /Annots 中移除，使其永久且不可交互。

const highlight = doc.Pages[0].AddHighlight({ quadPoints: [72, 700, 200, 700, 72, 685, 200, 685] });
highlight.Flatten();

请参阅 Annotations 用于完整的标注类型以及搜索标注文本。

表单与字段扁平化

AcroForm 字段可以通过 doc.Form、一个 Form 门面，或直接在带有 Page.AddTextField() / Page.AddCheckbox() 的 Page 上创建。Form.AddTextField() 和 Form.AddCheckbox() 返回一个字段句柄，其自身的 Flatten() 方法会像 Annotation.Flatten() 那样将其烘焙为静态内容。

const field = doc.Form.AddTextField({
  page: 0, rect: [72, 660, 300, 680], name: 'FullName', value: 'Jane Doe',
});
field.Flatten();

请参阅 Forms 获取完整的字段类型集合。

Security

Document.OpenFile() 和 Document.Open() 接受一个 password 选项来打开受保护的文档，Document.Save() 接受一个 encrypt 选项以在保存时进行保护。Document.Sign() 和 Document.Certify() 添加数字签名，而 Document.VerifySignatures() 检查文档中已存在的每个签名。

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

try {
  const doc = Document.OpenFile('secret.pdf', { password: 'hunter2' });
  doc.WriteTo('decrypted.pdf');
} catch (e) {
  if (e instanceof InvalidPasswordError) console.error('wrong password');
  else throw e;
}

参见 Security 用于加密、签名和签名验证。

Redaction

Page.AddRedact() 标记一个矩形区域用于编辑，但尚未更改页面；Page.ApplyRedactions() 随后以破坏性方式重写内容流，永久删除标记的内容，并返回已应用的编辑次数。

page.AddRedact({ rect: [220, 550, 460, 566], fill: [0, 0, 0], overlayText: '[REDACTED]' });
const applied = page.ApplyRedactions();

参见 Redaction 更详细了解标记模式与已应用的编辑。

文档结构与可访问性

Document.AutoTag() 从页面布局推断并生成一个 /StructTreeRoot ——通过字体大小聚类识别标题、段落，以及（使用 opts.alt）图形——并返回一个 AutoTagReport。Document.GetStructTree() 读取生成的结构树，Document.ValidatePdfUa() 将文档与 PDF/UA-1 的机器可检查子集进行校验。

const report = doc.AutoTag({ lang: 'en-US', title: 'Quarterly Report', tables: true });
console.log(report);

参见 Structure 用于大纲、标签和命名目标。

提示与最佳实践

直接修改通过 doc.Pages 访问的 Page 对象——如果注释、字段或页面保存在单独的变量中且未从实时文档获取，则在调用 Save() / WriteTo() 时不会反映出来。
Flatten() 在 Annotation 和表单字段句柄（TextField、CheckboxField 以及其他字段类型）上均可用——在交互式内容应转为永久、不可编辑的页面内容时调用一次。
仅在该页面的所有 Page.AddRedact() 标记全部添加完毕后才调用 Page.ApplyRedactions()；调用后再添加的标记将不会生效。
在对不受信任的输入调用 Document.OpenFile() / Document.Open() 时，先专门捕获 InvalidPasswordError，再进行更宽泛的统一捕获。
Document.AutoTag() 会生成启发式结构树——应始终使用 Document.GetStructTree() 或 ValidatePdfUa() 对结果进行抽查，而不要假设已完全符合可访问性标准。

常见问题

问题	原因	修复
`Document.OpenFile()` / `Document.Open()` 抛出 `InvalidPasswordError`	文档已受密码保护，但未提供密码，或提供的密码错误	将 `{ password: '...' }` 传递给 `Document.OpenFile()` / `Document.Open()`
遮蔽标记没有效果	`Page.ApplyRedactions()` 从未被调用，或在标记添加之前就已被调用	首先对每个标记调用 `Page.AddRedact()`，然后调用一次 `Page.ApplyRedactions()`
扁平化字段或注释仍显示为交互式	`Flatten()` 在副本上被调用，而不是在 `Add*()` 调用返回的句柄上调用	在由 `AddTextField()` / `AddHighlight()` 等直接返回的对象上调用 `Flatten()`.
`ValidatePdfUa()` 在 `AutoTag()` 之后仍报告缺少结构	`AutoTag()` 是一种启发式方法，可能在没有 `alt` 回调的情况下未标记每个图形	将 `opts.alt` 函数传递给 `AutoTag()` 以为图像提供替代文本

FAQ

对于 TypeScript，Aspose.PDF 的 FOSS 是否依赖商业 PDF 引擎？

不。它在 MIT 许可证下发布，其渲染、转换和签名逻辑完全在 TypeScript/JavaScript 中运行。

我可以直接将 PDF 转换为 HTML、Markdown 或 DOCX 吗？

是的 — Document.ToHtml()、Document.ToMarkdown() 和 Document.ToDocx() 会渲染文档的每一页；相应的 Page.ToHtml() / Page.ToMarkdown() / Page.ToDocx() 方法则只渲染单页。

标记与应用编辑删除之间有什么区别？

Page.AddRedact() 只标记一个区域 —— 底层内容仍然存在且可以复制选择，直到调用 Page.ApplyRedactions()，后者会以破坏性的方式将其移除。

如何使注释或表单字段永久且不可编辑？

对创建它的 Add*() 调用返回的对象调用 Flatten() —— 对于注释使用 Annotation.Flatten()，对于 AcroForm 字段则使用字段句柄自身的 Flatten()。

我该去哪里？

《入门指南》涵盖了安装和第一个可运行示例。此开发者指南在上方链接的每个功能区提供专门页面继续深入。

API Reference 摘要

类/方法	描述
`Document`	入口点 — 创建、加载、保存和管理 PDF
`Document.New()` / `Document.OpenFile()` / `Document.Open()`	启动一个空白文档，或从文件路径或内存字节加载文档
`Document.WriteTo()` / `Document.Save()`	将文档写入文件路径或返回字节
`Document.ToHtml()` / `Document.ToDocx()` / `Document.ToMarkdown()`	将每页渲染为其他格式
`Page.ToImage()` / `Page.ToSvg()`	将单页渲染为 PNG 或 SVG
`Page.AddHighlight()` 和其他 `Page.Add*()` 注解方法	创建注解，返回实时句柄
`Annotation.Flatten()`	将注解的外观烘焙到静态页面内容中
`Form` / `Form.AddTextField()` / `Form.AddCheckbox()`	AcroForm 外观和字段创建
`Document.Sign()` / `Document.Certify()` / `Document.VerifySignatures()`	添加或验证数字签名
`Page.AddRedact()` / `Page.ApplyRedactions()`	标记并应用内容编辑
`Document.AutoTag()` / `Document.GetStructTree()`	撰写并读取文档的逻辑结构树

另请参阅

Aspose.PDF — Enterprise Documentation