Skip to main content

fast_excel/
column.rs

1//! 列定义:一个业务字段 = 一列(对标 EasyExcel 的 `@ExcelProperty`)
2
3/// 列的语义类型:读时决定解析方式,写时决定单元格格式
4#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
5pub enum ColumnKind {
6    /// 自动(按单元格实际类型解析)
7    #[default]
8    Any,
9    /// 文本(导出时按文本格式写,长数字/手机号不丢前导 0、不变科学计数)
10    Text,
11    Integer,
12    Number,
13    /// 金额 / 高精度小数(对应 `rust_decimal::Decimal`)
14    Decimal,
15    Bool,
16    Date,
17    DateTime,
18    /// 图片列:导入按行读内嵌图片,导出按行嵌入图片
19    Image,
20}
21
22impl ColumnKind {
23    pub fn is_image(self) -> bool {
24        matches!(self, ColumnKind::Image)
25    }
26
27    pub fn is_numeric(self) -> bool {
28        matches!(
29            self,
30            ColumnKind::Integer | ColumnKind::Number | ColumnKind::Decimal
31        )
32    }
33
34    pub fn is_temporal(self) -> bool {
35        matches!(self, ColumnKind::Date | ColumnKind::DateTime)
36    }
37
38    pub fn as_str(self) -> &'static str {
39        match self {
40            ColumnKind::Any => "any",
41            ColumnKind::Text => "text",
42            ColumnKind::Integer => "integer",
43            ColumnKind::Number => "number",
44            ColumnKind::Decimal => "decimal",
45            ColumnKind::Bool => "bool",
46            ColumnKind::Date => "date",
47            ColumnKind::DateTime => "datetime",
48            ColumnKind::Image => "image",
49        }
50    }
51}
52
53/// 列定义
54#[derive(Debug, Clone)]
55pub struct ColumnDef {
56    /// 标准表头(模板/导出使用)
57    pub header: String,
58    /// 别名(动态表头适配:历史模板改过列名的场景)
59    pub aliases: Vec<String>,
60    /// 必填
61    pub required: bool,
62    /// 语义类型
63    pub kind: ColumnKind,
64    /// 导出列宽
65    pub width: Option<f64>,
66    /// 导出数值格式(如 `#,##0.00`、`yyyy-mm-dd`)
67    pub format: Option<String>,
68    /// 导出是否按文本格式写(`@`)
69    pub text_format: bool,
70    /// 是否图片列
71    pub image: bool,
72    /// 导入时忽略(仅参与模板/导出展示)
73    pub ignore: bool,
74    /// 空值默认值(模板示例行与导入兜底)
75    pub default: Option<String>,
76    /// 模板备注(写入说明 sheet)
77    pub note: Option<String>,
78    /// 模板下拉选项(数据验证)
79    pub dropdown: Vec<String>,
80}
81
82impl ColumnDef {
83    pub fn new(header: impl Into<String>) -> Self {
84        Self {
85            header: header.into(),
86            aliases: Vec::new(),
87            required: false,
88            kind: ColumnKind::Any,
89            width: None,
90            format: None,
91            text_format: false,
92            image: false,
93            ignore: false,
94            default: None,
95            note: None,
96            dropdown: Vec::new(),
97        }
98    }
99
100    pub fn alias(mut self, alias: impl Into<String>) -> Self {
101        let a = alias.into();
102        if !a.is_empty() && a != self.header {
103            self.aliases.push(a);
104        }
105        self
106    }
107
108    pub fn aliases<I, S>(mut self, list: I) -> Self
109    where
110        I: IntoIterator<Item = S>,
111        S: Into<String>,
112    {
113        for a in list {
114            self = self.alias(a);
115        }
116        self
117    }
118
119    pub fn required(mut self) -> Self {
120        self.required = true;
121        self
122    }
123
124    pub fn optional(mut self) -> Self {
125        self.required = false;
126        self
127    }
128
129    pub fn kind(mut self, kind: ColumnKind) -> Self {
130        self.kind = kind;
131        if kind.is_image() {
132            self.image = true;
133        }
134        self
135    }
136
137    pub fn width(mut self, width: f64) -> Self {
138        self.width = Some(width);
139        self
140    }
141
142    pub fn format(mut self, format: impl Into<String>) -> Self {
143        self.format = Some(format.into());
144        self
145    }
146
147    /// 文本格式(长数字、手机号、编码类字段)
148    pub fn as_text(mut self) -> Self {
149        self.text_format = true;
150        self
151    }
152
153    pub fn image(mut self) -> Self {
154        self.image = true;
155        self.kind = ColumnKind::Image;
156        self
157    }
158
159    pub fn ignore(mut self) -> Self {
160        self.ignore = true;
161        self
162    }
163
164    pub fn default_value(mut self, value: impl Into<String>) -> Self {
165        self.default = Some(value.into());
166        self
167    }
168
169    pub fn note(mut self, note: impl Into<String>) -> Self {
170        self.note = Some(note.into());
171        self
172    }
173
174    pub fn dropdown<I, S>(mut self, list: I) -> Self
175    where
176        I: IntoIterator<Item = S>,
177        S: Into<String>,
178    {
179        self.dropdown = list.into_iter().map(Into::into).collect();
180        self
181    }
182
183    /// 表头 + 别名(动态匹配用)
184    pub fn names(&self) -> impl Iterator<Item = &str> {
185        std::iter::once(self.header.as_str()).chain(self.aliases.iter().map(|s| s.as_str()))
186    }
187
188    /// 是否参与导入解析
189    pub fn is_importable(&self) -> bool {
190        !self.ignore
191    }
192
193    /// 该列是否需要在模板里标红(必填)
194    pub fn mark_required(&self) -> bool {
195        self.required
196    }
197}
198
199impl From<&str> for ColumnDef {
200    fn from(header: &str) -> Self {
201        ColumnDef::new(header)
202    }
203}
204
205impl From<String> for ColumnDef {
206    fn from(header: String) -> Self {
207        ColumnDef::new(header)
208    }
209}
210
211impl From<(&str, ColumnKind)> for ColumnDef {
212    fn from((header, kind): (&str, ColumnKind)) -> Self {
213        ColumnDef::new(header).kind(kind)
214    }
215}