Skip to main content

fast_excel/read/
mod.rs

1//! 读侧:流式 xlsx 读取(动态表头 / 多 sheet / 单元格图片)
2//!
3//! ```no_run
4//! use fast_excel::read::{ExcelReader, ReadOptions, SheetSelector};
5//! # fn main() -> Result<(), fast_excel::ExcelError> {
6//! let reader = ExcelReader::open("products.xlsx")?;
7//! println!("工作表:{:?}", reader.sheet_names());
8//! let options = ReadOptions::new().header_row(0).with_images();
9//! let mut stream = reader.stream(SheetSelector::First, &[], options)?;
10//! while let Some(row) = stream.next_row()? {
11//!     println!("第 {} 行:{}", row.row_index, row.text_of("品名"));
12//! }
13//! # Ok(()) }
14//! ```
15
16pub mod csv;
17pub mod images;
18pub mod merges;
19pub mod shared_strings;
20pub mod sheet_meta;
21pub mod source;
22pub mod stream;
23pub mod styles;
24pub mod workbook;
25
26use std::path::Path;
27use std::sync::Arc;
28
29use crate::column::ColumnDef;
30use crate::error::{ExcelError, Result};
31use crate::header::{HeaderAnalysis, HeaderMap, HeaderOptions};
32use crate::model::{DynamicRow, ExcelRow, RowData};
33use crate::value::CellValue;
34
35pub use crate::value::CellImage;
36pub use csv::CsvReader;
37pub use images::{
38    ExtractedImages, extract_all_images, extract_embedded_images, extract_images_of_sheet,
39    extract_wps_cellimages, parse_dispimg_id,
40};
41pub use merges::MergeRange;
42pub use sheet_meta::{CfRule, Comment, ConditionalFormat, DataValidation, Hyperlink};
43pub use shared_strings::SharedStrings;
44pub use source::{EntryReader, ZipSource};
45pub use stream::SheetStream;
46pub use styles::{CellStyle, Styles};
47pub use workbook::SheetInfo;
48
49/// 导入**计算列**:文件里没有该列时,也能从本行其它列算出值
50///
51/// 只要模型的字段表头与 `def.header` 一致,取值时会自动命中(无需文件里真有该列)。
52#[derive(Clone)]
53pub struct ComputedColumn {
54    /// 列定义(`header` 必须与模型声明的表头一致)
55    pub def: ColumnDef,
56    expr: Arc<dyn for<'a> Fn(&RowData<'a>) -> CellValue + Send + Sync>,
57}
58
59impl ComputedColumn {
60    pub fn new<F>(def: ColumnDef, expr: F) -> Self
61    where
62        F: for<'a> Fn(&RowData<'a>) -> CellValue + Send + Sync + 'static,
63    {
64        Self {
65            def,
66            expr: Arc::new(expr),
67        }
68    }
69
70    /// 用本行原始数据求值
71    pub fn eval<'a>(&self, row: &RowData<'a>) -> CellValue {
72        (self.expr)(row)
73    }
74
75    pub fn header(&self) -> &str {
76        &self.def.header
77    }
78}
79
80impl std::fmt::Debug for ComputedColumn {
81    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
82        f.debug_struct("ComputedColumn")
83            .field("def", &self.def)
84            .finish_non_exhaustive()
85    }
86}
87
88/// 导入行过滤:返回 `true` 表示保留该行(用于跳过表尾"合计 / 备注"等脚注行)
89#[derive(Clone)]
90pub struct RowFilter(Arc<dyn for<'a> Fn(&RowData<'a>) -> bool + Send + Sync>);
91
92impl RowFilter {
93    pub fn new<F>(f: F) -> Self
94    where
95        F: for<'a> Fn(&RowData<'a>) -> bool + Send + Sync + 'static,
96    {
97        Self(Arc::new(f))
98    }
99
100    /// 是否保留该行
101    pub fn keep<'a>(&self, row: &RowData<'a>) -> bool {
102        (self.0)(row)
103    }
104}
105
106impl std::fmt::Debug for RowFilter {
107    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
108        f.write_str("RowFilter")
109    }
110}
111
112/// 工作表选择器
113#[derive(Debug, Clone, PartialEq, Eq)]
114pub enum SheetSelector {
115    /// 第一个工作表
116    First,
117    /// 按下标(0 基)
118    Index(u32),
119    /// 按名称(精确)
120    Name(String),
121    /// 按名称集合(多 sheet 导入:逐个读,顺序与传入一致)
122    Names(Vec<String>),
123    /// 全部工作表(多 sheet 导入)
124    All,
125}
126
127impl SheetSelector {
128    pub fn name(name: impl Into<String>) -> Self {
129        SheetSelector::Name(name.into())
130    }
131
132    pub fn names<I, S>(names: I) -> Self
133    where
134        I: IntoIterator<Item = S>,
135        S: Into<String>,
136    {
137        SheetSelector::Names(names.into_iter().map(Into::into).collect())
138    }
139}
140
141/// 读取选项
142#[derive(Debug, Clone)]
143pub struct ReadOptions {
144    /// 表头定位与匹配策略
145    pub header: HeaderOptions,
146    /// 最多产出多少行(预览 / 抽样用)
147    pub max_rows: Option<u64>,
148    /// 跳过整行空白
149    pub skip_empty_rows: bool,
150    /// 是否读取单元格内嵌图片
151    pub read_images: bool,
152    /// 只读这些文件列(0 基)的图片;`None` = 按模型声明自动推导
153    pub image_columns: Option<Vec<u16>>,
154    /// 是否读取合并单元格信息(`<mergeCells>`)
155    ///
156    /// 开启后需要**额外扫描一遍工作表 XML**(`<mergeCells>` 在 `<data>` 之后,
157    /// 流式读取无法边读边拿),因此默认关闭以保证百万行吞吐;需要时用
158    /// [`ReadOptions::with_merges`] 打开。
159    pub read_merges: bool,
160    /// 是否把合并区域左上角的值回填到区域内每个单元格(依赖 `read_merges`)
161    pub fill_merged: bool,
162    /// 是否读取超链接(`<hyperlinks>`,需额外扫一遍工作表 XML)
163    pub read_hyperlinks: bool,
164    /// 是否读取批注(`comments*.xml`)
165    pub read_comments: bool,
166    /// 是否读取数据验证(下拉 / 数值区间)
167    pub read_validations: bool,
168    /// 是否读取条件格式
169    pub read_conditional_formats: bool,
170    /// 导入计算列(文件里没有该列也能按表达式算出来)
171    pub computed: Vec<ComputedColumn>,
172    /// 行过滤:返回 `false` 的行会被跳过(表尾汇总行 / 脚注行)
173    pub row_filter: Option<RowFilter>,
174    /// 文本是否 trim
175    pub trim_text: bool,
176}
177
178impl Default for ReadOptions {
179    fn default() -> Self {
180        Self {
181            header: HeaderOptions::default(),
182            max_rows: None,
183            skip_empty_rows: true,
184            read_images: false,
185            image_columns: None,
186            read_merges: false,
187            fill_merged: true,
188            read_hyperlinks: false,
189            read_comments: false,
190            read_validations: false,
191            read_conditional_formats: false,
192            computed: Vec::new(),
193            row_filter: None,
194            trim_text: true,
195        }
196    }
197}
198
199impl ReadOptions {
200    pub fn new() -> Self {
201        Self::default()
202    }
203
204    pub fn header_options(mut self, header: HeaderOptions) -> Self {
205        self.header = header;
206        self
207    }
208
209    pub fn header_row(mut self, row_index: u32) -> Self {
210        self.header.row_index = row_index;
211        self
212    }
213
214    pub fn header_span(mut self, span: u32) -> Self {
215        self.header.row_span = span.max(1);
216        self
217    }
218
219    pub fn max_rows(mut self, rows: u64) -> Self {
220        self.max_rows = Some(rows);
221        self
222    }
223
224    /// 打开图片读取(模型里声明了图片列时,只读这些列)
225    pub fn with_images(mut self) -> Self {
226        self.read_images = true;
227        self
228    }
229
230    /// 显式指定要读图的文件列
231    pub fn image_columns(mut self, cols: Vec<u16>) -> Self {
232        self.image_columns = Some(cols);
233        self
234    }
235
236    /// 打开合并单元格读取:解析 `<mergeCells>` 并把左上角值回填到整个区域
237    ///
238    /// 代价是多扫一遍工作表 XML(见字段说明);不需要合并信息时保持默认即可。
239    pub fn with_merges(mut self) -> Self {
240        self.read_merges = true;
241        self.fill_merged = true;
242        self
243    }
244
245    /// 关闭合并单元格读取
246    pub fn without_merges(mut self) -> Self {
247        self.read_merges = false;
248        self
249    }
250
251    /// 只暴露合并区域、不做值回填(会同时打开合并读取)
252    pub fn merges_exposed_only(mut self) -> Self {
253        self.read_merges = true;
254        self.fill_merged = false;
255        self
256    }
257
258    /// 打开超链接读取(`SheetStream::hyperlinks` / `ExcelReader::hyperlinks`)
259    pub fn with_hyperlinks(mut self) -> Self {
260        self.read_hyperlinks = true;
261        self
262    }
263
264    /// 打开批注读取(`SheetStream::comments` / `ExcelReader::comments`)
265    pub fn with_comments(mut self) -> Self {
266        self.read_comments = true;
267        self
268    }
269
270    /// 打开数据验证读取(下拉 / 数值区间)
271    pub fn with_validations(mut self) -> Self {
272        self.read_validations = true;
273        self
274    }
275
276    /// 打开条件格式读取
277    pub fn with_conditional_formats(mut self) -> Self {
278        self.read_conditional_formats = true;
279        self
280    }
281
282    /// 追加一个**导入计算列**:文件里没有该列时,也能从本行其它列算出值
283    ///
284    /// 模型只需按同一个表头声明字段即可取到:
285    ///
286    /// ```ignore
287    /// use fast_excel::{CellValue, ColumnDef, ReadOptions};
288    /// let options = ReadOptions::new().computed(ColumnDef::new("全名"), |row| {
289    ///     let full = format!("{}{}", row.text_of("姓"), row.text_of("名"));
290    ///     CellValue::Text(full)
291    /// });
292    /// ```
293    pub fn computed<F>(mut self, def: ColumnDef, expr: F) -> Self
294    where
295        F: for<'a> Fn(&RowData<'a>) -> CellValue + Send + Sync + 'static,
296    {
297        self.computed.push(ComputedColumn::new(def, expr));
298        self
299    }
300
301    /// 设置**行过滤**:返回 `false` 的行直接跳过(表尾"合计 / 备注"等脚注行)
302    ///
303    /// ```ignore
304    /// use fast_excel::ReadOptions;
305    /// let options = ReadOptions::new().row_filter(|row| {
306    ///     // 丢弃第一列为「合计」的汇总行
307    ///     row.text_of("品名") != "合计"
308    /// });
309    /// ```
310    pub fn row_filter<F>(mut self, f: F) -> Self
311    where
312        F: for<'a> Fn(&RowData<'a>) -> bool + Send + Sync + 'static,
313    {
314        self.row_filter = Some(RowFilter::new(f));
315        self
316    }
317
318    pub fn skip_empty_rows(mut self, skip: bool) -> Self {
319        self.skip_empty_rows = skip;
320        self
321    }
322
323    pub fn trim_text(mut self, trim: bool) -> Self {
324        self.trim_text = trim;
325        self
326    }
327}
328
329/// xlsx 读取器(可同时解析多个工作表;每次 `stream` 都是独立的流式读取)
330pub struct ExcelReader {
331    source: ZipSource,
332    sheets: Vec<SheetInfo>,
333    date_1904: bool,
334    shared: Arc<SharedStrings>,
335    styles: Arc<Styles>,
336}
337
338impl ExcelReader {
339    /// 打开磁盘文件(推荐:不把整个文件读进内存)
340    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
341        Self::from_source(ZipSource::open(path)?)
342    }
343
344    /// 以内存字节打开(HTTP 上传的 multipart 场景)
345    pub fn from_bytes(bytes: Vec<u8>) -> Result<Self> {
346        Self::from_source(ZipSource::from_bytes(bytes))
347    }
348
349    /// 复用已有数据源
350    pub fn from_source(source: ZipSource) -> Result<Self> {
351        let (sheets, date_1904) = workbook::load_sheets(&source)?;
352        // 共享字符串与样式表体积小、且需要随机访问,策略是整体加载一次
353        let shared = match source.entry_reader("xl/sharedStrings.xml") {
354            Ok(reader) => SharedStrings::parse(std::io::BufReader::new(reader))?,
355            Err(_) => SharedStrings::empty(),
356        };
357        let styles = match source.entry_reader("xl/styles.xml") {
358            Ok(reader) => Styles::parse(std::io::BufReader::new(reader))?,
359            Err(_) => Styles::empty(),
360        };
361        Ok(Self {
362            source,
363            sheets,
364            date_1904,
365            shared: Arc::new(shared),
366            styles: Arc::new(styles),
367        })
368    }
369
370    pub fn source(&self) -> &ZipSource {
371        &self.source
372    }
373
374    pub fn sheets(&self) -> &[SheetInfo] {
375        &self.sheets
376    }
377
378    pub fn sheet_names(&self) -> Vec<String> {
379        self.sheets.iter().map(|s| s.name.clone()).collect()
380    }
381
382    pub fn date_1904(&self) -> bool {
383        self.date_1904
384    }
385
386    pub fn shared_strings(&self) -> &SharedStrings {
387        &self.shared
388    }
389
390    /// 单元格样式表(字体颜色 / 底色 / 加粗 / 斜体)
391    pub fn styles(&self) -> &Styles {
392        &self.styles
393    }
394
395    /// 解析选择器 → 工作表列表
396    pub fn select(&self, selector: &SheetSelector) -> Result<Vec<&SheetInfo>> {
397        let found: Vec<&SheetInfo> = match selector {
398            SheetSelector::First => self.sheets.first().into_iter().collect(),
399            SheetSelector::Index(i) => self.sheets.iter().filter(|s| s.index == *i).collect(),
400            SheetSelector::Name(name) => self.sheets.iter().filter(|s| &s.name == name).collect(),
401            SheetSelector::Names(names) => names
402                .iter()
403                .map(|n| {
404                    self.sheets
405                        .iter()
406                        .find(|s| &s.name == n)
407                        .ok_or_else(|| ExcelError::SheetNotFound(n.clone()))
408                })
409                .collect::<Result<Vec<_>>>()?,
410            SheetSelector::All => self.sheets.iter().collect(),
411        };
412        if found.is_empty() {
413            return Err(ExcelError::SheetNotFound(match selector {
414                SheetSelector::First => "第一个工作表".to_string(),
415                SheetSelector::Index(i) => format!("下标 {i}"),
416                SheetSelector::Name(n) => n.clone(),
417                SheetSelector::Names(n) => n.join("、"),
418                SheetSelector::All => "任意工作表".to_string(),
419            }));
420        }
421        Ok(found)
422    }
423
424    /// 打开一个工作表的行流(单个 sheet)
425    pub fn stream(
426        &self,
427        selector: SheetSelector,
428        defs: &[ColumnDef],
429        options: ReadOptions,
430    ) -> Result<SheetStream> {
431        let sheets = self.select(&selector)?;
432        let sheet = sheets[0];
433        self.stream_sheet(sheet, defs, options)
434    }
435
436    /// 打开指定工作表的行流
437    pub fn stream_sheet(
438        &self,
439        sheet: &SheetInfo,
440        defs: &[ColumnDef],
441        options: ReadOptions,
442    ) -> Result<SheetStream> {
443        SheetStream::new(
444            self.source.clone(),
445            &sheet.path,
446            &sheet.name,
447            self.date_1904,
448            self.shared.clone(),
449            self.styles.clone(),
450            defs,
451            options,
452        )
453    }
454
455    /// 只做表头自适应分析(不消费数据,供"导入预检"接口使用)
456    pub fn analyze_header(
457        &self,
458        selector: &SheetSelector,
459        defs: &[ColumnDef],
460        options: ReadOptions,
461    ) -> Result<HeaderAnalysis> {
462        let sheets = self.select(selector)?;
463        let mut stream = self.stream_sheet(sheets[0], defs, options)?;
464        // 触发一次解析即可确保表头已构建(空文件也会在 EOF 处构建)
465        let _ = stream.next_row()?;
466        Ok(stream
467            .header_analysis()
468            .unwrap_or_else(|| HeaderMap::dynamic(Vec::new()).analysis()))
469    }
470
471    /// 读取所有工作表的表头分析(多 sheet 预检)
472    pub fn analyze_all_headers(
473        &self,
474        defs: &[ColumnDef],
475        options: ReadOptions,
476    ) -> Result<Vec<(String, HeaderAnalysis)>> {
477        let mut out = Vec::with_capacity(self.sheets.len());
478        for sheet in &self.sheets {
479            let mut stream = self.stream_sheet(sheet, defs, options.clone())?;
480            let _ = stream.next_row()?;
481            let analysis = stream
482                .header_analysis()
483                .unwrap_or_else(|| HeaderMap::dynamic(Vec::new()).analysis());
484            out.push((sheet.name.clone(), analysis));
485        }
486        Ok(out)
487    }
488
489    /// 读取指定(可多个)工作表的合并区域(只查询,不做值回填)
490    ///
491    /// 需要值回填时改用 [`ReadOptions::with_merges`] 走 [`ExcelReader::stream`]。
492    pub fn merge_ranges(&self, selector: &SheetSelector) -> Result<Vec<MergeRange>> {
493        let mut out = Vec::new();
494        for sheet in self.select(selector)? {
495            let wants = sheet_meta::MetaWants {
496                merges: true,
497                ..Default::default()
498            };
499            out.extend(sheet_meta::load_sheet_meta(&self.source, &sheet.path, wants)?.merges);
500        }
501        Ok(out)
502    }
503
504    /// 读取指定(可多个)工作表的超链接
505    pub fn hyperlinks(&self, selector: &SheetSelector) -> Result<Vec<Hyperlink>> {
506        let mut out = Vec::new();
507        for sheet in self.select(selector)? {
508            let wants = sheet_meta::MetaWants {
509                hyperlinks: true,
510                ..Default::default()
511            };
512            out.extend(sheet_meta::load_sheet_meta(&self.source, &sheet.path, wants)?.hyperlinks);
513        }
514        Ok(out)
515    }
516
517    /// 读取指定(可多个)工作表的数据验证(下拉 / 数值区间)
518    pub fn validations(&self, selector: &SheetSelector) -> Result<Vec<sheet_meta::DataValidation>> {
519        let mut out = Vec::new();
520        for sheet in self.select(selector)? {
521            let wants = sheet_meta::MetaWants {
522                validations: true,
523                ..Default::default()
524            };
525            out.extend(sheet_meta::load_sheet_meta(&self.source, &sheet.path, wants)?.validations);
526        }
527        Ok(out)
528    }
529
530    /// 读取指定(可多个)工作表的条件格式
531    pub fn conditional_formats(
532        &self,
533        selector: &SheetSelector,
534    ) -> Result<Vec<sheet_meta::ConditionalFormat>> {
535        let mut out = Vec::new();
536        for sheet in self.select(selector)? {
537            let wants = sheet_meta::MetaWants {
538                conditional_formats: true,
539                ..Default::default()
540            };
541            out.extend(
542                sheet_meta::load_sheet_meta(&self.source, &sheet.path, wants)?
543                    .conditional_formats,
544            );
545        }
546        Ok(out)
547    }
548
549    /// 动态读取整表(**无实体**):返回 `(表头, 每行 表头→值)`
550    ///
551    /// 等价于 `stream(selector, &[], options)` + [`DynamicRow::from_row`],
552    /// 用于「没有实体、前端直接拿表头与内容」的场景。
553    pub fn read_dynamic(
554        &self,
555        selector: &SheetSelector,
556        options: ReadOptions,
557    ) -> Result<(Vec<String>, Vec<DynamicRow>)> {
558        let sheets = self.select(selector)?;
559        let mut stream = self.stream_sheet(sheets[0], &[], options)?;
560        let mut rows = Vec::new();
561        while let Some(row) = stream.next_row()? {
562            let dynamic = DynamicRow::from_row(&row)
563                .map_err(|e| ExcelError::Other(format!("动态行解析失败:{}", e.len())))?;
564            rows.push(dynamic);
565        }
566        let headers = stream
567            .header()
568            .map(|h| h.file_headers.clone())
569            .unwrap_or_default();
570        Ok((headers, rows))
571    }
572
573    /// 读取指定(可多个)工作表的批注(经典批注 `comments*.xml` + 线程批注 `threadedComments`)
574    ///
575    /// 线程批注只收根批注(带 `ref` 的条目),回复暂不展开。
576    pub fn comments(&self, selector: &SheetSelector) -> Result<Vec<Comment>> {
577        let mut out = Vec::new();
578        for sheet in self.select(selector)? {
579            out.extend(sheet_meta::load_comments(&self.source, &sheet.path)?);
580        }
581        Ok(out)
582    }
583}