介绍
本指南展示了如何在 Aspose.PDF FOSS for C++ 中读取和更新文档级状态——即 PDF 中描述文档本身而非页面上绘制内容的部分。Aspose.PDF FOSS for C++ 以 Aspose::Pdf::Document 类为核心，该类从文件路径加载现有 PDF，并提供对内容编辑和文档级账务的访问。文档级账务包括 /Info 字典、XMP 元数据流、在查看器导航面板中显示的书签（大纲）树、内部链接使用的命名目标、嵌入 PDF 的文件附件以及文档可以定义的自定义页码序列。
本文逐一介绍这些领域的 API 表面：DocumentInfo 用于经典的 /Info 字典字段（标题、作者、创建者、主题、关键词），Metadata 用于 XMP 元数据流，Outlines 和 OutlineItemCollection 用于书签树，NamedDestinationCollection 用于命名链接，EmbeddedFileCollection 和 FileSpecification 用于附件，PageLabelCollection 用于按范围的页码编号。每个章节都将相关类与基于已加载的 Document 对象的实际示例配对。
Aspose.PDF FOSS for C++ 在 MIT 许可证下发布，并且仅依赖 C++ 标准库，因此本文所述的每项操作都无需专有 PDF 引擎或第三方依赖即可运行。该库以静态目标（aspose_pdf_foss）形式构建，可通过 CMake 添加。
包含内容
/Info 字典 — DocumentInfo
Document.Info() 返回绑定到 PDF /Info 字典的 DocumentInfo 引用。它提供对标准字段的类型化访问器——Title()、Author()、Creator()、Subject()、Keywords()、Producer() 和 Trapped()——每个都有对应的 setter，此外还有用于自定义键的通用 Add(key, value) / Remove(key) 对，以及 IsPredefinedKey(key) 用于检查键名是否属于标准字段。Document.SetTitle() 是一个快捷方式，直接在文档上写入标题。
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/document_info.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& info = doc.Info();
std::cout << "Title: " << info.Title() << "\n";
std::cout << "Author: " << info.Author() << "\n";
info.Author("Demo author");
info.Creator("Aspose.PDF FOSS C++");
info.Add("Generated-By", "document-management sample");
doc.Save("output.pdf");
}
XMP 元数据 — Metadata
除了 /Info 字典外，Document.Metadata() 返回文档 XMP 元数据流上的 Metadata 对象。它的行为类似于关联容器，提供条目操作：Add(key, value)、Contains(key)、ContainsKey(key)、TryGetValue(key, value)、Remove(key)、Keys()、Values() 和 Count()。自定义命名空间可通过 RegisterNamespaceUri(prefix, namespaceUri) 注册，并可使用 GetNamespaceUriByPrefix() 与 GetPrefixByNamespaceUri() 相互解析。
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/metadata.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& metadata = doc.Metadata();
metadata.RegisterNamespaceUri("myapp", "http://example.com/myapp/1.0/");
metadata.Add("myapp:BatchId", "2026-07-run-42");
std::cout << "XMP entries: " << metadata.Count() << "\n";
doc.Save("output.pdf");
}
书签和大纲
Document.Outlines() 返回文档的 OutlineCollection —— 在查看器导航面板中显示的书签树的根。该集合支持 Count()、Add(item)、Clear()、Contains(item)、Remove(item)、Delete()，以及端点访问器 First() / Last()，它们返回 OutlineItemCollection 节点。每个 OutlineItemCollection 节点包含 Title()、Bold() / Italic() 显示标志、Open() 展开状态、Destination() 或 Action()，以及遍历成员 Next()、Prev()、HasNext()、Level() 和 Parent()，返回所属的 Outlines 集合。
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/outlines.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& outlines = doc.Outlines();
std::cout << "Top-level bookmarks: " << outlines.Count() << "\n";
if (outlines.Count() > 0) {
auto& first = outlines.First();
std::cout << "First bookmark: " << first.Title()
<< " (level " << first.Level() << ")\n";
}
}
命名目标
Document.NamedDestinations() 返回一个 NamedDestinationCollection，它是将应用程序自定义名称映射到文档内部目标的查找表。使用 Add(name, appointment) 注册新条目，其中 appointment 是 IAppointment 实现——与大纲项目标和链接动作使用的同一接口。使用 Remove(name) 删除现有条目，使用 Count() 计数，并通过 Names() 枚举。
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/named_destination_collection.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& destinations = doc.NamedDestinations();
std::cout << "Named destinations: " << destinations.Count() << "\n";
for (const auto& name : destinations.Names()) {
std::cout << " " << name << "\n";
}
}
嵌入文件和附件
Document.EmbeddedFiles() 返回一个 EmbeddedFileCollection，其中包含 PDF 内部的 FileSpecification 附件。文件可通过 Add(file) 或 Add(key, file) 添加，使用 FindByName(name) 查找，使用 Delete(name)、DeleteByKey(key) 或 Delete() 删除，并通过 Count() 和 Keys() 枚举。每个 FileSpecification 提供其 Name()、Description()、MIMEType() 和 AFRelationship()——PDF “Associated File” 关系分类。
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/file_specification.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& files = doc.EmbeddedFiles();
std::cout << "Embedded files: " << files.Count() << "\n";
for (const auto& key : files.Keys()) {
auto spec = files.FindByName(key);
std::cout << " " << spec.Name() << " (" << spec.MIMEType() << ")\n";
}
}
页面标签
Document.PageLabels() 返回一个 PageLabelCollection，用于自定义查看器显示的页码序列，以取代物理页码——例如，前言使用罗马数字，正文使用阿拉伯数字。GetLabel(pageIndex) 获取该页生效的 PageLabel；PageLabel 暴露 StartingValue()、NumberingStyle()（一个 Aspose::Pdf::NumberingStyle 值，如 NumeralsArabic 或 NumeralsRomanLowercase）和 Prefix()。UpdateLabel(pageIndex, pageLabel) 在该页起始设置标签，RemoveLabel(pageIndex) 删除标签，GetPages() 列出所有带有自定义标签的页索引。
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/page_label.hpp>
#include <aspose/pdf/page_label_collection.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& labels = doc.PageLabels();
for (int pageIndex : labels.GetPages()) {
auto label = labels.GetLabel(pageIndex);
std::cout << "Page " << pageIndex << " prefix: " << label.Prefix()
<< ", starts at " << label.StartingValue() << "\n";
}
auto preface = labels.GetLabel(1);
preface.NumberingStyle(Aspose::Pdf::NumberingStyle::NumeralsRomanLowercase);
preface.StartingValue(1);
labels.UpdateLabel(1, preface);
doc.Save("output.pdf");
}
快速入门
将库作为 CMake 子目录添加，并链接到 aspose_pdf_foss 目标：
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)
打开文档，读取并更新其 /Info 元数据，然后保存结果：
#include <aspose/pdf/document.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& info = doc.Info();
std::cout << "Title: " << info.Title() << "\n";
std::cout << "Author: " << info.Author() << "\n";
doc.SetTitle("Updated Report Title");
info.Author("Report Generator");
info.Add("Generated-By", "Aspose.PDF FOSS for C++");
doc.Save("output.pdf");
return 0;
}
支持的格式
| 格式 | 扩展 | 读取 | 写入 |
|---|---|---|---|
| BMP | .bmp | — | ✓ |
| JPEG | .jpg | — | ✓ |
| TIFF | .tiff | — | ✓ |
| Text | .txt | — | ✓ |
| SVG | .svg | ✓ | — |
BMP、JPEG 和 TIFF 是各自设备类生成的页面渲染输出，文本通过 TextAbsorber 提取。SVG 通过库的 SVG 加载路径作为矢量内容导入。上述文档管理类型均不是格式转换器——它们仅读取和写入 PDF 结构。
开源与许可
Aspose.PDF FOSS for C++ 在 MIT 许可证下分发，完整源码可在 github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp 获得。该许可证允许商业使用、修改和再分发，无需另行协议。
