Aspose.PDF FOSS for C++ 功能

Aspose.PDF FOSS for C++ 特性

Aspose.PDF FOSS for C++ 是一个 C++20 库，用于创建、打开、修改和保存 PDF 文档。本页概览了主要功能区域以及作为入口点的类。每个区域在其各自的开发者指南页面中都有深入的介绍。

文档管理

Aspose::Pdf::Document 是每个操作的根对象。它从路径打开已有文件，通过 Pages() 暴露页面集合，并使用 Save() 保存更改。Optimize() 和 OptimizeResources() 通过移除未使用或重复的资源来减小文件大小。

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");

    auto& pages = doc.Pages();
    pages.Add();                 // append a blank page
    pages.Delete(1);             // remove the original first page

    doc.Optimize();
    doc.Save("output.pdf");
}

文本提取

Aspose::Pdf::Text::TextAbsorber 遍历文档或单页并收集纯文本，可在调用 Visit() 后通过 Text() 获取。TextFragmentAbsorber 执行相同的遍历，但通过 TextFragments() 返回各个 TextFragment 对象，从而可以访问每个片段的位置和文本状态。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/text_absorber.hpp>
#include <iostream>

int main() {
    Aspose::Pdf::Document doc("report.pdf");

    Aspose::Pdf::Text::TextAbsorber absorber;
    absorber.Visit(doc);

    std::cout << absorber.Text() << "\n";
}

渲染为光栅图像

页面渲染设备将 Page 转换为光栅图像。BmpDevice、PngDevice、JpegDevice 和 TiffDevice 共享相同的 Process(page, output) 签名，并使用设置输出 DPI 的 Resolution 构建。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/bmp_device.hpp>
#include <aspose/pdf/resolution.hpp>
#include <fstream>

int main() {
    Aspose::Pdf::Document doc("report.pdf");

    Aspose::Pdf::Devices::BmpDevice device(Aspose::Pdf::Devices::Resolution(150));
    std::ofstream out("page1.bmp", std::ios::binary);
    device.Process(doc.Pages()[1], out);
}

加密

Document::Encrypt() 使用用户密码（用于打开文档）和所有者密码（用于更改权限）来保护文档，算法从 CryptoAlgorithm 枚举中选择：RC4x40、RC4x128、AESx128 或 AESx256。IsEncrypted() 报告当前状态，Decrypt() 则从已打开的文档中移除保护。

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");

    doc.Encrypt("user-password", "owner-password",
                Aspose::Pdf::Permissions::PrintDocument,
                Aspose::Pdf::CryptoAlgorithm::AESx256);

    doc.Save("encrypted.pdf");
}

批注

批注将可见的注释、形状和标记附加到页面上。每种批注类型都派生自 Annotation，并使用目标 Page 和放置 Rectangle 构造，然后通过 批注()（一种 AnnotationCollection）添加到页面。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/text_annotation.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto page = doc.Pages()[1];

    Aspose::Pdf::Annotations::TextAnnotation note(
        page, Aspose::Pdf::Rectangle(50.0, 700.0, 250.0, 740.0, false));
    note.Contents("Reviewed and approved.");

    page.Annotations().Add(note);
    doc.Save("annotated.pdf");
}

Forms

AcroForm 字段通过 Aspose::Pdf::Forms::Form 管理，可通过 Document::Form() 访问。诸如 TextBoxField 的字段类型的构造方式类似批注——使用 Page 和 Rectangle——并在 Form::Add() 中注册。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/text_box_field.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto page = doc.Pages()[1];

    Aspose::Pdf::Forms::TextBoxField field(
        page, Aspose::Pdf::Rectangle(100.0, 650.0, 300.0, 670.0, false));
    field.PartialName("customer_name");
    field.Value("Jane Doe");

    doc.Form().Add(field);
    doc.Save("form_filled.pdf");
}

技巧与最佳实践

使用 Document 构造函数按路径打开输入文件；调用 Save() 时提供显式的输出路径，而不是在其他句柄仍可能打开的情况下覆盖源文件。
当文档被大量编辑时，在调用 Save() 之前先调用 Optimize()——它会删除任何页面不再引用的资源。
针对每个分辨率构建一次光栅设备（BmpDevice、PngDevice、JpegDevice、TiffDevice），并在页面之间复用，而不是为每页重新创建设备。
在调用 Encrypt() 时同时设置用户密码和所有者密码——空的用户密码允许任何查看器打开文件，而所有者密码则限制权限的更改。
保持注释和字段对象（TextAnnotation、TextBoxField 等）在 Save() 返回之后仍然存活，因为文档持有对它们所添加的页面内容的引用。

常见问题

问题	原因	修复
`Save()` 生成的文件内容保持不变	对页面或注释的副本进行了编辑，而不是对从 `doc.Pages()` 获取的对象进行编辑	直接修改由 `Pages()`、`Annotations()` 或 `Form()` 返回的对象
渲染的图像为空或空白	向 `Process()` 传递了错误的页面索引	`PageCollection` 是从 1 开始计数的 — 第 1 页是 `doc.Pages()[1]`，而不是 `[0]`
`Encrypt()` 生成的文件仍然可以在不输入密码的情况下打开	用户密码为空	将非空字符串作为 `userPassword` 参数传入
对扫描的 PDF 提取的文本为空	该页仅包含栅格图像内容，没有文本操作符	`TextAbsorber` 读取文本操作符；仅图像页没有可提取的内容
使用 `Form::Add()` 添加的字段未出现在页面上	字段的 `Rectangle` 超出了页面的 `MediaBox`	确认矩形坐标位于 `Page::MediaBox()` 范围内

FAQ

Aspose.PDF 的 C++ 开源版是否依赖任何商业 PDF 库？

不。它是一个从头开始的 C++20 实现，不依赖任何商业 PDF 堆栈，采用 MIT 许可证发布。

我可以从头创建一个新的 PDF，而不是打开已有的文件吗？

是的。Document 有一个默认构造函数，可创建空文档；在保存之前调用 Pages().Add() 追加页面。

我可以渲染成哪些栅格格式？

BmpDevice、PngDevice、JpegDevice 和 TiffDevice 分别将单页渲染为 BMP、PNG、JPEG 和 TIFF。

支持哪些加密算法？

CryptoAlgorithm 提供 RC4x40、RC4x128、AESx128 和 AESx256，传递给 Document::Encrypt()。

接下来我该去哪里？

开发者指南包括专门的页面，用于文档和页面管理、PDF-native 图形和形状、注释和交互式表单，以及封装常见文件操作的更高级别外观类。

API Reference 摘要

类/方法	描述
`Document`	根对象 — 打开、创建、保存并优化 PDF
`Document.Pages()`	返回文档的 `PageCollection`
`Document.Encrypt()` / `Decrypt()`	对文档进行密码保护或移除保护
`Document.Form()`	返回文档的 AcroForm 容器
`TextAbsorber`	从文档或页面中提取纯文本
`TextFragmentAbsorber`	提取定位的文本片段
`BmpDevice` / `PngDevice` / `JpegDevice` / `TiffDevice`	将页面渲染为光栅图像格式
`Resolution`	输出传递给渲染设备的 DPI
`CryptoAlgorithm`	加密算法选择：RC4 或 AES，40–256 位
`Permissions`	传递给 `Encrypt()` 的访问控制标志
`Annotation` / `AnnotationCollection`	页面注释的基础类型和容器
`TextAnnotation`	文本注释
`Form`	AcroForm 字段容器通过 `Document.Form()` 访问
`TextBoxField`	单行/多行文本表单字段

另请参阅

Aspose.PDF for C++ — Enterprise Documentation