Skip to main content

fast_excel/write/
dynamic.rs

1//! 无实体(动态表头)导出:前端传入表头 + 数据,框架按**表头名**自动对齐数据列
2//!
3//! 与有实体的 [`crate::ExcelRow`] 链路互补:
4//! - 有实体:字段 → 列,编译期确定;
5//! - 无实体:表头与数据都由前端给,运行时对齐(本模块)。
6//!
7//! ```ignore
8//! use fast_excel::{CellValue, DynamicRow, DynamicSheet, write_named_xlsx};
9//!
10//! let sheet = DynamicSheet::new("导出").headers(["品名", "数量", "备注"]);
11//! let rows = vec![
12//!     DynamicRow { entries: vec![("数量".into(), CellValue::Number(3.0)), ("品名".into(), CellValue::Text("甲".into()))] },
13//! ];
14//! write_named_xlsx("out.xlsx", &sheet, &rows)?;   // 按表头名对齐,缺列留空、多余忽略
15//! ```
16
17use std::future::Future;
18use std::path::Path;
19use std::time::Instant;
20
21use tokio::sync::mpsc;
22
23use crate::column::ColumnDef;
24use crate::error::{ExcelError, Result};
25use crate::export::{ExportStats, Page};
26use crate::header::{normalize_header, simple_columns};
27use crate::model::DynamicRow;
28use crate::value::CellValue;
29use crate::write::{ExcelWriter, SheetOptions, WriteOptions};
30
31/// 把「(表头名, 值)」按给定表头顺序对齐成一行单元格
32///
33/// 缺列填空、多余列忽略;匹配顺序:精确 → 归一化(去空白 / 全角半角 / 必填标记)。
34pub fn align_row(headers: &[String], values: &[(String, CellValue)]) -> Vec<CellValue> {
35    headers
36        .iter()
37        .map(|h| {
38            if let Some((_, v)) = values.iter().find(|(k, _)| k == h) {
39                return v.clone();
40            }
41            let nh = normalize_header(h);
42            values
43                .iter()
44                .find(|(k, _)| normalize_header(k) == nh)
45                .map(|(_, v)| v.clone())
46                .unwrap_or(CellValue::Empty)
47        })
48        .collect()
49}
50
51/// 动态表头配置:只要表头名,或前端给的完整列定义(类型 / 格式 / 宽度)
52#[derive(Debug, Clone)]
53pub struct DynamicSheet {
54    pub sheet: SheetOptions,
55}
56
57impl DynamicSheet {
58    pub fn new(name: impl Into<String>) -> Self {
59        Self {
60            sheet: SheetOptions::new(name),
61        }
62    }
63
64    /// 用表头名(默认按文本列导出)
65    pub fn headers<I, S>(self, headers: I) -> Self
66    where
67        I: IntoIterator<Item = S>,
68        S: Into<String>,
69    {
70        self.columns(simple_columns(headers))
71    }
72
73    /// 用前端给的完整列定义(可带 `kind` / `format` / `width`)
74    pub fn columns<I>(mut self, columns: I) -> Self
75    where
76        I: IntoIterator<Item = ColumnDef>,
77    {
78        self.sheet = self.sheet.columns(columns);
79        self
80    }
81
82    pub fn write_options(mut self, write: WriteOptions) -> Self {
83        self.sheet = self.sheet.write_options(write);
84        self
85    }
86
87    /// 表头名(按列顺序)
88    pub fn headers_vec(&self) -> Vec<String> {
89        self.sheet.columns.iter().map(|c| c.header.clone()).collect()
90    }
91}
92
93/// 动态表头 + 具名行 → 内存字节(HTTP 直接下载)
94pub fn named_xlsx_bytes(sheet: &DynamicSheet, rows: &[DynamicRow]) -> Result<Vec<u8>> {
95    let mut writer = ExcelWriter::new();
96    {
97        let mut ws = writer.add_sheet(&sheet.sheet)?;
98        ws.write_headers()?;
99        let headers = sheet.headers_vec();
100        for row in rows {
101            ws.write_row(&align_row(&headers, &row.entries))?;
102        }
103        ws.finish()?;
104    }
105    writer.save_to_buffer()
106}
107
108/// 动态表头 + 具名行 → 文件
109pub fn write_named_xlsx<P: AsRef<Path>>(
110    path: P,
111    sheet: &DynamicSheet,
112    rows: &[DynamicRow],
113) -> Result<u64> {
114    let mut writer = ExcelWriter::new();
115    {
116        let mut ws = writer.add_sheet(&sheet.sheet)?;
117        ws.write_headers()?;
118        let headers = sheet.headers_vec();
119        for row in rows {
120            ws.write_row(&align_row(&headers, &row.entries))?;
121        }
122        ws.finish()?;
123    }
124    writer.save(path)
125}
126
127/// 动态表头 + **按位置**对应的行 → 内存字节
128pub fn positional_xlsx_bytes(sheet: &DynamicSheet, rows: &[Vec<CellValue>]) -> Result<Vec<u8>> {
129    let mut writer = ExcelWriter::new();
130    {
131        let mut ws = writer.add_sheet(&sheet.sheet)?;
132        ws.write_headers()?;
133        for row in rows {
134            ws.write_row(row)?;
135        }
136        ws.finish()?;
137    }
138    writer.save_to_buffer()
139}
140
141/// 动态表头 + **按位置**对应的行 → 文件
142pub fn write_positional_xlsx<P: AsRef<Path>>(
143    path: P,
144    sheet: &DynamicSheet,
145    rows: &[Vec<CellValue>],
146) -> Result<u64> {
147    let mut writer = ExcelWriter::new();
148    {
149        let mut ws = writer.add_sheet(&sheet.sheet)?;
150        ws.write_headers()?;
151        for row in rows {
152            ws.write_row(row)?;
153        }
154        ws.finish()?;
155    }
156    writer.save(path)
157}
158
159/// 动态表头 + 游标分页的流式导出(百万行不进内存)
160///
161/// 每页返回 [`DynamicRow`](表头名 → 值),框架按表头顺序对齐后写出。
162#[derive(Debug, Clone)]
163pub struct DynamicExportRunner {
164    sheet: DynamicSheet,
165    queue_pages: usize,
166}
167
168impl DynamicExportRunner {
169    pub fn new(sheet: DynamicSheet) -> Self {
170        Self {
171            sheet,
172            queue_pages: 2,
173        }
174    }
175
176    pub fn queue_pages(mut self, pages: usize) -> Self {
177        self.queue_pages = pages.max(1);
178        self
179    }
180
181    pub async fn export_named<P, F, Fut>(&self, path: P, mut fetch: F) -> Result<ExportStats>
182    where
183        P: AsRef<Path>,
184        F: FnMut(Option<String>) -> Fut,
185        Fut: Future<Output = Result<Page<DynamicRow>>> + Send,
186    {
187        let started = Instant::now();
188        let out_path = path.as_ref().to_path_buf();
189        let headers = self.sheet.headers_vec();
190        let sheet = self.sheet.sheet.clone();
191        let write_path = out_path.clone();
192        let (tx, mut rx) = mpsc::channel::<Vec<Vec<CellValue>>>(self.queue_pages);
193
194        let writer_task = tokio::task::spawn_blocking(move || -> Result<u64> {
195            let mut writer = ExcelWriter::new();
196            let mut ws = writer.add_sheet(&sheet)?;
197            ws.write_headers()?;
198            while let Some(rows) = rx.blocking_recv() {
199                for cells in &rows {
200                    ws.write_row(cells)?;
201                }
202            }
203            ws.finish()?;
204            drop(ws);
205            writer.save(&write_path)
206        });
207
208        let mut cursor: Option<String> = None;
209        let mut pages = 0u64;
210        let mut rows_total = 0u64;
211        let fetch_result: Result<()> = async {
212            loop {
213                let page = fetch(cursor.clone()).await?;
214                pages += 1;
215                let done = page.done;
216                let next = page.cursor.clone();
217                rows_total += page.rows.len() as u64;
218                if !page.rows.is_empty() {
219                    let aligned: Vec<Vec<CellValue>> = page
220                        .rows
221                        .iter()
222                        .map(|r| align_row(&headers, &r.entries))
223                        .collect();
224                    tx.send(aligned)
225                        .await
226                        .map_err(|_| ExcelError::Other("导出写出任务已结束".to_string()))?;
227                }
228                if done {
229                    break;
230                }
231                if next.is_none() {
232                    log::warn!("动态导出分页既没有 done 也没有 cursor,提前结束");
233                    break;
234                }
235                cursor = next;
236            }
237            Ok(())
238        }
239        .await;
240
241        drop(tx);
242        let file_size = writer_task
243            .await
244            .map_err(|e| ExcelError::Other(format!("导出写出线程异常:{e}")))??;
245        if let Err(e) = fetch_result {
246            // 拉取失败时不要留下半截文件
247            let _ = std::fs::remove_file(&out_path);
248            return Err(e);
249        }
250
251        Ok(ExportStats {
252            rows: rows_total,
253            pages,
254            file_size,
255            elapsed_ms: started.elapsed().as_millis() as u64,
256            path: out_path.to_string_lossy().into_owned(),
257        })
258    }
259}
260
261#[cfg(test)]
262mod tests {
263    use super::*;
264
265    #[test]
266    fn test_align_row() {
267        let headers = vec!["品名".to_string(), "数量".to_string(), "备注".to_string()];
268        // 乱序 + 缺列 + 多余列(全角/空格归一化命中)
269        let values = vec![
270            ("数量".to_string(), CellValue::Number(3.0)),
271            (" 品 名 ".to_string(), CellValue::Text("甲".into())),
272            ("其他".to_string(), CellValue::Text("忽略".into())),
273        ];
274        let row = align_row(&headers, &values);
275        assert_eq!(row.len(), 3);
276        assert_eq!(row[0].to_text(), "甲");
277        assert_eq!(row[1].to_text(), "3");
278        assert!(row[2].is_empty());
279    }
280}