easydoc-writer

DOCX document writer with fluent builder API and atomic file output

English | 简体中文

Overview · Capabilities · Architecture · Quick Start · API · Upstream · Quality

Status: alpha pre-release (latest on crates.io) MSRV: Rust 1.88 Edition: 2024 Resolver: 3 Maturity: Alpha -- public API may change Last verified: 2026-08-11

1. Overview

easydoc-writer is a Rust crate for generating DOCX documents from a semantic document model (DocumentContent) or via a fluent builder API. It is part of the easydoc-rust workspace and corresponds to the write layer of Java EasyExcel (com.alibaba.excel).

1.1 What It Is

• A DOCX generator built on docx-rs that renders the DocumentContent semantic model into OOXML.
• Provides a fluent DocBuilder API for programmatic document construction.
• Supports atomic file writes via temporary file + persist (no partial output on failure).
• Includes a DocEditor for text replacement in existing DOCX files.
• Lifecycle hooks (DocWriteHandler) for before/after document, paragraph, and table callbacks.

1.2 What It Is Not

• Not a DOCX reader -- use easydoc-reader for reading.
• Not a Markdown converter -- use easydoc-markdown for conversion.
• Not a full OOXML style engine -- advanced formatting (columns, watermarks, macros) is out of scope.
• Not a template engine -- use easydoc-template for placeholder-based template filling.

2. Capabilities

2.1 Write Capability Matrix

2.2 Edit Capability Matrix

2.3 Status Definitions

3. Architecture

DocumentContent (semantic model from easydoc-core)
        │
        ▼
content_renderer::render_document_content()
        │
        ▼
docx-rs Docx builder (OOXML construction)
        │
        ▼
DocWriteExecutor::save()
        │
        ▼
AtomicFile (temp file + persist)
        │
        ▼
Output .docx file

3.1 Crate Dependencies

flowchart TB
    USER["Application"] --> WRITER["easydoc-writer"]
    WRITER --> CORE["easydoc-core"]
    WRITER --> OOXML["easydoc-ooxml"]
    WRITER --> DOCX["docx-rs"]
    WRITER --> OXIDE["office_oxide"]

3.2 Key Types

3.3 Handler Lifecycle

before_document
    ├── before_paragraph / after_paragraph  (per paragraph)
    ├── before_table / after_table          (per table)
    │       ├── before_cell / after_cell    (per cell)
    └── (other blocks)
after_document

4. Quick Start

4.1 Installation

[dependencies]
easydoc-writer = "0.1.0-alpha"

4.2 Fluent Builder

use easydoc_writer::DocBuilder;
use easydoc_core::HeadingLevel;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    DocBuilder::new("report.docx")
        .title("Quarterly Report")
        .author("Alice")
        .add_heading("Introduction", HeadingLevel::H1)
        .add_paragraph(
            easydoc_writer::Paragraph::new()
                .add_run(easydoc_writer::Run::new("This is the introduction."))
        )
        .add_heading("Results", HeadingLevel::H2)
        .add_table(easydoc_writer::Table::from_data(&vec![
            vec!["Metric", "Value"],
            vec!["Revenue", "$1.2M"],
        ]))
        .build()?
        .save()?;
    Ok(())
}

4.3 Render from Semantic Model

use easydoc_core::{DocumentContent, DocumentBlock, DocumentTextRun};
use easydoc_writer::content_renderer::render_document_content;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = DocumentContent {
        blocks: vec![
            DocumentBlock::Heading {
                level: 1,
                runs: vec![DocumentTextRun {
                    text: "Hello World".into(),
                    ..Default::default()
                }],
            },
            DocumentBlock::Paragraph(vec![DocumentTextRun {
                text: "Generated from semantic model.".into(),
                ..Default::default()
            }]),
        ],
        ..Default::default()
    };

    let docx = render_document_content(&content)?;
    // docx.pack() to write to file
    Ok(())
}

4.4 Edit Existing Document

use easydoc_writer::DocEditor;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    DocEditor::open("template.docx".as_ref())?
        .replace_text("{name}", "Alice")
        .replace_text("{date}", "2026-08-11")
        .save()?;
    Ok(())
}

5. API Reference

5.1 Core API

5.2 Error Model

6. Upstream Compatibility

6.1 Java EasyExcel Mapping

This crate corresponds to the write layer of Java EasyExcel:

6.2 Differences from Java

• No reflection: Rust uses typed structs instead of Java reflection for data binding.
• Atomic writes: All file output uses temp-file + persist; Java EasyExcel does not guarantee this.
• Handler model: Rust handlers use trait methods with explicit contexts; Java uses interface implementations.
• Style system: Rust style configuration is struct-based (ParagraphStyle, TableStyle, FontConfig); Java uses builder chains.

7. Quality & Testing

7.1 Unsafe Policy

This crate uses #![deny(unsafe_code)]. The workspace enforces unsafe_code = "forbid" via [workspace.lints.rust].

7.2 Test Categories

7.3 Building & Testing

cargo check -p easydoc-writer
cargo test -p easydoc-writer
cargo clippy -p easydoc-writer -- -D warnings
cargo doc -p easydoc-writer --no-deps

Back to top · docs.rs · crates.io · Issues