C# / .NET API 参考

PdfOxide NuGet 包通过 LibraryImport 生成的 P/Invoke（全部 881 条声明）封装 Rust 内核。开箱即可用于 NativeAOT 发布，且 trim-safe。目标框架：net8.0、net10.0。

dotnet add package PdfOxide

using PdfOxide.Core;

其他语言请参见 Python、Node.js、Golang 或 Rust。

---

命名空间

using PdfOxide.Core;        // PdfDocument, Pdf, DocumentEditor, DocumentBuilder, ...
using PdfOxide.Geometry;    // Color, Point, Rect
using PdfOxide.Exceptions;  // PdfException and typed subclasses

所有由原生层支撑的类型都实现了 IDisposable——请使用 using 块或 using 声明。除非另有说明，坐标均以 PDF 点为单位、原点位于左下角；以浮点数传入的颜色通道取值范围为 0.0–1.0。

---

PdfDocument

只读 / 提取句柄。PdfDocument 可枚举、可索引，按需返回惰性的 Page 句柄。

打开

static PdfDocument Open(string path)
static PdfDocument Open(Stream stream)
static PdfDocument Open(byte[] data)
static PdfDocument Open(ReadOnlySpan<byte> data)
static PdfDocument OpenWithPassword(string path, string password)
static PdfDocument OpenFromDocxBytes(byte[] data)
static PdfDocument OpenFromPptxBytes(byte[] data)
static PdfDocument OpenFromXlsxBytes(byte[] data)

• Open(...) —— 从路径、流、字节数组或 span 打开。
• OpenWithPassword(path, password) —— 一步打开加密的 PDF。
• OpenFromDocxBytes / OpenFromPptxBytes / OpenFromXlsxBytes —— 将 Office 字节转换后作为 PDF 打开（需要 office 特性）。

属性

(byte Major, byte Minor) Version { get; }   // PDF version, e.g. (1, 7)
int PageCount { get; }                       // number of pages
bool HasStructureTree { get; }               // Tagged PDF with a structure tree
bool IsEncrypted { get; }                    // document is encrypted
bool HasXfa { get; }                         // contains XFA forms
int SignatureCount { get; }                  // number of digital signatures
IReadOnlyList<Signature> Signatures { get; } // signature handles
IReadOnlyList<Page> Pages { get; }           // lazy per-page handles
Page this[int pageIndex] { get; }            // page at index

身份验证

bool Authenticate(string password)

打开文档后，使用用户口令或所有者口令对加密文档进行身份验证。成功时返回 true。

文本提取

string ExtractText(int pageIndex)
string ExtractAllText()
Task<string> ExtractTextAsync(int pageIndex, CancellationToken cancellationToken = default)
string ExtractTextInRect(int pageIndex, float x, float y, float width, float height)

(string Text, float X, float Y, float W, float H)[] ExtractWords(int pageIndex)
(string Text, float X, float Y, float W, float H)[] ExtractWordsInRect(int pageIndex, float x, float y, float width, float height)
(string Text, float X, float Y, float W, float H)[] ExtractTextLines(int pageIndex)
(char Char, float X, float Y, float W, float H)[] ExtractChars(int pageIndex)
(float X, float Y, float W, float H, float StrokeWidth)[] ExtractPaths(int pageIndex)
Table[] ExtractTables(int pageIndex)

• ExtractText / ExtractAllText —— 提取单页或整篇文档的纯文本。
• ExtractTextInRect —— 提取矩形区域内的文本。
• ExtractWords / ExtractWordsInRect —— 提取带边界框的单词（可选按区域裁剪）。
• ExtractTextLines —— 提取带边界框的文本行。
• ExtractChars —— 提取逐字形位置。
• ExtractPaths —— 提取矢量路径段及其描边宽度。
• ExtractTables —— 提取检测到的表格（参见 Table）。

分类与自动提取

string ExtractStructured(int page)
string ClassifyPage(int pageIndex)
string ClassifyDocument()
string ExtractTextAuto(int pageIndex)
string ExtractPageAuto(int pageIndex, string? optionsJson = null)

• ExtractStructured —— 以结构化 JSON 形式返回页面内容。
• ClassifyPage / ClassifyDocument —— 对单页或整篇文档进行分类（例如扫描件还是数字原生文档）。
• ExtractTextAuto —— 自动为页面选择最佳文本提取路径（数字或 OCR）。
• ExtractPageAuto —— 自动提取，可附带可选的 JSON 选项数据块。

转换

string ToMarkdown(int pageIndex)
string ToMarkdownAll()
string ToHtml(int pageIndex)
string ToHtmlAll()
string ToPlainText(int pageIndex)
string ToPlainTextAll()

byte[] ToDocxBytes()
byte[] ToPptxBytes()
byte[] ToXlsxBytes()

• ToMarkdown / ToHtml / ToPlainText（及 *All）—— 转换单页或整篇文档。
• ToDocxBytes / ToPptxBytes / ToXlsxBytes —— 导出为 Office 格式（需要 office 特性）。

内容清理

int RemoveHeaders(float threshold = 0.8f)
int RemoveFooters(float threshold = 0.8f)
int RemoveArtifacts(float threshold = 0.8f)

检测并剔除反复出现的页眉、页脚或页面伪影。返回被移除的元素数量。threshold 为跨页复现率。

搜索

(int Page, string Text, float X, float Y, float W, float H)[] SearchAll(string text, bool caseSensitive = false)
(int Page, string Text, float X, float Y, float W, float H)[] SearchPage(int pageIndex, string text, bool caseSensitive = false)

在整篇文档或单页范围内搜索；返回带页索引和边界框的匹配结果。

结构与元数据

string GetPageLabels()
string GetXmpMetadata()
string GetOutline()
string PlanSplitByBookmarks(int level, string? namePattern = null)
string[] GetFonts(int pageIndex)

• GetPageLabels —— 页面标签区间（JSON）。
• GetXmpMetadata —— XMP 元数据（JSON / XML 包）。
• GetOutline —— 书签树 / 目录（JSON）。
• PlanSplitByBookmarks —— 在指定书签层级计算拆分方案。
• GetFonts —— 页面上使用的字体名称。

图像

ExtractedImage[] ExtractImages(int pageIndex)

提取内嵌图像，附带元数据与原始字节（参见 ExtractedImage）。

表单

FormField[] GetFormFields()

枚举 AcroForm 表单字段（参见 FormField）。

渲染

byte[] RenderPage(int pageIndex, int format = 0)
byte[] RenderPage(int pageIndex, RenderOptions options)
byte[] RenderPageZoom(int pageIndex, float zoom, int format = 0)
byte[] RenderPageFit(int pageIndex, int fitWidth, int fitHeight, int format = 0)
byte[] RenderThumbnail(int pageIndex, int format = 0)
RgbaPixmap RenderToRgba(int pageIndex, int dpi = 150)
void SaveRenderedImage(int pageIndex, string filePath, int format = 0)

• RenderPage —— 以默认 DPI 渲染（format：0 = PNG，1 = JPEG），或使用完整的 RenderOptions。
• RenderPageZoom —— 按缩放系数渲染。
• RenderPageFit —— 缩放渲染以适配像素框。
• RenderThumbnail —— 渲染小尺寸缩略图。
• RenderToRgba —— 渲染为原始 RGBA pixmap（参见 RgbaPixmap）。
• SaveRenderedImage —— 渲染后直接写入文件。

签名

unsafe DocumentSecurityStore? GetDss()
bool HasDocumentTimestamp()

• GetDss —— 读取文档安全存储（DSS，若存在）。
• HasDocumentTimestamp —— 是否存在文档级时间戳。

逐个签名的验证请参见 Signature。

静态配置

static void SetLogLevel(int level)
static int GetLogLevel()
static string PrefetchModels(params string[] languages)
static string ModelManifest()
static bool PrefetchAvailable()
static string GetActiveCryptoProvider()
static bool IsFipsCryptoAvailable()
static void UseFipsCryptoProvider()
static void SetCryptoPolicy(string spec)
static string CryptoPolicy()
static string[] CryptoInventory()
static string CryptoCbom()

• SetLogLevel / GetLogLevel —— 控制原生层日志的详细程度。
• PrefetchModels / ModelManifest / PrefetchAvailable —— 管理 OCR 模型下载。
• GetActiveCryptoProvider / IsFipsCryptoAvailable / UseFipsCryptoProvider —— 加密提供程序选择（FIPS）。
• SetCryptoPolicy / CryptoPolicy —— 获取 / 设置当前加密策略。
• CryptoInventory / CryptoCbom —— 枚举加密用法 / 生成 CBOM。

释放

void Dispose()

---

Page

来自 doc[i] 或迭代的惰性逐页句柄。所有成员都委托给父文档处理。

int Index { get; }

string ExtractText();
Task<string> ExtractTextAsync(CancellationToken ct = default);
string ToMarkdown();
Task<string> ToMarkdownAsync(CancellationToken ct = default);
string ToHtml();
Task<string> ToHtmlAsync(CancellationToken ct = default);
string ToPlainText();
Task<string> ToPlainTextAsync(CancellationToken ct = default);

(string Text, float X, float Y, float W, float H)[] ExtractWords();
(string Text, float X, float Y, float W, float H)[] ExtractLines();
(char Char, float X, float Y, float W, float H)[] ExtractChars();
(float X, float Y, float W, float H, float StrokeWidth)[] ExtractPaths();
Table[] ExtractTables();
ExtractedImage[] ExtractImages();
string[] GetFonts();
(int Page, string Text, float X, float Y, float W, float H)[] Search(string text, bool caseSensitive = false);

byte[] Render(int format = 0);
byte[] RenderThumbnail(int format = 0);

---

Pdf —— 生成

从某种源格式创建 PDF，然后保存。

static Pdf FromMarkdown(string markdown)
static Pdf FromHtml(string html)
static Pdf FromHtmlCss(string html, string css, byte[] fontBytes)
static unsafe Pdf FromHtmlCssWithFonts(string html, string css, (string Name, byte[] Bytes)[] fonts)
static Pdf FromText(string text)
static Pdf FromImage(string path)
static Pdf FromImageBytes(byte[] data)

int PageCount { get; }

void Save(string path)
byte[] SaveToBytes()
void SaveToStream(Stream stream)
Task SaveAsync(string path, CancellationToken cancellationToken = default)
Task SaveToStreamAsync(Stream stream, CancellationToken cancellationToken = default)
void Dispose()

• FromMarkdown / FromHtml / FromText —— 从文本格式创建。
• FromHtmlCss / FromHtmlCssWithFonts —— 带内嵌字体的 HTML + CSS 流水线。
• FromImage / FromImageBytes —— 由图像生成单页 PDF。
• Save / SaveToBytes / SaveToStream（及异步版本）—— 持久化结果。

---

DocumentEditor

针对现有 PDF 的可变编辑器：元数据、页面、表单、涂黑、加密。

打开与保存

static DocumentEditor Open(string path)
static DocumentEditor OpenFromBytes(byte[] data)

void Save(string path)
Task SaveAsync(string path, CancellationToken cancellationToken = default)
byte[] SaveToBytes()
byte[] SaveToBytesWithOptions(bool compress, bool garbageCollect, bool linearize)
void SaveEncrypted(string path, string userPassword, string ownerPassword)
byte[] SaveEncryptedToBytes(string userPassword, string ownerPassword)
unsafe byte[] ExtractPages(int[] pageIndices)
void Dispose()

属性

bool IsModified { get; }
string SourcePath { get; }
(byte Major, byte Minor) Version { get; }
int PageCount { get; }
string? Title { get; set; }
string? Author { get; set; }
string? Subject { get; set; }
string? Keywords { get; set; }
string? Producer { get; set; }
string? CreationDate { get; set; }
string[] FlattenWarnings { get; }

页面操作

void MergeFrom(string sourcePath)
int MergeFromBytes(byte[] data)
void DeletePage(int pageIndex)
void MovePage(int fromIndex, int toIndex)
int GetPageRotation(int pageIndex)
void SetPageRotation(int pageIndex, int degrees)
void RotateAllPages(int degrees)
void RotatePageBy(int pageIndex, int degrees)
void CropMargins(float left, float right, float top, float bottom)
(double X, double Y, double Width, double Height) GetPageMediaBox(int pageIndex)
void SetPageMediaBox(int pageIndex, double x, double y, double width, double height)
(double X, double Y, double Width, double Height) GetPageCropBox(int pageIndex)
void SetPageCropBox(int pageIndex, double x, double y, double width, double height)

• MergeFrom / MergeFromBytes —— 追加来自另一个 PDF 的页面（MergeFromBytes 返回合并后的页数）。
• DeletePage / MovePage —— 删除或重排页面。
• GetPageRotation / SetPageRotation / RotateAllPages / RotatePageBy —— 旋转控制（绝对值 vs 相对值）。
• CropMargins —— 裁剪所有页面的边距。
• Get/SetPageMediaBox 与 Get/SetPageCropBox —— 页面几何框。

擦除 / 涂白

void EraseRegion(int pageIndex, float x, float y, float width, float height)
void EraseRegions(int pageIndex, double[][] rects)
void ClearEraseRegions(int pageIndex)

注释与表单

void SetFormFieldValue(string name, string value)
void FlattenForms()
void FlattenFormsOnPage(int pageIndex)
void FlattenAnnotations(int pageIndex)
void FlattenAllAnnotations()
bool IsPageMarkedForFlatten(int pageIndex)
void UnmarkPageForFlatten(int pageIndex)

涂黑

void AddRedaction(int pageIndex, double x1, double y1, double x2, double y2, byte r, byte g, byte b)
int RedactionCount(int pageIndex)
void ApplyPageRedactions(int pageIndex)
void ApplyAllRedactions()
int ApplyRedactions(bool scrubMetadata = true, bool scrubText = true)
bool IsPageMarkedForRedaction(int pageIndex)
void UnmarkPageForRedaction(int pageIndex)
int SanitizeDocument()

• AddRedaction —— 排入一个带填充色的涂黑矩形。
• ApplyPageRedactions / ApplyAllRedactions / ApplyRedactions —— 将待处理的涂黑烧入文档（ApplyRedactions 可选清理元数据 / 隐藏文本）。
• SanitizeDocument —— 移除隐藏 / 未引用的数据；返回被清理的数量。

其他

void EmbedFile(string name, byte[] data)
void ConvertToPdfA(PdfALevel level = PdfALevel.A2b)

• EmbedFile —— 将文件附加到 PDF 中。
• ConvertToPdfA —— 转换为指定的 PDF/A 一致性级别。

AddRedaction / ApplyRedactions 的实际签名在底层使用 snake-case 命名的原生参数；此处展示的 C# 接口为公开绑定。

---

DocumentBuilder

用于创建新文档的流式构建器。DocumentBuilder.Create() → 元数据 → 页面 → Build() / Save()。

static DocumentBuilder Create()

DocumentBuilder Title(string title)
DocumentBuilder Author(string author)
DocumentBuilder Subject(string subject)
DocumentBuilder Keywords(string keywords)
DocumentBuilder Creator(string creator)
DocumentBuilder OnOpen(string script)            // document-open JavaScript
DocumentBuilder TaggedPdfUa1()                    // emit a Tagged PDF/UA-1
DocumentBuilder Language(string lang)
DocumentBuilder RoleMap(string custom, string standard)
DocumentBuilder RegisterEmbeddedFont(string name, EmbeddedFont font)

PageBuilder A4Page()
PageBuilder LetterPage()
PageBuilder Page(float width, float height)

byte[] Build()
void Save(string path)
void SaveEncrypted(string path, string userPassword, string ownerPassword)
byte[] ToBytesEncrypted(string userPassword, string ownerPassword)
void Dispose()

---

PageBuilder

由 A4Page() / LetterPage() / Page(w, h) 返回的逐页流式接口。每个方法都返回该构建器以便链式调用；Done() 将页面提交回父级。

文本与排版

PageBuilder Font(string name, float size)
PageBuilder At(float x, float y)
PageBuilder Text(string text)
PageBuilder Heading(byte level, string text)
PageBuilder Paragraph(string text)
PageBuilder Space(float points)
PageBuilder HorizontalRule()
PageBuilder Newline()
PageBuilder Columns(uint columnCount, float gapPt, string text)
PageBuilder Footnote(string refMark, string noteText)
PageBuilder TextInRect(float x, float y, float w, float h, string text, Alignment align = Alignment.Left)
PageBuilder NewPageSameSize()
float Measure(string text)
float RemainingSpace()

行内文本段

PageBuilder Inline(string text)
PageBuilder InlineBold(string text)
PageBuilder InlineItalic(string text)
PageBuilder InlineColor(float r, float g, float b, string text)

链接与 JavaScript

PageBuilder LinkUrl(string url)
PageBuilder LinkPage(int pageIndex)
PageBuilder LinkNamed(string destination)
PageBuilder LinkJavascript(string script)
PageBuilder OnOpen(string script)
PageBuilder OnClose(string script)
PageBuilder FieldKeystroke(string script)
PageBuilder FieldFormat(string script)
PageBuilder FieldValidate(string script)
PageBuilder FieldCalculate(string script)

注释

PageBuilder Highlight(float r, float g, float b)
PageBuilder Underline(float r, float g, float b)
PageBuilder Strikeout(float r, float g, float b)
PageBuilder Squiggly(float r, float g, float b)
PageBuilder StickyNote(string text)
PageBuilder StickyNoteAt(float x, float y, string text)
PageBuilder Watermark(string text)
PageBuilder WatermarkConfidential()
PageBuilder WatermarkDraft()
PageBuilder Stamp(string typeName)
PageBuilder FreeText(float x, float y, float w, float h, string text)

表单控件

PageBuilder TextField(string name, float x, float y, float w, float h, string? defaultValue = null)
PageBuilder Checkbox(string name, float x, float y, float w, float h, bool @checked = false)
unsafe PageBuilder ComboBox(string name, float x, float y, float w, float h, string[] options, string? selected = null)
unsafe PageBuilder RadioGroup(string name, (string Value, float X, float Y, float W, float H)[] buttons, string? selected = null)
PageBuilder PushButton(string name, float x, float y, float w, float h, string caption)
PageBuilder SignatureField(string name, float x, float y, float w, float h)

图形

PageBuilder Rect(float x, float y, float w, float h)
PageBuilder FilledRect(float x, float y, float w, float h, float r, float g, float b)
PageBuilder Line(float x1, float y1, float x2, float y2)
PageBuilder StrokeRect(float x, float y, float w, float h, float width = 1f, float r = 0f, float g = 0f, float b = 0f)
PageBuilder StrokeLine(float x1, float y1, float x2, float y2, float width = 1f, float r = 0f, float g = 0f, float b = 0f)
unsafe PageBuilder StrokeRectDashed(float x, float y, float w, float h, float[] dash, float phase = 0f, float width = 1f, float r = 0f, float g = 0f, float b = 0f)
unsafe PageBuilder StrokeLineDashed(float x1, float y1, float x2, float y2, float[] dash, float phase = 0f, float width = 1f, float r = 0f, float g = 0f, float b = 0f)

图像与条形码

unsafe PageBuilder Image(byte[] imageBytes, float x, float y, float w, float h)
unsafe PageBuilder ImageWithAlt(byte[] imageBytes, float x, float y, float w, float h, string altText)
unsafe PageBuilder ImageArtifact(byte[] imageBytes, float x, float y, float w, float h)
PageBuilder Barcode1d(int barcodeType, string data, float x, float y, float w, float h)
PageBuilder BarcodeQr(string data, float x, float y, float size)

表格

unsafe PageBuilder Table(TableSpec spec)
StreamingTable StreamingTable(IReadOnlyList<Column> columns, bool repeatHeader = true,
                              TableMode? mode = null, int maxRowspan = 1, int batchSize = 256)
DocumentBuilder Done()
void Dispose()

• Table —— 从 TableSpec 渲染一个完全物化的表格。
• StreamingTable —— 为大批量 / 逐行数据打开一个流式表格（参见 StreamingTable）。
• Done —— 提交页面并返回父级 DocumentBuilder。

---

EmbeddedFont

static EmbeddedFont FromFile(string path)
static EmbeddedFont FromBytes(byte[] data, string? name = null)
void Dispose()

加载 TTF/OTF 字体，以便通过 DocumentBuilder.RegisterEmbeddedFont 内嵌。

---

StreamingTable

面向大数据集的逐行表格构建器，由 PageBuilder.StreamingTable(...) 返回。

unsafe StreamingTable AddRow(params string[] cells)
unsafe StreamingTable AddRowSpan(params (string? Text, int Rowspan)[] cells)
void Flush()
PageBuilder Build()
void Dispose()

• AddRow —— 追加一行单元格。
• AddRowSpan —— 追加一行，每个单元格可指定行跨度（需要 maxRowspan >= 2）。
• Flush —— 将缓冲的行刷写到原生层。
• Build —— 终结表格并返回父级 PageBuilder。

---

OcrEngine

对扫描版 PDF 进行 OCR（需要 ocr 特性）。模型从检测 / 识别 / 字典路径加载。

static OcrEngine Load(string detectionModelPath, string recognitionModelPath, string dictionaryPath)
static bool PageNeedsOcr(PdfDocument document, int pageIndex)
string ExtractText(PdfDocument document, int pageIndex)
void Dispose()

• Load —— 从模型文件加载引擎。
• PageNeedsOcr —— 启发式判断某页是否缺少数字文本层。
• ExtractText —— 对某页运行 OCR。

另请参见 PdfDocument.PrefetchModels、ModelManifest 与 PrefetchAvailable。

---

数字签名

Signature

来自 PdfDocument.Signatures 的逐个签名句柄。

string? SignerName { get; }
string? Reason { get; }
string? Location { get; }
Certificate GetCertificate()
bool Verify()
bool VerifyDetached(ReadOnlySpan<byte> pdfData)
void Dispose()

• Verify —— 校验签名的密码学完整性。
• VerifyDetached —— 额外校验 messageDigest 是否与所提供的 PDF 字节相符。
• GetCertificate —— 签名者的证书。

Certificate

static Certificate LoadFromPem(string certPem, string keyPem)
static Certificate Load(byte[] data, string? password = null)
unsafe byte[] SignPdfBytes(byte[] pdfData, string? reason = null, string? location = null)
unsafe byte[] SignPdfBytesPades(byte[] pdfData, PadesSignOptions options)
void Dispose()

• LoadFromPem / Load —— 加载签名证书（PEM 对，或带可选口令的 PKCS#12 字节）。
• SignPdfBytes —— 使用基础 CMS 签名进行签署。
• SignPdfBytesPades —— 使用 PAdES 配置进行签署（参见 PadesSignOptions）。

Timestamp

static Timestamp Parse(byte[] data)
string Serial { get; }
string PolicyOid { get; }
string TsaName { get; }
bool Verify()
void Dispose()

TsaClient

static TsaClient Create(TsaClientOptions options)
Timestamp RequestTimestamp(byte[] data)
Timestamp RequestTimestampHash(byte[] hash, TimestampHashAlgorithm hashAlgorithm)
void Dispose()

TsaClientOptions（仅初始化）：Url（必填）、Username、Password、TimeoutSeconds（= 30）、HashAlgorithm（= Sha256）、UseNonce（= true）、CertReq（= true）。位于 tsa-client 特性之后。

---

Barcode

static Barcode GenerateQrCode(string data, int errorCorrection = 1, int sizePx = 300)
static Barcode Generate(string data, BarcodeFormat format = BarcodeFormat.Code128, int sizePx = 300)
byte[] ToPng(int sizePx = 300)
string ToSvg()
void Dispose()

BarcodeFormat：Code128、Code39、Ean13、Ean8、UpcA、Itf。

---

PdfValidator

静态合规检查。每个方法都返回一个 PdfValidationResult。

static PdfValidationResult ValidatePdfA(PdfDocument document, PdfALevel level = PdfALevel.A2b)
static PdfValidationResult ValidatePdfX(PdfDocument document, PdfXLevel level = PdfXLevel.X4)
static PdfValidationResult ValidatePdfUA(PdfDocument document, PdfUaLevel level = PdfUaLevel.Ua1)

---

数据类型

RgbaPixmap

public sealed record RgbaPixmap(ReadOnlyMemory<byte> Data, int Width, int Height);

Table

public sealed class Table
{
    public int RowCount { get; }
    public int ColCount { get; }
    public bool HasHeader { get; }
}

ExtractedImage

public sealed class ExtractedImage
{
    public int Width { get; }
    public int Height { get; }
    public string Format { get; }
    public string Colorspace { get; }
    public int BitsPerComponent { get; }
    public byte[] Data { get; }
}

FormField

public sealed class FormField
{
    public string Name { get; }
    public string FieldType { get; }
    public string Value { get; }
}

TableSpec

public sealed class TableSpec
{
    public List<Column> Columns { get; set; }
    public IList<IList<string>> Rows { get; set; }
    public bool HasHeader { get; set; }
}

public sealed class Column
{
    public string Header { get; set; }
    public float Width { get; set; }
    public Alignment Align { get; set; }
    public Column(string header, float width, Alignment align = Alignment.Left);
}

public abstract class TableMode
{
    public sealed class Fixed : TableMode { }
    public sealed class Sample : TableMode
    {
        public int SampleRows { get; init; }      // = 20
        public float MinColWidthPt { get; init; } // = 0
        public float MaxColWidthPt { get; init; } // = 9999
    }
}

public enum Alignment { Left = 0, Center = 1, Right = 2 }

RenderOptions

public sealed class RenderOptions
{
    public int Dpi { get; set; }                   // = 150
    public RenderImageFormat Format { get; set; }  // = Png
    public bool TransparentBackground { get; set; }
    public bool RenderAnnotations { get; set; }    // = true
    public int JpegQuality { get; set; }           // = 85
}

public enum RenderImageFormat { Png = 0, Jpeg = 1 }

PAdES / DSS 类型

public enum PadesLevel { BB = 0, BT = 1, BLt = 2, BLta = 3 }

public sealed class PadesSignOptions
{
    public PadesLevel Level { get; set; }            // = BB
    public string? TsaUrl { get; set; }
    public string? Reason { get; set; }
    public string? Location { get; set; }
    public RevocationMaterial? Revocation { get; set; }
}

public sealed class RevocationMaterial
{
    public IList<byte[]> Certificates { get; }
    public IList<byte[]> Crls { get; }
    public IList<byte[]> OcspResponses { get; }
}

public sealed class DocumentSecurityStore
{
    public IReadOnlyList<byte[]> Certificates { get; }
    public IReadOnlyList<byte[]> Crls { get; }
    public IReadOnlyList<byte[]> OcspResponses { get; }
    public int VriCount { get; }
}

public enum TimestampHashAlgorithm { Unknown = 0, Sha1 = 1, Sha256 = 2, Sha384 = 3, Sha512 = 4 }

合规校验类型

public sealed class PdfValidationResult
{
    public bool IsCompliant { get; }
    public IReadOnlyList<string> Errors { get; }
    public IReadOnlyList<string> Warnings { get; }
}

public enum PdfALevel { A1b = 0, A1a = 1, A2b = 2, A2a = 3, A2u = 4, A3b = 5, A3a = 6, A3u = 7 }
public enum PdfXLevel { X1a = 0, X3 = 1, X4 = 2 }
public enum PdfUaLevel { Ua1 = 1, Ua2 = 2 }

几何（PdfOxide.Geometry）

public struct Color : IEquatable<Color>
{
    public Color(byte red, byte green, byte blue);
    public Color(byte red, byte green, byte blue, byte alpha);
    public byte Red { get; }
    public byte Green { get; }
    public byte Blue { get; }
    public byte Alpha { get; }
    public static Color FromArgb(uint argb);
    public uint ToArgb();
    public string ToHex();
    public static Color Black { get; }
    public static Color White { get; }
    public static Color Yellow { get; }
    public static Color Cyan { get; }
    public static Color Magenta { get; }
}

public struct Point : IEquatable<Point>
{
    public Point(float x, float y);
    public float X { get; }
    public float Y { get; }
    public float Magnitude { get; }
    public float Distance(Point other);
    // operators: + - * / == !=
}

public struct Rect : IEquatable<Rect>
{
    public Rect(float x, float y, float width, float height);
    public float X { get; }
    public float Y { get; }
    public float Width { get; }
    public float Height { get; }
    public bool Contains(Point point);
    public bool Intersects(Rect other);
}

---

异常

所有原生失败都会抛出 PdfException（位于 PdfOxide.Exceptions）：

public class PdfException : Exception
{
    public string Code { get; }
    public static string GetErrorMessage(int errorCode);
    public PdfException WithContext(string operation, params (string key, object? value)[] context);
}

带类型的子类覆盖各具体类别——例如：ParseException、InvalidStructure、CorruptedData、UnsupportedVersion、EncryptionException、InvalidPassword、DecryptionFailed、UnsupportedAlgorithm、DocumentClosed、OperationNotAllowed、UnsupportedFeatureException、FeatureNotImplemented、FormatNotSupported、ValidationException、InvalidParameter、MissingRequired、RenderingException、RenderFailed、UnsupportedRenderFormat、SearchException、InvalidPattern、SignatureException、RedactionException、AccessibilityException、OptimizationException、ComplianceException、ComplianceFailed、OcrException、RecognitionFailed、LanguageNotSupported、ImageProcessingFailed、InternalError 以及 XfaException。

try
{
    using var doc = PdfDocument.Open("file.pdf");
    var text = doc.ExtractText(0);
}
catch (InvalidPassword)
{
    // wrong / missing password
}
catch (UnsupportedFeatureException)
{
    // feature not compiled into this build (e.g. ocr, office)
}
catch (PdfException e)
{
    Console.Error.WriteLine($"{e.Code}: {e.Message}");
}

对于 I/O（FileNotFoundException 等）和参数校验（ArgumentOutOfRangeException、ArgumentNullException），仍会抛出标准的 .NET 异常。

---

线程安全

• PdfDocument 的只读方法是线程安全的——可在多个线程间共享同一个文档。
• DocumentEditor 和各构建器在写入时不是线程安全的。请将写入串行化到单个线程，或用锁加以保护。

参见 并发指南。

异步模式

I/O 密集型方法提供接受 CancellationToken 的 *Async 变体（ExtractTextAsync、SaveAsync、SaveToStreamAsync 以及 Page.*Async 系列）。参见 异步指南。

NativeAOT

使用 -p:PublishAot=true 发布。无需额外配置——所有 P/Invoke 均为源码生成，不依赖反射，也不依赖动态代码。

---

完整示例

using PdfOxide.Core;

// --- Creation ---
using (var builder = DocumentBuilder.Create()
    .Title("Report").Author("PDF Oxide"))
{
    builder.LetterPage()
        .Heading(1, "Quarterly Report")
        .Paragraph("Generated by PDF Oxide.")
        .LinkUrl("https://oxide.fyi")
        .Done();
    builder.Save("report.pdf");
}

// --- Extraction ---
using var doc = PdfDocument.Open("report.pdf");
Console.WriteLine($"Pages: {doc.PageCount}");
foreach (var page in doc)
    Console.WriteLine($"Page {page.Index}: {page.ExtractText().Length} chars");

// Search with LINQ
var hits = doc.SearchAll("Report", caseSensitive: false)
    .GroupBy(r => r.Page);

// --- Editing ---
using (var editor = DocumentEditor.Open("report.pdf"))
{
    editor.Title = "Updated Title";
    editor.RotateAllPages(90);
    editor.SetFormFieldValue("name", "Jane Doe");
    editor.Save("report-updated.pdf");
}

// --- Rendering ---
byte[] png = doc.RenderPage(0, new RenderOptions { Dpi = 200, Format = RenderImageFormat.Png });
File.WriteAllBytes("page0.png", png);

Other Language Bindings

PDF Oxide 为所有主流生态系统提供原生绑定：Rust, Python, Node.js, WASM, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir。

下一步

• 类型与枚举 — 所有共享类型与枚举
• Page API 参考 — 各绑定间一致的逐页迭代方式
• C# 快速上手 — 教程