fast_excel/lib.rs
1//! # excel — 通用 Excel 导入导出工具
2//!
3//! 对标 Java 生态的 EasyExcel,面向"百万行 + 批量落库 + 单元格图片 + 多 sheet +
4//! 动态表头"的真实业务场景。整个工具只依赖纯 Rust 库(无 JVM / 无 Office 组件)。
5//!
6//! ## 能力总览
7//!
8//! | 能力 | 实现方式 |
9//! |---|---|
10//! | 百万行读取 | `quick-xml` SAX 事件流逐行解析,内存与行数无关([`SheetStream`]) |
11//! | 百万行写出 | `rust_xlsxwriter` 常量内存工作表,边写边落临时文件 |
12//! | 批量落库 | [`ImportRunner::commit`]:`spawn_blocking` 解析 + 有界通道 + 分批事务([`BatchSink`]) |
13//! | 单元格图片 | 标准 drawing 锚点 + WPS `DISPIMG`;按行对应,图片字节按需读 |
14//! | 多 sheet | 读:`SheetSelector::{Name,Names,All}`;写:[`ExcelWriter::add_sheet`] / [`ExportRunner::export_multi_sheet`] |
15//! | 动态表头 | 别名 / 模糊匹配 / 归一化(全角、空格、`*` 必填标记)/ 列序回退([`HeaderOptions`]) |
16//! | 注解式映射 | `#[derive(ExcelRow)]`(`excel-macros`) |
17//! | 执行器 | `#[derive(ExcelExecutor)]` 自动注册执行器工厂([`inventory`](https://docs.rs/inventory) 静态收集,零初始化):[`executor_for::<T>`] / [`executor_by_name`] |
18//! | 导入模板 | 必填红字表头 + 示例行 + 下拉 + 说明 sheet([`TemplateSpec`]) |
19//! | 导出 | 游标分批拉取 + 流式写文件([`ExportRunner`]);CSV 兜底([`write::write_csv`]) |
20//!
21//! 完整用法与百万行调优见 crate 根目录 `README.md`。
22//!
23//! ## 最小示例(声明式)
24//!
25//! ```no_run
26//! use std::sync::Arc;
27//! use fast_excel::{BatchSink, ExcelError, ExcelReader, ExcelRow, ImportRunner, SheetSelector, ZipSource};
28//!
29//! #[derive(ExcelRow, Debug)]
30//! #[excel(sheet = "产品导入")]
31//! struct ProductRow {
32//! #[excel(header = "工厂名称", alias = ["工厂", "厂名"], required)]
33//! factory_name: String,
34//! #[excel(header = "品名", required)]
35//! name: String,
36//! #[excel(header = "MOQ")]
37//! moq: Option<i32>,
38//! }
39//!
40//! # async fn demo(db_sink: Arc<dyn BatchSink<ProductRow>>) -> Result<(), ExcelError> {
41//! let report = ImportRunner::new()
42//! .sheets(SheetSelector::All) // 多 sheet 合并导入
43//! .batch_size(500) // 每 500 行一批
44//! .commit(ZipSource::open("products.xlsx")?, db_sink)
45//! .await?;
46//! println!("成功 {} 行,失败 {} 行", report.success_rows, report.error_rows);
47//! # Ok(()) }
48//! ```
49//!
50//! ## 落库实现约定
51//!
52//! [`BatchSink::save`] 拿到的是一批已解析、已校验的行,事务边界由业务侧决定
53//! (推荐"一批一个事务 + `insert_many`")。项目内 sea-orm 实体用
54//! `Entity::insert_many_with_fill(models, &tx)` 即可同时拿到主键生成、审计字段
55//! 自动填充与租户注入。
56
57// 让派生宏在 crate 内部(单元测试 / 文档测试)也能用 `::fast_excel::` 路径
58extern crate self as fast_excel;
59
60pub mod column;
61pub mod error;
62pub mod executor;
63pub mod export;
64pub mod expr;
65pub mod funcs;
66pub mod header;
67pub mod import;
68pub mod model;
69pub mod read;
70pub mod task;
71pub mod value;
72pub mod write;
73
74pub use column::{ColumnDef, ColumnKind};
75pub use error::{ExcelError, Result};
76pub use expr::{CellExpr, RowValues};
77pub use executor::{
78 ErasedExecutor, ExcelExecutor, Executor, ExecutorConfigEntry, ExecutorEntry, JsonBatchSink,
79 commit_json_by_name, executor_by_name, executor_config_entry, executor_entry, executor_for,
80 export_bytes_by_name, identity_import_runner, identity_sheet_options, preview_by_name,
81 registered_executors, registered_names,
82};
83pub use export::{ExportRunner, ExportStats, Page};
84pub use header::{
85 HeaderAnalysis, HeaderMap, HeaderOptions, MatchKind, ResolvedColumn, excel_column_name,
86 resolve_headers, simple_columns,
87};
88pub use import::{
89 BatchConfig, BatchSink, FnSink, ImportPreview, ImportProgress, ImportReport, ImportRunner,
90 NoopSink, PreviewRow, ProgressFn, RowError, SheetHeader,
91};
92pub use model::{ColumnError, DynamicRow, ExcelRow, RowData, RowImage};
93pub use read::{
94 CfRule, CellImage, CellStyle, Comment, ComputedColumn, ConditionalFormat, CsvReader,
95 DataValidation, EntryReader, ExcelReader, Hyperlink, MergeRange, ReadOptions, RowFilter,
96 SheetInfo, SheetSelector, SheetStream, Styles, ZipSource, extract_all_images,
97 extract_embedded_images, extract_images_of_sheet, extract_wps_cellimages, parse_dispimg_id,
98};
99pub use task::{
100 ExportTaskContext, ExportTaskEntry, ExportTaskFn, ExportTaskFuture, ExportTaskKind,
101 ExportTaskOutput, XLSX_MIME, export_task_entry, export_task_registered, registered_export_tasks,
102 run_export_task, run_file_task, run_rows_task,
103};
104pub use value::{Cell, CellValue, FromCell, IntoCell};
105pub use write::{
106 DynamicExportRunner, DynamicSheet, ExcelWriter, ReferenceSheet, SheetOptions, SheetWriter,
107 TemplateSpec, WriteOptions, align_row, build_template, named_xlsx_bytes,
108 positional_xlsx_bytes, write_csv, write_named_xlsx, write_positional_xlsx,
109};
110
111/// `#[derive(ExcelRow)]` 派生宏(与 [`ExcelRow`] trait 同名,不同命名空间)
112pub use fast_excel_macros::ExcelRow;
113
114/// `#[derive(ExcelExecutor)]` 派生宏:注册执行器工厂(与 [`ExcelExecutor`] trait 同名)
115pub use fast_excel_macros::ExcelExecutor;
116
117/// 派生宏生成的 `inventory::submit!` 通过此路径引用;通常无需直接使用
118#[doc(hidden)]
119pub use ::inventory;
120
121/// 为某个执行器(按注册名)登记**模型级默认配置**,让按名/按类型拿到的 runner 自动带上
122/// 计算列、合并开关、批大小等,不用在每个调用点重复拼装。
123///
124/// 配置项是普通函数 / 非捕获闭包(`fn` 指针),链接期注册:
125///
126/// ```ignore
127/// use fast_excel::executor_config;
128///
129/// // 只配导入
130/// executor_config!("product",
131/// import = |r: fast_excel::ImportRunner| r.merged(true).batch_size(500));
132///
133/// // 同时配导入 + 导出
134/// executor_config!("product",
135/// import = |r: fast_excel::ImportRunner| r.merged(true),
136/// export = |s: fast_excel::SheetOptions| s.computed(
137/// fast_excel::ColumnDef::new("导出日期"),
138/// |_row| fast_excel::CellValue::Text(fast_excel::funcs::date_fmt(
139/// fast_excel::funcs::today(), "%Y-%m-%d")),
140/// ));
141/// ```
142#[macro_export]
143macro_rules! executor_config {
144 ($name:expr, import = $imp:expr, export = $exp:expr $(,)?) => {
145 $crate::__executor_config_submit!($name, $imp, $exp);
146 };
147 ($name:expr, export = $exp:expr, import = $imp:expr $(,)?) => {
148 $crate::__executor_config_submit!($name, $imp, $exp);
149 };
150 ($name:expr, import = $imp:expr $(,)?) => {
151 $crate::__executor_config_submit!($name, $imp, $crate::identity_sheet_options);
152 };
153 ($name:expr, export = $exp:expr $(,)?) => {
154 $crate::__executor_config_submit!($name, $crate::identity_import_runner, $exp);
155 };
156}
157
158/// `executor_config!` 的内部展开;请勿直接使用
159#[doc(hidden)]
160#[macro_export]
161macro_rules! __executor_config_submit {
162 ($name:expr, $imp:expr, $exp:expr) => {
163 #[allow(non_upper_case_globals, unused)]
164 const _: () = {
165 $crate::inventory::submit! {
166 $crate::ExecutorConfigEntry {
167 name: $name,
168 import: $imp,
169 export: $exp,
170 }
171 }
172 };
173 };
174}
175/// 注册一个异步导出任务(唯一宏:行导出 / 文件导出都用它)。
176///
177/// 展开后直接向 `inventory` 提交任务定义,链接期即完成注册:
178/// **没有执行器结构体、没有 `install()`、不需要在 `main.rs` 聚合**。
179/// 导出中心按 `task_type` 查到函数后直接调用。
180///
181/// # 形态一:行数据导出(业务只查数据,引擎写 xlsx)
182/// ```ignore
183/// fast_excel::export_task! {
184/// task_type = "factory",
185/// sheet_name = "工厂数据",
186/// headers = FACTORY_HEADERS,
187/// rows = factory_export_rows, // async fn(ExportTaskContext) -> Result<Vec<Vec<String>>, E>
188/// }
189/// ```
190///
191/// # 形态二:文件导出(业务自带流式生成,如带图 xlsx)
192/// ```ignore
193/// fast_excel::export_task! {
194/// task_type = "product",
195/// mime = fast_excel::XLSX_MIME,
196/// file = product_export_file, // async fn(ExportTaskContext) -> Result<(i64, String), E>
197/// }
198/// ```
199///
200/// `rows` / `file` 也接受非捕获闭包(如 `|ctx| rows_for(kind, ctx)`),
201/// 方便一个模块用同一份逻辑注册多张表。
202#[macro_export]
203macro_rules! export_task {
204 (
205 task_type = $task:expr,
206 sheet_name = $sheet:expr,
207 headers = $headers:expr,
208 rows = $rows:expr
209 $(,)?
210 ) => {
211 const _: () = {
212 fn __excel_export_task(
213 ctx: $crate::ExportTaskContext,
214 ) -> $crate::ExportTaskFuture {
215 ::std::boxed::Box::pin($crate::run_rows_task(
216 ctx,
217 $task,
218 $sheet,
219 $headers,
220 $rows,
221 ))
222 }
223
224 $crate::inventory::submit! {
225 $crate::ExportTaskEntry {
226 task_type: $task,
227 kind: $crate::ExportTaskKind::Rows {
228 sheet_name: $sheet,
229 headers: $headers,
230 },
231 run: __excel_export_task,
232 }
233 }
234 };
235 };
236 (
237 task_type = $task:expr,
238 mime = $mime:expr,
239 file = $file:expr
240 $(,)?
241 ) => {
242 const _: () = {
243 fn __excel_export_task(
244 ctx: $crate::ExportTaskContext,
245 ) -> $crate::ExportTaskFuture {
246 ::std::boxed::Box::pin($crate::run_file_task(ctx, $mime, $file))
247 }
248
249 $crate::inventory::submit! {
250 $crate::ExportTaskEntry {
251 task_type: $task,
252 kind: $crate::ExportTaskKind::File { mime: $mime },
253 run: __excel_export_task,
254 }
255 }
256 };
257 };
258}