fast-excel 1.0.0

通用 Excel 导入导出工具:流式读写(百万级)、动态表头适配、多 sheet、单元格图片、批量落库(纯 Rust,对标 EasyExcel)
Documentation
//! 无实体(动态表头)导出:前端传入表头 + 数据,框架按**表头名**自动对齐数据列
//!
//! 与有实体的 [`crate::ExcelRow`] 链路互补:
//! - 有实体:字段 → 列,编译期确定;
//! - 无实体:表头与数据都由前端给,运行时对齐(本模块)。
//!
//! ```ignore
//! use fast_excel::{CellValue, DynamicRow, DynamicSheet, write_named_xlsx};
//!
//! let sheet = DynamicSheet::new("导出").headers(["品名", "数量", "备注"]);
//! let rows = vec![
//!     DynamicRow { entries: vec![("数量".into(), CellValue::Number(3.0)), ("品名".into(), CellValue::Text("甲".into()))] },
//! ];
//! write_named_xlsx("out.xlsx", &sheet, &rows)?;   // 按表头名对齐,缺列留空、多余忽略
//! ```

use std::future::Future;
use std::path::Path;
use std::time::Instant;

use tokio::sync::mpsc;

use crate::column::ColumnDef;
use crate::error::{ExcelError, Result};
use crate::export::{ExportStats, Page};
use crate::header::{normalize_header, simple_columns};
use crate::model::DynamicRow;
use crate::value::CellValue;
use crate::write::{ExcelWriter, SheetOptions, WriteOptions};

/// 把「(表头名, 值)」按给定表头顺序对齐成一行单元格
///
/// 缺列填空、多余列忽略;匹配顺序:精确 → 归一化(去空白 / 全角半角 / 必填标记)。
pub fn align_row(headers: &[String], values: &[(String, CellValue)]) -> Vec<CellValue> {
    headers
        .iter()
        .map(|h| {
            if let Some((_, v)) = values.iter().find(|(k, _)| k == h) {
                return v.clone();
            }
            let nh = normalize_header(h);
            values
                .iter()
                .find(|(k, _)| normalize_header(k) == nh)
                .map(|(_, v)| v.clone())
                .unwrap_or(CellValue::Empty)
        })
        .collect()
}

/// 动态表头配置:只要表头名,或前端给的完整列定义(类型 / 格式 / 宽度)
#[derive(Debug, Clone)]
pub struct DynamicSheet {
    pub sheet: SheetOptions,
}

impl DynamicSheet {
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            sheet: SheetOptions::new(name),
        }
    }

    /// 用表头名(默认按文本列导出)
    pub fn headers<I, S>(self, headers: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.columns(simple_columns(headers))
    }

    /// 用前端给的完整列定义(可带 `kind` / `format` / `width`)
    pub fn columns<I>(mut self, columns: I) -> Self
    where
        I: IntoIterator<Item = ColumnDef>,
    {
        self.sheet = self.sheet.columns(columns);
        self
    }

    pub fn write_options(mut self, write: WriteOptions) -> Self {
        self.sheet = self.sheet.write_options(write);
        self
    }

    /// 表头名(按列顺序)
    pub fn headers_vec(&self) -> Vec<String> {
        self.sheet.columns.iter().map(|c| c.header.clone()).collect()
    }
}

/// 动态表头 + 具名行 → 内存字节(HTTP 直接下载)
pub fn named_xlsx_bytes(sheet: &DynamicSheet, rows: &[DynamicRow]) -> Result<Vec<u8>> {
    let mut writer = ExcelWriter::new();
    {
        let mut ws = writer.add_sheet(&sheet.sheet)?;
        ws.write_headers()?;
        let headers = sheet.headers_vec();
        for row in rows {
            ws.write_row(&align_row(&headers, &row.entries))?;
        }
        ws.finish()?;
    }
    writer.save_to_buffer()
}

/// 动态表头 + 具名行 → 文件
pub fn write_named_xlsx<P: AsRef<Path>>(
    path: P,
    sheet: &DynamicSheet,
    rows: &[DynamicRow],
) -> Result<u64> {
    let mut writer = ExcelWriter::new();
    {
        let mut ws = writer.add_sheet(&sheet.sheet)?;
        ws.write_headers()?;
        let headers = sheet.headers_vec();
        for row in rows {
            ws.write_row(&align_row(&headers, &row.entries))?;
        }
        ws.finish()?;
    }
    writer.save(path)
}

/// 动态表头 + **按位置**对应的行 → 内存字节
pub fn positional_xlsx_bytes(sheet: &DynamicSheet, rows: &[Vec<CellValue>]) -> Result<Vec<u8>> {
    let mut writer = ExcelWriter::new();
    {
        let mut ws = writer.add_sheet(&sheet.sheet)?;
        ws.write_headers()?;
        for row in rows {
            ws.write_row(row)?;
        }
        ws.finish()?;
    }
    writer.save_to_buffer()
}

/// 动态表头 + **按位置**对应的行 → 文件
pub fn write_positional_xlsx<P: AsRef<Path>>(
    path: P,
    sheet: &DynamicSheet,
    rows: &[Vec<CellValue>],
) -> Result<u64> {
    let mut writer = ExcelWriter::new();
    {
        let mut ws = writer.add_sheet(&sheet.sheet)?;
        ws.write_headers()?;
        for row in rows {
            ws.write_row(row)?;
        }
        ws.finish()?;
    }
    writer.save(path)
}

/// 动态表头 + 游标分页的流式导出(百万行不进内存)
///
/// 每页返回 [`DynamicRow`](表头名 → 值),框架按表头顺序对齐后写出。
#[derive(Debug, Clone)]
pub struct DynamicExportRunner {
    sheet: DynamicSheet,
    queue_pages: usize,
}

impl DynamicExportRunner {
    pub fn new(sheet: DynamicSheet) -> Self {
        Self {
            sheet,
            queue_pages: 2,
        }
    }

    pub fn queue_pages(mut self, pages: usize) -> Self {
        self.queue_pages = pages.max(1);
        self
    }

    pub async fn export_named<P, F, Fut>(&self, path: P, mut fetch: F) -> Result<ExportStats>
    where
        P: AsRef<Path>,
        F: FnMut(Option<String>) -> Fut,
        Fut: Future<Output = Result<Page<DynamicRow>>> + Send,
    {
        let started = Instant::now();
        let out_path = path.as_ref().to_path_buf();
        let headers = self.sheet.headers_vec();
        let sheet = self.sheet.sheet.clone();
        let write_path = out_path.clone();
        let (tx, mut rx) = mpsc::channel::<Vec<Vec<CellValue>>>(self.queue_pages);

        let writer_task = tokio::task::spawn_blocking(move || -> Result<u64> {
            let mut writer = ExcelWriter::new();
            let mut ws = writer.add_sheet(&sheet)?;
            ws.write_headers()?;
            while let Some(rows) = rx.blocking_recv() {
                for cells in &rows {
                    ws.write_row(cells)?;
                }
            }
            ws.finish()?;
            drop(ws);
            writer.save(&write_path)
        });

        let mut cursor: Option<String> = None;
        let mut pages = 0u64;
        let mut rows_total = 0u64;
        let fetch_result: Result<()> = async {
            loop {
                let page = fetch(cursor.clone()).await?;
                pages += 1;
                let done = page.done;
                let next = page.cursor.clone();
                rows_total += page.rows.len() as u64;
                if !page.rows.is_empty() {
                    let aligned: Vec<Vec<CellValue>> = page
                        .rows
                        .iter()
                        .map(|r| align_row(&headers, &r.entries))
                        .collect();
                    tx.send(aligned)
                        .await
                        .map_err(|_| ExcelError::Other("导出写出任务已结束".to_string()))?;
                }
                if done {
                    break;
                }
                if next.is_none() {
                    log::warn!("动态导出分页既没有 done 也没有 cursor,提前结束");
                    break;
                }
                cursor = next;
            }
            Ok(())
        }
        .await;

        drop(tx);
        let file_size = writer_task
            .await
            .map_err(|e| ExcelError::Other(format!("导出写出线程异常:{e}")))??;
        if let Err(e) = fetch_result {
            // 拉取失败时不要留下半截文件
            let _ = std::fs::remove_file(&out_path);
            return Err(e);
        }

        Ok(ExportStats {
            rows: rows_total,
            pages,
            file_size,
            elapsed_ms: started.elapsed().as_millis() as u64,
            path: out_path.to_string_lossy().into_owned(),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_align_row() {
        let headers = vec!["品名".to_string(), "数量".to_string(), "备注".to_string()];
        // 乱序 + 缺列 + 多余列(全角/空格归一化命中)
        let values = vec![
            ("数量".to_string(), CellValue::Number(3.0)),
            (" 品 名 ".to_string(), CellValue::Text("甲".into())),
            ("其他".to_string(), CellValue::Text("忽略".into())),
        ];
        let row = align_row(&headers, &values);
        assert_eq!(row.len(), 3);
        assert_eq!(row[0].to_text(), "甲");
        assert_eq!(row[1].to_text(), "3");
        assert!(row[2].is_empty());
    }
}