مقدمه
این راهنما نشان میدهد که چگونه وضعیت سطح-سند را در Aspose.PDF FOSS برای C++ بخوانید و بهروزرسانی کنید — بخشهایی از PDF که توصیفکنندهٔ خود سند هستند نه آنچه روی صفحات آن رسم میشود. Aspose.PDF FOSS برای C++ بر کلاس Aspose::Pdf::Document متمرکز است، که یک PDF موجود را از مسیر فایل بارگذاری میکند و برای ویرایش محتوا و حسابداری سطح-سند در دسترس میگذارد. حسابداری سطح-سند شامل دیکشنری /Info، جریان متادیتای XMP، درخت نشانک (outline) که در پنل ناوبری نمایشگر نشان داده میشود، مقاصد نامگذاریشدهٔ مورد استفاده در لینکهای داخلی، پیوستهای فایل تعبیهشده در PDF، و توالیهای شمارهگذاری صفحهٔ سفارشی که سند میتواند تعریف کند، میشود.
این پست سطح API را برای هر یک از این حوزهها مرور میکند: DocumentInfo برای فیلدهای کلاسیک دیکشنری /Info (title, author, creator, subject, keywords)، Metadata برای جریان متادیتای XMP، Outlines و OutlineItemCollection برای درخت نشانک، NamedDestinationCollection برای لینکهای نامگذاریشده، EmbeddedFileCollection و FileSpecification برای پیوستها، و PageLabelCollection برای شمارهگذاری صفحه بهصورت بازهای. هر بخش کلاس مرتبط را با یک مثال عملی ساختهشده از شیء Document بارگذاریشده جفت میکند.
Aspose.PDF FOSS برای C++ تحت مجوز MIT منتشر شده است و فقط به کتابخانهٔ استاندارد C++ لینک میشود، بنابراین هر عملیاتی که در اینجا توصیف شده بدون نیاز به موتور PDF اختصاصی یا وابستگی شخص ثالث اجرا میشود. این کتابخانه بهعنوان هدف ایستاتیك (aspose_pdf_foss) که از طریق CMake اضافه میشود، ساخته میشود.
چه چیزی شامل میشود
دیکشنری /Info — DocumentInfo
Document.Info() یک ارجاع DocumentInfo برگردانده که به دیکشنری /Info PDF متصل است. این متد دسترسیهای تایپشده برای فیلدهای استاندارد دارد — 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() یک شیء Metadata بر روی جریان متادیتای XMP سند برمیگرداند. این شیء مانند یک container انجمنی از ورودیها رفتار میکند: 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 از پیوستهای FileSpecification که داخل PDF حمل میشوند برمیگرداند. فایلها با Add(file) یا Add(key, file) اضافه میشوند، با FindByName(name) جستجو میشوند، با Delete(name), DeleteByKey(key), یا Delete() حذف میشوند و از طریق Count() و Keys() شمارش و فهرست میشوند. هر FileSpecification مقادیر Name(), Description(), MIMEType(), و AFRelationship() را گزارش میدهد — طبقهبندی رابطهٔ «فایل مرتبط» در PDF.
#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 برای C++ تحت مجوز MIT توزیع میشود، با منبع کامل در github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp در دسترس است. این مجوز استفاده تجاری، تغییر و توزیع مجدد را بدون نیاز به توافقیه جداگانه مجاز میداند.
