ZhileTime.IE.Word 1.1.0

<img align="right" src="./res/logo.jpg" width="300"/>

ZhileTime.IE |

👁 Member project of .NET Core Community
👁 nuget
👁 Build Status
👁 stats
👁 License

最近主要精力都在CodeSpirit，由于业余精力极其有限，ZhileTime.IE仅作间歇性维护。

地址（优先更新Gitee，路径沿用历史组织名）：CodeSpirit（码灵）

说明：下文个别外部链接仍包含历史组织路径，仅为第三方平台沿用的地址命名，不代表当前项目名称。

简介：CodeSpirit（码灵）是一款革命性的全栈低代码智能体开发框架，通过智能代码生成引擎与AI深度协同，实现后端驱动式全栈开发范式。基于.NET 10技术栈构建，将具备企业级技术深度与云原生扩展能力，提供从界面生成、业务逻辑编排到系统运维的全生命周期支持。

让全栈开发回归工程本质

• 后端驱动式开发范式 · 企业级开放架构 · AI增强工程闭环

👁 Azure DevOps tests (master)
👁 Azure DevOps coverage (branch)
👁 Financial Contributors on Open Collective

目录

1. 概述
2. 自动构建
3. Nuget包
4. 注意事项
5. 教程
6. 特点
7. FAQ
8. 联系我们
9. 贡献者

概述

导入导出通用库，支持Dto导入导出、模板导出、花式导出以及动态导出，支持Excel、Csv、Word、Pdf和Html。

• Github：https://github.com/dotnetcore/ZhileTime.IE
• 码云（手动同步，不维护，路径沿用历史组织名）：https://gitee.com/magicodes/ZhileTime.IE

功能清单

• Excel
  • 导入
    • Dto导入
      • 导入配置
        • 指定Sheet名称(获取指定Sheet名称)，为空则自动获取第一个
        • 指定Sheet下标
        • 截止读取的列数（从1开始，如果已设置，则将支持空行以及特殊列）
        • 是否标注错误（默认为true）
        • Sheet顶部导入描述
        • Sheet顶部导入描述高度(换行可能无法自动设定高度,默认为Excel的默认行高)
        • 是否仅导出错误数据
        • 表头位置
        • 最大允许导入的行数（默认没有限制）
        • 导入结果筛选器
        • 导入列头筛选器
        • 是否禁用所有筛选器
        • 是否忽略列的大小写
      • 列配置
        • 列名
        • 批注
        • 作者
        • 自动过滤空格，默认启用
        • 处理所有的空格，包括中间空格
        • 格式化（仅用于模板生成）
        • 列索引，如果为0则自动计算
        • 是否忽略
      • 导入验证
        • DataAnnotations（MaxLength、Required...）
        • 是否允许重复
      • 值映射
        • bool
        • 枚举
      • 筛选器
        • 结果筛选器
        • 列头筛选器
      • 特殊数据列导入
        • 图片导入
          • 导入为Base64
          • 导入到临时目录
          • 导入到指定目录
      • 合并行导入
      • 错误处理
        • 模板校验错误
        • 数据验证错误
        • 异常
        • 导入Excel文件的错误标注
      • 生成导入模板
        • 数据验证提示
        • 必填项标注
        • 数据下拉项生成（仅枚举）
        • 生成批注
        • Excel内置数据验证，并支持自定义提示（默认未开启）
          • MaxLengthAttribute
          • MinLengthAttribute
          • StringLengthAttribute
          • RangeAttribute
      • 乱序导入（无需按列顺序导入）
      • 多Sheet导入
    • 动态导入（主干入口：ZhileTime.IE.Excel.Importing.Dynamic.DynamicExcelImporter，脚本与规则扩展位于 ZhileTime.IE.Extensions.*，迁移说明见 ）
  • 导出

自动构建

• Build Status：👁 Build Status
  
• Azure DevOps coverage (master): 👁 Azure DevOps coverage (branch)
  
• Azure DevOps tests (master): 👁 Azure DevOps tests (master)
  

具体见：https://dev.azure.com/xinlaiopencode/ZhileTime.IE/_build?definitionId=4&_a=summary

NuGet包

稳定版（推荐）

注意事项

• Excel导入不支持“.xls”文件，即不支持Excel97-2003。
• 如需在Docker中使用，请参阅文档中的《Docker中使用》一节。
• 相关功能均已编写单元测试，在使用的过程中可以参考单元测试。

教程

1. （点此访问国内文档）
2. （点此访问国内文档）
3. (点此访问国内文档)
8. (点此访问国内文档)
9. （点此访问国内文档）

其他教程见下文或单元测试

特点

• 需配合相关导入导出的DTO模型使用，支持通过DTO以及相关特性控制导入导出。配置特性即可控制相关逻辑和显示结果，无需修改逻辑代码；
• 支持各种筛选器，支持依赖注入，以便支持多语言、动态控制列展示等场景，具体使用见单元测试：
  • 导入列头筛选器【IImportHeaderFilter】（可动态指定导入列、导入的值映射关系）
  • 导出列头筛选器【IExportHeaderFilter】（可动态控制导出列，支持单列 Filter(ExportColumn) 和集合 Filter(IList<ExportColumn>) 两种粒度）
  • 导入结果筛选器【IImportResultFilter】（可修改标注文件）
• 导出支持文本自定义过滤或处理；
• 导入支持中间空行自动跳过；
• 导入支持自动根据 DTO 生成导入模板,针对必填项将自动标注；
• 导入支持数据下拉选择，目前仅支持枚举类型；
• 导入数据支持前后空格以及中间空格处理，允许指定列进行设置；
• 导入支持模板自动检查，数据自动校验，异常统一处理，并提供统一的错误封装，包含异常、模板错误和行数据错误；
• 支持导入表头位置设置，默认为1；
• 支持导入列乱序，无需按顺序一一对应；
• 支持导入指定列索引，默认自动识别；
• 导出Excel支持拆分Sheet，仅需设置特性【ExcelExporterAttribute】的【MaxRowNumberOnASheet】的值，为0则不拆分。具体见单元测试；
• 支持将导入Excel进行错误标注；
• 导入支持截止列设置，如未设置则默认遇到空格截止；
• 支持导出HTML、Word、Pdf，支持自定义导出模板；
  • 导出HTML
  • 导出Word
  • 导出Pdf，支持设置，具体见更新日志
  • 导出收据
• 导入支持重复验证；
• 支持单个数据模板导出，常用于导出收据、凭据等业务
• 支持动态列导出（基于DataTable），并且超过100W将自动拆分Sheet。（感谢张善友老师（https://github.com/xin-lai/ZhileTime.IE/pull/8 ））
• 支持 dynamic/ExpandoObject 动态列导出

 [Fact(DisplayName = "DTO导出支持动态类型")]
 public async Task ExportAsBytesAsyncSupportDynamicType_Test()
 {
 IExcelExporter exporter = new ExcelExporter();

 var filePath = GetTestFilePath($"{nameof(ExportAsBytesAsyncSupportDynamicType_Test)}.xlsx");

 DeleteFile(filePath);

 var source = GenFu.GenFu.ListOf<ExportTestDataWithAttrs>();
 string fields = "text,number,name";
 var shapedData = source.ShapeData(fields) as ICollection<ExpandoObject>;

 var result = await exporter.ExportAsBytesAsync(shapedData);
 result.ShouldNotBeNull();
 result.Length.ShouldBeGreaterThan(0);
 File.WriteAllBytes(filePath, result);
 File.Exists(filePath).ShouldBeTrue();
 }

• 支持值映射，支持通过“ValueMappingAttribute”特性设置值映射关系，目前仅可用于枚举和Bool类型，支持导入导出。

 /// <summary>
 /// 性别
 /// </summary>
 [ImportHeader(Name = "性别")]
 [Required(ErrorMessage = "性别不能为空")]
 [ValueMapping(text: "男", 0)]
 [ValueMapping(text: "女", 1)]
 public Genders Gender { get; set; }

• 也可以继承“ValueMappingsBaseAttribute”特性基类实现值映射关系，目前仅可用于枚举和Bool类型，支持导入导出。

 [AttributeUsage(AttributeTargets.Property, AllowMultiple = true)]
 public class GenderLocalAttribute : ValueMappingsBaseAttribute
 {
 public override Dictionary<string, object> GetMappings(PropertyInfo propertyInfo)
 {
 var res= new Dictionary<string, object>();
 res.Add("男",0);
 res.Add("女",1);
 return res;
 }
 }


 /// <summary>
 /// 性别
 /// </summary>
 [ImportHeader(Name = "性别")]
 [Required(ErrorMessage = "性别不能为空")]
 [GenderLocal]
 public Genders Gender { get; set; }

• 支持枚举和Bool类型的导入数据验证项的生成，以及相关数据转换

  • 枚举默认情况下会自动获取枚举的描述、显示名、名称和值生成数据项

     	/// <summary>
     	/// 学生状态 正常、流失、休学、勤工俭学、顶岗实习、毕业、参军
     	/// </summary>
     	public enum StudentStatus
     	{
     		/// <summary>
     		/// 正常
     		/// </summary>
     		[Display(Name = "正常")]
     		Normal = 0,
    
     		/// <summary>
     		/// 流失
     		/// </summary>
     		[Description("流水")]
     		PupilsAway = 1,
    
     		/// <summary>
     		/// 休学
     		/// </summary>
     		[Display(Name = "休学")]
     		Suspension = 2,
    
     		/// <summary>
     		/// 勤工俭学
     		/// </summary>
     		[Display(Name = "勤工俭学")]
     		WorkStudy = 3,
    
     		/// <summary>
     		/// 顶岗实习
     		/// </summary>
     		[Display(Name = "顶岗实习")]
     		PostPractice = 4,
    
     		/// <summary>
     		/// 毕业
     		/// </summary>
     		[Display(Name = "毕业")]
     		Graduation = 5,
    
     		/// <summary>
     		/// 参军
     		/// </summary>
     		[Display(Name = "参军")]
     		JoinTheArmy = 6,
     	}
    

  • bool类型默认会生成“是”和“否”的数据项

  • 如果已设置自定义值映射，则不会生成默认选项

• 支持excel多Sheet导入；

• 支持Excel模板导出，JSON动态导出，并且支持图片渲染

  渲染语法如下所示：

   {{Company}} //单元格渲染
   {{Table>>BookInfos|RowNo}} //表格渲染开始语法
   {{Remark|>>Table}}//表格渲染结束语法
   {{Image::ImageUrl?Width=50&Height=120&Alt=404}} //图片渲染
   {{Image::ImageUrl?w=50&h=120&Alt=404}} //图片渲染
   {{Image::ImageUrl?Alt=404}} //图片渲染
   {{Formula::AVERAGE?params=G4:G6}} //公式渲染
   {{Formula::SUM?params=G4:G6&G4}} //公式渲染
  

  后续将支持自定义管道。

• 支持Excel导入模板生成标注

• 支持Excel图片导入导出

  • 图片导入
    • 导入为Base64
    • 导入到临时目录
    • 导入到指定目录
  • 图片导出
    • 将文件路径导出为图片
    • 将网络路径导出为图片

• 支持多个实体导出多个Sheet

• 支持使用System.ComponentModel.DataAnnotations命名空间下的部分特性来控制导入导出 #63

• 支持在ASP.NET Core Web API 中使用自定义格式化程序导出Excel、Pdf、Csv等内容，具体见教程 #64

• 支持分栏、分sheet、追加rows导出

await exporter.Append(list1).SeparateByColumn().Append(list2).ExportAppendDataFileAsync(filePath);

具体见上面教程《ZhileTime.IE之花式导出》

• 支持单元格导出宽度设置

[ExportHeader(Width = 100)]
public DateTime Time3 { get; set; }

• Excel导出支持HeaderRowIndex，在ExcelExporterAttribute导出特性类中添加HeaderRowIndex属性，方便导出时去指定从第一行开始导出。

• Excel生成导入模板支持内置数据验证

对于内置数据验证的支持可通过IsInterValidation属性开启，并且需要注意的是仅支持MaxLengthAttribute、 MinLengthAttribute、 StringLengthAttribute、 RangeAttribute支持对内置数据验证的开启操作。 支持对输入提示的展示操作：

• Excel导入支持合并行数据 #239

联系我们

订阅号

关注“麦扣聊技术”订阅号可以获得最新文章、教程、文档，并且加入微信生态群：

<table> <tr> <td> <img align="left" src="./res/wechat.jpg" width="300"/> </td> <td> <img align="right" src="./res/IE_WeChat.png" width="300"/> </td> </tr> </table>

文档官网&官方博客

• 官方博客： http://www.cnblogs.com/codelove/
• GitHub： https://github.com/dotnetcore/ZhileTime.IE
• Gitee（手动同步，不维护，路径沿用历史组织名）： https://gitee.com/magicodes/ZhileTime.IE

贡献者

Code Contributors

本项目感谢所有贡献者的支持。[]

<a href="https://github.com/dotnetcore/ZhileTime.IE/graphs/contributors"><img src="https://opencollective.com/magicodes/contributors.svg?width=890&button=false" /></a>

Financial Contributors

以下 OpenCollective 链接与徽章沿用历史组织路径，用于保留既有赞助与贡献记录。

成为财务贡献者，帮助我们维持社区发展。[贡献]

Individuals

<a href="https://opencollective.com/magicodes"><img src="https://opencollective.com/magicodes/individuals.svg?width=890"></a>

Organizations

用您的组织支持这个项目。您的徽标将显示在这里，并链接到您的网站。[贡献]

<a href="https://opencollective.com/magicodes/organization/0/website"><img src="https://opencollective.com/magicodes/organization/0/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/1/website"><img src="https://opencollective.com/magicodes/organization/1/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/2/website"><img src="https://opencollective.com/magicodes/organization/2/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/3/website"><img src="https://opencollective.com/magicodes/organization/3/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/4/website"><img src="https://opencollective.com/magicodes/organization/4/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/5/website"><img src="https://opencollective.com/magicodes/organization/5/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/6/website"><img src="https://opencollective.com/magicodes/organization/6/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/7/website"><img src="https://opencollective.com/magicodes/organization/7/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/8/website"><img src="https://opencollective.com/magicodes/organization/8/avatar.svg"></a> <a href="https://opencollective.com/magicodes/organization/9/website"><img src="https://opencollective.com/magicodes/organization/9/avatar.svg"></a>