fast-excel 1.0.0

通用 Excel 导入导出工具:流式读写(百万级)、动态表头适配、多 sheet、单元格图片、批量落库(纯 Rust,对标 EasyExcel)
Documentation
//! 写侧:流式导出(多 sheet / 单元格图片 / 模板生成)

pub mod csv;
pub mod dynamic;
pub mod template;
pub mod writer;

pub use csv::write_csv;
pub use dynamic::{
    DynamicExportRunner, DynamicSheet, align_row, named_xlsx_bytes, positional_xlsx_bytes,
    write_named_xlsx, write_positional_xlsx,
};
pub use template::{DefaultExpr, ReferenceSheet, SampleExpr, TemplateSpec, build_template};
pub use writer::{ExcelWriter, SheetWriter};

use std::sync::Arc;

use crate::column::ColumnDef;
use crate::expr::{CellExpr, RowValues};
use crate::value::CellValue;

/// 写出选项
#[derive(Debug, Clone)]
pub struct WriteOptions {
    /// 表头样式(加粗 + 底色 + 居中)
    pub header_style: bool,
    /// 冻结表头行
    pub freeze_header: bool,
    /// 自动筛选
    pub auto_filter: bool,
    /// 默认行高
    pub default_row_height: Option<f64>,
    /// 含图片的行高(图片嵌入后按行高缩放)
    pub image_row_height: f64,
    /// 日期默认格式
    pub date_format: String,
    /// 日期时间默认格式
    pub datetime_format: String,
    /// 常量内存模式(**百万行必须开启**;开启后只能按行号递增写入)
    pub constant_memory: bool,
    /// 是否写 Excel「置于单元格内」图片(`embed_image`)
    ///
    /// 默认写标准锚点图片(`insert_image`):常量内存模式下可用、且能被
    /// 本工具的读取端(drawing 锚点)与 Excel / WPS 正常识别。
    /// 注意:`embed_image` 在 `rust_xlsxwriter` 常量内存模式下会报错,
    /// 且生成的是 `xl/richData/*`(Excel 内嵌图片);请用 [`WriteOptions::cell_image`]
    /// 开启——它会自动关闭常量内存;直接改字段的话请配合 `constant_memory = false`。
    pub cell_image: bool,
}

impl Default for WriteOptions {
    fn default() -> Self {
        Self {
            header_style: true,
            freeze_header: true,
            auto_filter: true,
            default_row_height: None,
            image_row_height: 60.0,
            date_format: "yyyy-mm-dd".to_string(),
            datetime_format: "yyyy-mm-dd hh:mm:ss".to_string(),
            constant_memory: true,
            cell_image: false,
        }
    }
}

impl WriteOptions {
    pub fn new() -> Self {
        Self::default()
    }

    /// 小数据量 / 需要随机写(合并单元格、绝对定位图片)时关闭常量内存
    pub fn in_memory(mut self) -> Self {
        self.constant_memory = false;
        self
    }

    /// 写 Excel 内嵌单元格图片(`embed_image`)
    ///
    /// 内嵌图片在 `rust_xlsxwriter` 常量内存模式下支持不完整(会直接报错),
    /// 因此这里**自动关闭常量内存**(等价于 `in_memory()`),只需调用本方法即可。
    pub fn cell_image(mut self) -> Self {
        self.cell_image = true;
        self.constant_memory = false;
        self
    }

    pub fn without_header_style(mut self) -> Self {
        self.header_style = false;
        self
    }

    pub fn auto_filter(mut self, enable: bool) -> Self {
        self.auto_filter = enable;
        self
    }

    pub fn freeze_header(mut self, enable: bool) -> Self {
        self.freeze_header = enable;
        self
    }

    pub fn image_row_height(mut self, height: f64) -> Self {
        self.image_row_height = height;
        self
    }

    pub fn date_format(mut self, format: impl Into<String>) -> Self {
        self.date_format = format.into();
        self
    }

    pub fn datetime_format(mut self, format: impl Into<String>) -> Self {
        self.datetime_format = format.into();
        self
    }
}

/// 单个工作表的配置
#[derive(Clone)]
pub struct SheetOptions {
    pub name: String,
    /// 列定义(表头、别名、宽度、格式、图片列)
    pub columns: Vec<ColumnDef>,
    pub write: WriteOptions,
    /// 计算列:导出时按表达式追加到末尾
    pub computed: Vec<(ColumnDef, CellExpr)>,
    /// 列改写:按表头匹配,导出时用表达式替换该列的值
    pub transforms: Vec<(String, CellExpr)>,
}

impl std::fmt::Debug for SheetOptions {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SheetOptions")
            .field("name", &self.name)
            .field("columns", &self.columns)
            .field("write", &self.write)
            .field(
                "computed",
                &self.computed.iter().map(|(d, _)| &d.header).collect::<Vec<_>>(),
            )
            .field(
                "transforms",
                &self.transforms.iter().map(|(h, _)| h).collect::<Vec<_>>(),
            )
            .finish()
    }
}

impl SheetOptions {
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            columns: Vec::new(),
            write: WriteOptions::default(),
            computed: Vec::new(),
            transforms: Vec::new(),
        }
    }

    pub fn columns<I>(mut self, columns: I) -> Self
    where
        I: IntoIterator<Item = ColumnDef>,
    {
        self.columns = columns.into_iter().collect();
        self
    }

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

    /// 追加一个**计算列**(导出时按表达式算出,无需模型里有对应字段)
    ///
    /// ```ignore
    /// use fast_excel::{CellValue, ColumnDef, SheetOptions, funcs};
    /// let sheet = SheetOptions::new("明细")
    ///     .columns(ProductRow::columns())
    ///     .computed(ColumnDef::new("全名"), |row| {
    ///         CellValue::Text(funcs::concat(&[&row.text("姓"), &row.text("名")]))
    ///     });
    /// ```
    pub fn computed<F>(mut self, def: ColumnDef, expr: F) -> Self
    where
        F: for<'a> Fn(&RowValues<'a>) -> CellValue + Send + Sync + 'static,
    {
        self.computed.push((def, Arc::new(expr)));
        self
    }

    /// **改写已有列**的值(按表头匹配;表达式拿到的是本行其它列的原始值)
    pub fn transform<F>(mut self, header: impl Into<String>, expr: F) -> Self
    where
        F: for<'a> Fn(&RowValues<'a>) -> CellValue + Send + Sync + 'static,
    {
        self.transforms.push((header.into(), Arc::new(expr)));
        self
    }

    /// 实际写出的列 = 基础列 + 追加的计算列
    pub fn effective_columns(&self) -> Vec<ColumnDef> {
        let mut cols = self.columns.clone();
        cols.extend(self.computed.iter().map(|(def, _)| def.clone()));
        cols
    }

    /// 应用列表达式:先按表头改写,再追加计算列
    pub fn eval_row(&self, mut cells: Vec<CellValue>) -> Vec<CellValue> {
        let base = &self.columns;
        for (header, expr) in &self.transforms {
            let Some(index) = base.iter().position(|c| &c.header == header) else {
                continue;
            };
            let value = expr(&RowValues::new(&cells, base));
            if index < cells.len() {
                cells[index] = value;
            } else {
                while cells.len() < index {
                    cells.push(CellValue::Empty);
                }
                cells.push(value);
            }
        }
        if !self.computed.is_empty() {
            let all = self.effective_columns();
            for (_, expr) in &self.computed {
                let value = expr(&RowValues::new(&cells, &all));
                cells.push(value);
            }
        }
        cells
    }
}

impl Default for SheetOptions {
    fn default() -> Self {
        Self::new("Sheet1")
    }
}

/// 列默认宽度(按语义类型 + 表头长度估算)
pub(crate) fn default_column_width(col: &ColumnDef) -> f64 {
    let base: f64 = match col.kind {
        crate::column::ColumnKind::DateTime => 20.0,
        crate::column::ColumnKind::Date => 13.0,
        crate::column::ColumnKind::Image => 16.0,
        crate::column::ColumnKind::Text => 16.0,
        _ => 12.0,
    };
    let header_width = col.header.chars().count() as f64 + 3.0;
    base.max(header_width)
}