Rust排版引擎插件库typst-realize使用指南

介绍

typst-realize是一个基于Rust的排版引擎插件库，它构建在typst排版系统之上，专注于高效实现文档生成与格式化。这个库特别适合需要自动化生成格式精美文档的场景，如报告生成、发票制作、批量文档处理等。

typst-realize的主要特点：

• 高性能的文档渲染引擎
• 简洁的API设计
• 支持动态内容生成
• 可定制的文档样式
• 与Rust生态无缝集成

安装方法

在Cargo.toml中添加依赖：

[dependencies]
typst-realize = "0.5"  # 请使用最新版本

完整示例代码

1. 创建带样式的完整文档

use typst_realize::{Document, Style, Table};

fn main() {
    // 创建样式
    let style = Style::new()
        .font("SimSun")  // 使用宋体支持中文
        .font_size(14.0)
        .line_spacing(1.8)
        .margin(2.0);  // 2厘米页边距

    // 创建表格数据
    let sales_data = vec![
        ("产品A".into(), 1250.50),
        ("产品B".into(), 3200.75),
        ("产品C".into(), 980.25),
    ];

    // 生成表格
    let mut table = Table::new()
        .header(["产品名称", "销售额"])
        .alignments(&["left", "right"]);
    
    for (product, amount) in sales_data {
        table = table.row([product, format!("¥{:.2}", amount)]);
    }

    // 创建完整文档
    let doc = Document::new()
        .title("2023年销售报告")
        .author("销售部")
        .date("2023-12-31")
        .style(style)
        .content(r#"
            # 2023年度销售报告

            ## 销售概览
            
            本年度的销售情况如下：

            [table]

            ## 总结

            本年度总销售额达到XXXX元，同比增长XX%。
            
            ### 注意事项
            
            [warning]
        "#)
        .component(WarningBox {
            message: "数据仅供参考，正式报告以财务部为准".into(),
        })
        .content(table.to_string());

    // 渲染PDF
    doc.render_to_file("annual_report.pdf").unwrap();
}

// 自定义警告框组件
struct WarningBox {
    message: String,
}

impl typst_realize::Component for WarningBox {
    fn render(&self) -> String {
        format!(
            r#"
            #box(
                fill: yellow.lighten(90%),
                border: 1pt solid orange,
                inset: 10pt,
                radius: 5pt,
                [⚠️ **重要提示**: {}]
            )
            "#,
            self.message
        )
    }
}

2. 使用模板生成合同文档

use typst_realize::{Document, Template};
use serde_json::json;

fn main() {
    // 编译并缓存模板
    let template = Template::compile("contract_template.typ").unwrap();

    // 合同数据
    let contract_data = json!({
        "title": "技术开发合同",
        "contract_no": "TD2023001",
        "parties": {
            "party_a": "XX科技有限公司",
            "party_b": "YY信息技术有限公司"
        },
        "effective_date": "2023-01-01",
        "terms": [
            "项目内容：开发企业管理系统",
            "开发周期：6个月",
            "合同金额：人民币150,000元",
            "付款方式：分期付款",
            "违约责任：按合同法执行"
        ]
    });

    // 应用模板生成文档
    let doc = template.apply_context(contract_data).unwrap();
    
    // 保存PDF
    doc.render_to_file("tech_contract.pdf").unwrap();
}

3. 批量生成文档

use typst_realize::{Document, BatchRender};
use std::path::Path;

fn generate_invoice(data: &(String, f64, String)) -> Document {
    Document::new()
        .title(format!("发票-{}", data.2))
        .content(format!(
            r#"
            # 发票

            **客户**: {}  
            **金额**: ¥{:.2}  
            **发票编号**: {}  
            **日期**: {}

            [payment_info]
            "#,
            data.0, data.1, data.2, "2023-12-15"
        ))
}

fn main() {
    // 准备批量数据
    let invoices = vec![
        ("客户A".into(), 1250.50, "INV2023001".into()),
        ("客户B".into(), 3200.75, "INV2023002".into()),
        ("客户C".into(), 980.25, "INV2023003".into()),
    ];

    // 创建批量渲染任务
    let mut batch = BatchRender::new()
        .parallel(true)  // 启用并行渲染
        .timeout(30);    // 30秒超时

    // 添加文档到批量任务
    for (i, data) in invoices.iter().enumerate() {
        let doc = generate_invoice(data);
        let output_path = format!("invoices/invoice_{}.pdf", i + 1);
        batch.add_document(doc, output_path);
    }

    // 确保输出目录存在
    std::fs::create_dir_all("invoices").unwrap();

    // 执行批量渲染
    match batch.execute() {
        Ok(_) => println!("批量发票生成完成！"),
        Err(e) => eprintln!("生成失败: {}", e),
    }
}

最佳实践建议

1. 项目结构组织

// 推荐的项目结构：
// src/
//   components/     // 自定义组件
//     warning_box.rs
//     invoice_header.rs
//   templates/      // 模板文件
//     contract.typ
//     report.typ
//   models/         // 数据模型
//     invoice.rs
//     report.rs
//   main.rs         // 主程序

1. 错误处理优化

use typst_realize::RenderError;

fn render_document() -> Result<(), RenderError> {
    let doc = Document::new()
        .content("# 重要文档")
        .render_to_file("important.pdf")?;
    
    Ok(())
}

fn main() {
    if let Err(e) = render_document() {
        eprintln!("文档渲染失败: {}", e);
        std::process::exit(1);
    }
}

1. 配置管理

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct AppConfig {
    default_font: String,
    output_dir: String,
    template_dir: String,
}

fn load_config() -> AppConfig {
    // 可以从配置文件加载
    AppConfig {
        default_font: "SimSun".into(),
        output_dir: "output".into(),
        template_dir: "templates".into(),
    }
}