Skip to main content

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}