rust_xlsxwriter×Serde终极指南:Rust结构体一键序列化为Excel
rust_xlsxwriter×Serde终极指南:Rust结构体一键序列化为Excel
📊 rust_xlsxwriter 是 Rust 生态中创建 Excel XLSX 文件的库,配合 Serde 序列化支持,只需几行代码就能把 Rust 结构体(struct)或结构体数组一键序列化写入 Excel 工作表:字段名自动变成表头,值自动填入下方单元格,还能控制表头样式、数字格式和 Excel 表格外观。本指南带你从启用 feature 到属性宏进阶,完整掌握 Serde 序列化导出 Excel 的最快路径。
为什么 rust_xlsxwriter + Serde 是 Excel 导出组合
传统做法是逐格调用 write_string、write_number 手动填充,列一多代码又长又容易错位。而 rust_xlsxwriter 实现了 Serde 的 serde::Serializer trait(核心实现在 src/serializer.rs),让 Worksheet 直接充当序列化目标:
- 结构体 → 二维网格:每个字段映射为一列表头,每个实例映射为一行数据;
- 一次
serialize()调用:数组或向量数据按行依次写入,无需手写行列索引; - 格式跟着结构体走:通过
#[xlsx]属性把重命名、数字格式、列宽、表格样式直接"焊"在结构体定义上。
完整文档说明在 src/serializer.rs 文件头部,示例代码集中在 examples/ 目录下(如 examples/app_serialize.rs)。
3步启用:开启 serde feature 并写出第一张表
第1步:安装并启用 serde feature
cargo add rust_xlsxwriter -F serde
feature 定义见 Cargo.toml 中的 serde = ["dep:serde", "dep:rust_xlsxwriter_derive"] 一行。
第2步:定义可序列化结构体
use rust_xlsxwriter::{Workbook, XlsxSerialize};
use serde::Serialize;
#[derive(XlsxSerialize, Serialize)]
#[xlsx(header_format = Format::new().set_bold())]
struct Produce {
#[xlsx(rename = "Item", column_width = 12.0)]
fruit: &'static str,
#[xlsx(rename = "Price", num_format = "$0.00")]
cost: f64,
}
第3步:设置表头、序列化、保存
let mut workbook = Workbook::new();
let worksheet = workbook.add_worksheet();
// 从 (0, 0) 位置开始写入表头
worksheet.set_serialize_headers::<Produce>(0, 0)?;
// 一次序列化整个数组
worksheet.serialize(&items)?;
workbook.save("serialize.xlsx")?;
对应完整示例:examples/doc_xlsxserialize_intro.rs。
如何选择:3 种表头设置方式对比
rust_xlsxwriter 提供三组方法,区别在于"表头信息从哪来"(详见 src/serializer.rs 的文档说明):
| 方式 | 方法 | 结构体需要 | 适用场景 |
|---|---|---|---|
| ① 序列化推断 | serialize_headers() / serialize_headers_with_format() |
仅 Serialize |
需要传入一个实例供库推断字段,改动最小的方案 |
| ② 反序列化推断 | deserialize_headers() / deserialize_headers_with_format() |
Serialize + Deserialize |
只需类型不需实例,可配合 SerializeFieldOptions 自定义表头 |
| ③ 属性宏声明 | set_serialize_headers() |
Serialize + XlsxSerialize |
格式内联在结构体属性中,代码最少(官方作者主要用法) |
💡 选择建议:结构体归你控制 → 用方式③;结构体有 Deserialize → 用方式②省事;结构体是第三方定义且只能 Serialize → 用方式①。
方式②的完整示例(含表头加粗、边框、背景色)见 examples/doc_worksheet_serialize_intro2.rs;方式①的"自定义表头+隐藏表头"进阶用法见 examples/doc_worksheet_serialize_headers_with_options.rs。
#[xlsx] 属性速查表:让输出更精美
XlsxSerialize 支持两类属性,把格式定义"锁"在结构体上(完整说明:src/serializer.rs)。
容器属性(写在 struct 上)
#[derive(XlsxSerialize, Serialize)]
#[xlsx(header_format = Format::new().set_bold())] // 表头格式
#[xlsx(hide_headers)] // 隐藏表头行
#[xlsx(table_default)] // 自动附加默认样式的 Excel 表格
#[xlsx(table_style = TableStyle::Medium10)] // 指定表格样式
struct Produce { /* ... */ }
给数据区加上 Excel 表格后,自带筛选、隔行底纹等效果,一行属性搞定:examples/doc_worksheet_serialize_table1.rs、examples/doc_xlsxserialize_table_style.rs。
字段属性(写在字段上)
struct Produce {
#[xlsx(rename = "Item")] // 重命名表头(不影响其他序列化)
fruit: &'static str,
#[xlsx(num_format = "$0.00")] // 数字格式(货币示例)
cost: f64,
#[xlsx(column_width = 12.0)] // 自动设置列宽
#[xlsx(value_format = Format::new().set_font_color("#FF0000"))] // 数据区字体颜色
fruit2: &'static str,
}
示例文件:examples/doc_xlsxserialize_rename.rs、examples/doc_xlsxserialize_num_format.rs、examples/doc_xlsxserialize_value_format.rs。
常见场景:跳过字段与日期时间
跳过不想导出的字段
比如结构体里有内部 ID 字段不希望出现在 Excel 中,用三种方式之一跳过:
- Serde 属性:
#[serde(skip)](所有序列化都跳过) - xlsx 属性:
#[xlsx(skip)](仅 Excel 序列化跳过) - 运行时:
CustomSerializeField::skip()
示例:examples/doc_xlsxserialize_skip.rs、examples/doc_worksheet_serialize_headers_skip1.rs。
序列化日期和时间
支持的时间类型:
ExcelDateTime:库自带类型,自动按 Excel 日期数值序列化;chrono的NaiveDate/NaiveTime/NaiveDateTime(需chronofeature);jiff的civil类型(需jifffeature)。
⚠️ 注意:chrono/jiff 类型默认会序列化为字符串。若要写成 Excel 原生日期(数字+日期格式),需用 Utility::serialize_datetime_to_excel() 转换,或改用 ExcelDateTime。Excel 本身不处理时区,库也不编码时区信息。
示例:examples/doc_worksheet_serialize_datetime1.rs。
避坑指南:Excel 序列化的边界
Excel 是二维网格,序列化能力受此约束(官方说明:src/serializer.rs):
- 只支持结构体及其向量:
T或Vec<T>(T: Serialize); - 不支持 Map / HashMap:无固定 schema,且字段顺序不保证;
#[serde(flatten)]不可用:flatten 会把固定字段转成动态 map,因此带 flatten 的结构体无法直接序列化(可用CustomSerializeField::skip()等手段剔除问题字段);- 嵌套结构体有限制:最好先设计好"数据最终在表格里长什么样",再定义结构体。
碰到无法序列化的数据,还有退路:直接用 Worksheet::write()、write_row()、write_column() 等标准 API 手动写入。
总结:Rust 结构体导出 Excel 的最短路径
| 需求 | 推荐做法 |
|---|---|
| 快速把结构体数组导出成表 | deserialize_headers() + serialize() |
| 结构体可控、想要最少代码 | XlsxSerialize 派生 + #[xlsx] 属性 |
| 表头要样式/表格/隔行底纹 | header_format / table_default / table_style |
| 字段重命名或隐藏列 | #[xlsx(rename)] / #[xlsx(skip)] |
| 金额、日期等特殊显示 | num_format、value_format、ExcelDateTime |
至此,你已经掌握 rust_xlsxwriter 的 Serde 序列化全貌:从一行 cargo add 命令开始,到属性宏精细控制每一列的外观。更多可运行示例可参考 examples/README.md 索引,源码细节随时翻 src/serializer.rs——这是库中实现 Serde 序列化 trait 的核心模块。