- A+
开源项目地址：https://gitee.com/easyxaf/excel-importer
前言
在XAF中有Excel导出，但没有Excel导入，一开始不理解，难道Excel导入很难实现吗，当我自己去实现Excel导入功能时，才发现难的不是技术，而是要有足够的灵活性，在不同的项目中或不同的业务场景中，都会有不同的需求，可能需要很多客制化，那能不能实现通用的Excel导入功能呢，我感觉满足所有需求是不可能的，但满足大多数需求还是有可能的。
思路
Excel导入本质是数据的映射，就是将Excel的行映射到XAF的BO对象中，这中间要涉及到数据类型的转换，如数值、日期、布尔、枚举、引用等类型，同时还要有数据的校验，由于Excel输入的灵活性及随意性，可以提高输入的方便性，但输入的准确性会大打折扣，所以数据的校验很重要。
结合XAF的特点，再加上Excel的灵活性，本Excel导入模块，优先考虑了采用XAF的Model进行Excel导入模板的创建，由于Model可以在设计时及运行时创建，这样可以解决Excel导入模板的灵活性，再通过XAF的条件表达式（Criteria）来实现数据的验证及数据的转换，基本可以解决大部分Excel导入的需求。
使用
首先看一下项目结构：
项目中带有Sample的是示例项目，主要项目为三个，EasyXaf.ExcelImporters为主项目，EasyXaf.Blazor.ExcelImporters为Blazor适配项目，EasyXaf.Win.ExcelImporters为WinForm适配项目，根据项目类型选择不同的项目。
本模块支持XPO及EFCore，由于Blazor项目需要一个存储临时文件的实体，而XPO与EFCore的实体类是不一样的，模块中并没包含这个实体（ExcelImporterTempFile），而是将其放到了示例模块项目中，如下图
在项目引用模块时，需要将文件ExcelImporterTempFile.cs拷贝到自己的项目中，对于EFCore项目，还要将ExcelImporterTempFile类，添加到DbContext中，如下图
完成以上操作后，就可以正常使用了。
示例
下面通过一个简单的示例来讲解Excel导入模块的功能
简易Excel模板制作
导出的Excel模板
编辑后的Excel模板
导入Excel数据
上面是简单的演示，Excel导入的过程需要4个步骤
- 模板制作
- 导出模板
- 编辑数据
- 导入Excel
模板的有效性验证
模板的制作是整个Excel导入模块的核心功能，为了提高用户在Excel输入的体验，同时为了避免输入错误数据，在模板中加入了有效性验证，如必填验证，数值及日期的范围验证，布尔值及枚举的下拉选择，同时还支持引用类型的下拉选择等
Excel录入数据
设置
了解上面的简单介绍后，下面讲解一些具体的设置
Excel模板中的下拉选择
在User中有一个IsActive属性，它的类型为布尔型，在本模块中布尔型默认会使用下拉选择，如果IsActive属性定义了CaptionForFalse及CaptionForTrue，则采用定义的文本，否则会采用'否'与'是'，但同时我们也可以设置PredefinedValues属性，如非活动与活动
PredefinedValues不仅可以用在布尔型中，也可以用在其它所有类型中（在数值及日期中也可以使用），同时它的优先级最高，定义了PredefinedValues后，则会忽略其自身的下拉选择，如果用在枚举中，要保证与枚举顺序保持一致
Excel模板中的效果
Excel模板的标头格式
默认情况下，在Excel模板中必填列的标头文本会加粗，如感觉不明显或想着重强调，可以修改相应的样式，NumberFormat对应着单元格的数值格式，可以通过它设置格式中数值或日期的显示格式。
Excel模板中的效果
Excel模板的标头文本
如果我们没有设置列的Caption属性，它将采用BO中定义的Caption，如果BO的Caption也为空，则采用BO类型的Name属性。同时可以用它来适配外来的Excel工作表，这样就可以不用修改Excel工作表原有标头文本，通过与其它参数配合，可以实现外来Excel工作表直接导入。
Excel模板中的效果
Excel模板中的列隐藏
在Excel模板中我们一般不需要对列进行隐藏，但有时我们需要通过导入来更新时，有时需要Oid等字段，如果我们不想显示出来，可以对其进行隐藏，只是进行了隐藏，用户可以轻松的显示出来，无法通过它隐藏数据
Excel模板中的效果
Excel模板中引用类型的下拉选择
本模块中引用类型默认不下拉选择，这主要基于安全考虑，由于引用类型下拉选择数据源中的数据并不是面向所有用户的，所以不能把不相关的都显示出来，这里需要单独的定义，可以通过PredefinedValues或DataSoruceCriteria，而DataSoruceCriteria可以通过表达式来限制数据源的显示。
Excel模板中的效果
忽略验证错误
一般验证错误是不需要忽略的，但有时我们提供了下拉选择，也允许用户输入下拉列表之外的内容时，就需要忽略验证错误，这样Excel不会阻止用户的输入
必须包含的Excel工作表列
有时我们要保证数据的完整性，要求用户输入比较完整的信息，在Model中定义的列，如果是必填的，那么在导入时首先会检查Excel工作表对应的列是否存在，如果不存在则无法导入，而对于不是必填的列，由于Excel的灵活性，用户可以很轻松的删除，我们可以将MustIncludeColumn设为True，这样缺少当前列时将无法成功导入。
导入时的默认值表达式
默认值一般用在当用户没有输入值时采用的值，格式为Criteria表达式。同时默认值还有一种使用场景，与VisibleInTemplate结合使用，当VisibleInTemplate为False，当前列不会显示在Excel模板中，可以通过设置默认值，用于它的初始值，例如：当我们希望用户导入的数据只在他自己所在的部门，但我们又不想用户自己选择部门，就可以通过这种方式。
列不显示在模板中
这里的不显示就是不在Excel模板中创建列，Excel模板不会包含它，与ColumnVisible是不一样的，ColumnVisible会将列包含在Excel模板中，而VisibleInTemplate一般主要用于不想要用户自己输入，可以结合DefaultValue一起使用
不更新模板中的列
模板中的列默认都是更新的，但有时我们是不需要更新的，比如在盘点时，我们只更新数量，但其它的列则是展示列没有必要更新，再比如，当用户表中部分用户手机号错误或不全时，需要比对确认，那么在导入时，我们希望只更新手机号
列的值表达式
一般主要用在引用类型的查找，通过设置Criteria来查找引用类型，同时也可以通过它来实现数据的转换，如下面在导入时在用户名的前面加上USER。ValueCriteria扩展性很强，可以使用XAF中的表达式函数，也可以使用自定义表达式函数
Excel模板中的效果
导入后的效果
导出视图数据
导出Excel模板时包含视图数据，这里的视图数据是视图查询出来的可显现数据，主要用在数据更新，可以对导出的数据进行修改，然后再次导入
主键的导入
主键主要用于更新，主键不一定是BO的真实主键，也可以是其它的唯一字段，如果不是BO的主键，需要设置KeyCriteria
导入数据方式
导入数据方式是导入数据时创建BO对象的方式，有4种导入方式
- 同步（Synchronize），它不仅创建不存在的数据，同时还会更新已存在的数据（默认行为）
- 仅创建（OnlyCreation），它只创建不存在的数据，已存在的数据不会更新
- 仅更新（OnlyUpdate），不存在的数据不会创建，更新已存在的数据
- 全创建（AllCreation），不管是否存在都会创建
验证失败展示
由于Excel的灵活性，无法避免错误的产生，如果导入时对数据验证不通过时，则将其显示在相应的单元格中，如果验证错误没有对应的单元格，则将其错误信息放在对应行的第一个单元格中。错误单元的背景可以通过ErrorBackgroundColor来设置，为空时将采用默认背景颜色。
自定义数据验证
数据验证是导入数据的保障，本模块中会依次采用下面的方式进行数据验证
- 数据类型的验证
- 模板中定义的最大值，最小值
- BO中定义的规则
- 模板中自定义的规则
最后
Excel导入模块现已实现了基础功能，今后还会根据业务的需求扩充新功能
