docx-rs

The DocumentTreeVisitor trait allows you to implement custom logic for traversing the DOCX document tree. By implementing this trait, you can intercept specific nodes (like paragraphs, runs, or pictures) as the library recurses through the document structure. This is useful for collecting metadata, finding specific elements, or extracting media dependencies.

Because the trait provides default empty implementations for all methods, you only need to implement the hooks for the specific elements you are interested in.

use docx_rs::DocumentTreeVisitor;
// Note: Actual imports depend on your project structure

struct MyVisitor;

impl DocumentTreeVisitor for MyVisitor {
    fn visit_paragraph(&mut self, _paragraph: &mut Paragraph) {
        // Custom logic when a paragraph is encountered
    }

    fn visit_run(&mut self, _run: &mut Run) {
        // Custom logic when a run is encountered
    }
}

When preparing a .docx package, the library distinguishes between physical media (the actual image bytes) and relationships (the XML pointers within specific parts like the body, headers, or footers).

• MediaRegistry: A package-global store that ensures physical media bytes are stored only once. It deduplicates identical images using a combination of preferred IDs and content fingerprints (length + CRC32).
• CollectedPart: A part-local collection of relationships and footnotes. While multiple CollectedPart instances (e.g., one for the body, one for the header) share a single MediaRegistry, they maintain their own unique relationship IDs to comply with the Open Packaging Conventions (OPC).

This separation allows a single image to be referenced in both the body and the header without duplicating the bytes in the final ZIP file, while still maintaining valid, independent relationship entries for each XML part.

To extract relationships and footnotes from a specific part of a document for packaging, use the specialized collection functions. These functions require a mutable reference to a MediaRegistry to handle global media deduplication.

• Main Document: Use collect_document_part(&mut document, &mut registry) to gather relationships and footnotes from the main body.
• Headers: Use collect_header_part(&mut header, &mut registry).
• Footers: Use collect_footer_part(&mut footer, &mut registry).

Each function returns a CollectedPart containing a list of relationships (mapping IDs to media paths) and footnotes.

Note: If you only need footnotes without touching media, use collect_document_footnotes(&mut document).

// Example of collecting data from a document and its header
let mut registry = MediaRegistry::default();

// Collect from main document
let body_part = collect_document_part(&mut document, &mut registry);

// Collect from header
let header_part = collect_header_part(&mut header, &mut registry);

// Finally, extract the physical media for the ZIP package
let media_files = registry.into_media();

The Docx struct is the primary entrypoint for constructing a .docx file. You can initialize a new document using Docx::new() and use a builder pattern to add content such as paragraphs, tables, styles, headers, footers, and sections.

To finalize the document, you have two main options:

1. build(): Consumes the Docx instance and returns an XMLDocx object containing all rendered XML parts in memory. This is useful if you need to manipulate the rendered parts before writing.
2. pack<W>(writer): Consumes the Docx instance and streams the XML parts directly into a ZIP archive writer. This is more memory-efficient for large documents.

Note: Adding elements like paragraphs or tables with numbering will automatically update the document relationships to include numberings.xml to ensure compatibility with Word Online.

// Example workflow
let docx = Docx::new()
    .add_paragraph(paragraph)
    .add_table(table)
    .styles(my_styles);

// Option 1: Build to memory
let xml_docx = docx.build();

// Option 2: Stream directly to a file/writer
let file = std::fs::File::create("output.docx")?;
let mut zip_writer = zip::ZipWriter::new(file);
docx.pack(&mut zip_writer)?;