XAF Excel Importer

开源项目地址: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导入模块现已实现了基础功能,今后还会根据业务的需求扩充新功能

https://www.cnblogs.com/haoxj/p/17419045.html

posted @ 2023-05-21 20:14  haoxj  阅读(456)  评论(2编辑  收藏  举报