注释编辑

PDF Oxide 通过 PdfPage 对象提供 DOM 级别的注释访问。你可以读取现有注释、添加新注释（链接、高亮、便签）、修改注释属性、删除注释，以及将注释扁平化到页面内容中。

获取注释

列出所有注释

from pdf_oxide import PdfDocument

doc = PdfDocument("annotated.pdf")
page = doc.page(0)

for ann in page.annotations():
    print(f"Type: {ann.subtype}")
    print(f"Rect: {ann.rect}")
    if ann.contents:
        print(f"Contents: {ann.contents}")

import { WasmPdfDocument } from "pdf-oxide-wasm";

const doc = new WasmPdfDocument(bytes);
const annotations = doc.getAnnotations(0);

for (const ann of annotations) {
  console.log(`Type: ${ann.subtype}`);
  console.log(`Rect: ${JSON.stringify(ann.rect)}`);
  if (ann.contents) {
    console.log(`Contents: ${ann.contents}`);
  }
}
doc.free();

use pdf_oxide::api::Pdf;

let mut doc = Pdf::open("annotated.pdf")?;
let page = doc.page(0)?;

for ann in page.annotations() {
    println!("Type: {:?}", ann.subtype());
    println!("Rect: {:?}", ann.rect());
    if let Some(contents) = ann.contents() {
        println!("Contents: {}", contents);
    }
    if let Some(color) = ann.color() {
        println!("Color: {:?}", color);
    }
}

按索引访问

let page = doc.page(0)?;

if let Some(ann) = page.annotation(0) {
    println!("First annotation: {:?}", ann.subtype());
}

println!("Total annotations: {}", page.annotation_count());

查找注释

按 ID

let page = doc.page(0)?;
let id = page.annotations()[0].id();

if let Some(ann) = page.find_annotation(id) {
    println!("Found: {:?}", ann.subtype());
}

按区域

在矩形区域内查找注释。

use pdf_oxide::geometry::Rect;

let page = doc.page(0)?;
let region = Rect::new(0.0, 700.0, 612.0, 92.0);
let top_annotations = page.find_annotations_in_region(region);

for ann in top_annotations {
    println!("Annotation in header area: {:?}", ann.subtype());
}

按类型

use pdf_oxide::AnnotationSubtype;

let page = doc.page(0)?;
let highlights = page.find_annotations_by_type(AnnotationSubtype::Highlight);
println!("Found {} highlights", highlights.len());

添加注释

添加链接

doc = PdfDocument("input.pdf")
page = doc.page(0)

# Add a clickable URL link
page.add_link(100, 700, 150, 12, "https://example.com")
doc.save_page(page)
doc.save("with-link.pdf")

use pdf_oxide::api::Pdf;
use pdf_oxide::writer::LinkAnnotation;
use pdf_oxide::geometry::Rect;

let mut doc = Pdf::open("input.pdf")?;
let mut page = doc.page(0)?;

let link = LinkAnnotation::uri(
    Rect::new(100.0, 700.0, 150.0, 12.0),
    "https://example.com"
);
page.add_annotation(link);
doc.save_page(page)?;
doc.save("with-link.pdf")?;

添加文本高亮

doc = PdfDocument("input.pdf")
page = doc.page(0)

# Yellow highlight
page.add_highlight(100, 700, 200, 12, (1.0, 1.0, 0.0))
doc.save_page(page)
doc.save("highlighted.pdf")

use pdf_oxide::writer::TextMarkupAnnotation;
use pdf_oxide::TextMarkupType;
use pdf_oxide::geometry::Rect;

let mut doc = Pdf::open("input.pdf")?;
let mut page = doc.page(0)?;

let highlight = TextMarkupAnnotation::from_rect(
    TextMarkupType::Highlight,
    Rect::new(100.0, 700.0, 200.0, 12.0),
).with_color(1.0, 1.0, 0.0);  // Yellow

page.add_annotation(highlight);
doc.save_page(page)?;
doc.save("highlighted.pdf")?;

添加便签

doc = PdfDocument("input.pdf")
page = doc.page(0)

page.add_note(50, 750, "Review this section before publishing.")
doc.save_page(page)
doc.save("with-notes.pdf")

use pdf_oxide::writer::TextAnnotation;
use pdf_oxide::geometry::Rect;

let mut doc = Pdf::open("input.pdf")?;
let mut page = doc.page(0)?;

let note = TextAnnotation::new(
    Rect::new(50.0, 750.0, 24.0, 24.0),
    "Review this section before publishing."
);
page.add_annotation(note);
doc.save_page(page)?;
doc.save("with-notes.pdf")?;

删除注释

按索引移除

doc = PdfDocument("input.pdf")
page = doc.page(0)

# Remove the first annotation
page.remove_annotation(0)
doc.save_page(page)
doc.save("cleaned.pdf")

let mut page = doc.page(0)?;
page.remove_annotation(0);  // Returns Option<AnnotationWrapper>
doc.save_page(page)?;

按 ID 移除

let mut page = doc.page(0)?;

// Get the ID of an annotation to remove
let ann_id = page.annotations()[0].id();
page.remove_annotation_by_id(ann_id);

doc.save_page(page)?;
doc.save("cleaned.pdf")?;

修改注释

访问可变注释以修改其属性。

let mut page = doc.page(0)?;

// Modify annotations through mutable access
for ann in page.annotations_mut() {
    // Change contents text
    ann.set_contents("Updated comment");

    // Change position
    ann.set_rect(pdf_oxide::geometry::Rect::new(100.0, 700.0, 200.0, 20.0));

    // Change color
    ann.set_color(1.0, 0.0, 0.0);  // Red
}

doc.save_page(page)?;
doc.save("modified.pdf")?;

修改特定注释

let mut page = doc.page(0)?;

if let Some(ann) = page.annotation_mut(0) {
    ann.set_contents("First annotation - updated");
}

doc.save_page(page)?;

可变查找

let mut page = doc.page(0)?;
let target_id = page.annotations()[0].id();

if let Some(ann) = page.find_annotation_mut(target_id) {
    ann.set_contents("Found and updated");
    ann.set_color(0.0, 1.0, 0.0);  // Green
}

doc.save_page(page)?;

扁平化注释

扁平化将注释的外观流渲染到页面内容中并移除注释对象。这使得注释变为永久的且不可编辑。

扁平化单个页面

doc = PdfDocument("annotated.pdf")
doc.flatten_page_annotations(0)
doc.save("flat.pdf")

import { WasmPdfDocument } from "pdf-oxide-wasm";

const doc = new WasmPdfDocument(bytes);
doc.flattenPageAnnotations(0);
const output = doc.save();
doc.free();

let mut editor = DocumentEditor::open("annotated.pdf")?;
editor.flatten_page_annotations(0)?;
editor.save("flat.pdf")?;

扁平化所有注释

doc = PdfDocument("annotated.pdf")
doc.flatten_all_annotations()
doc.save("flat.pdf")

import { WasmPdfDocument } from "pdf-oxide-wasm";

const doc = new WasmPdfDocument(bytes);
doc.flattenAllAnnotations();
const output = doc.save();
doc.free();

let mut editor = DocumentEditor::open("annotated.pdf")?;
editor.flatten_all_annotations()?;
editor.save("flat.pdf")?;

检查和撤销扁平化标记

doc.flatten_page_annotations(0)
print(doc.is_page_marked_for_flatten(0))  # True

doc.unmark_page_for_flatten(0)
print(doc.is_page_marked_for_flatten(0))  # False

editor.flatten_page_annotations(0)?;
assert!(editor.is_page_marked_for_flatten(0));

editor.unmark_page_for_flatten(0);
assert!(!editor.is_page_marked_for_flatten(0));

完整 API 参考

PdfPage 注释方法

方法	返回值	描述
annotations()	&[AnnotationWrapper]	获取所有注释
annotation(index)	Option<&AnnotationWrapper>	按索引获取注释
annotations_mut()	&mut [AnnotationWrapper]	获取可变注释
annotation_mut(index)	Option<&mut AnnotationWrapper>	Get mutable annotation by index
annotation_count()	usize	注释数量
has_annotations_modified()	bool	Check if annotations were changed
add_annotation(ann)	AnnotationId	Add a new annotation
remove_annotation(index)	Option<AnnotationWrapper>	Remove by index
remove_annotation_by_id(id)	Option<AnnotationWrapper>	Remove by ID
find_annotation(id)	Option<&AnnotationWrapper>	Find by ID
find_annotation_mut(id)	Option<&mut AnnotationWrapper>	Find mutable by ID
find_annotations_in_region(rect)	Vec<&AnnotationWrapper>	Find in area
find_annotations_by_type(subtype)	Vec<&AnnotationWrapper>	Find by type

AnnotationWrapper 属性

方法	返回值	描述
id()	AnnotationId	唯一标识符
subtype()	AnnotationSubtype	注释类型
rect()	Rect	Position and size
contents()	Option<&str>	文本内容
color()	Option<(f32, f32, f32)>	RGB 颜色
is_modified()	bool	Has been changed
is_new()	bool	Was added (not from source)
set_contents(text)	()	Set text contents
set_rect(rect)	()	Set position/size
set_color(r, g, b)	()	Set RGB color

DocumentEditor 注释方法

方法	返回值	描述
flatten_page_annotations(page)	Result<()>	扁平化一个页面
flatten_all_annotations()	Result<()>	扁平化所有页面
is_page_marked_for_flatten(page)	bool	检查扁平化状态
unmark_page_for_flatten(page)	()	取消待处理的扁平化

高级示例：注释审查工作流

use pdf_oxide::api::Pdf;
use pdf_oxide::writer::{TextAnnotation, TextMarkupAnnotation};
use pdf_oxide::{AnnotationSubtype, TextMarkupType};
use pdf_oxide::geometry::Rect;

let mut doc = Pdf::open("draft.pdf")?;
let count = doc.page_count()?;

for i in 0..count {
    let mut page = doc.page(i)?;

    // Find all text containing "TODO"
    let todos = page.find_text_containing("TODO");
    for t in &todos {
        // Add a highlight over the TODO text
        let highlight = TextMarkupAnnotation::from_rect(
            TextMarkupType::Highlight,
            t.bbox(),
        ).with_color(1.0, 0.5, 0.0);  // Orange
        page.add_annotation(highlight);

        // Add a note next to it
        let note = TextAnnotation::new(
            Rect::new(t.bbox().x - 30.0, t.bbox().y, 24.0, 24.0),
            &format!("TODO found: {}", t.text()),
        );
        page.add_annotation(note);
    }

    doc.save_page(page)?;
}

doc.save("reviewed.pdf")?;

相关页面

• 文本编辑 – 直接修改文本内容
• 涂黑 – 使用涂黑注释涂黑内容
• 页面操作 – 页面级操作
• 表单字段编辑 – 交互式表单字段