Skip to content

Latest commit

 

History

History
439 lines (358 loc) · 21.9 KB

README.zh-CN.md

File metadata and controls

439 lines (358 loc) · 21.9 KB

Magicodes.IE | English

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

Stargazers over time

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

目录

  1. 概述
  2. 自动构建
  3. Nuget包
  4. 注意事项
  5. 教程
  6. 特点
  7. FAQ
  8. 联系我们
  9. 更新历史
  10. 友情赞助

概述

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

总体说明

功能清单

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

自动构建

  • 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/Magicodes.IE/_build?definitionId=4&_a=summary

NuGet包

稳定版(推荐)

名称 NuGet
Magicodes.IE.Core NuGet
Magicodes.IE.Excel NuGet
Magicodes.IE.Excel.NPOI NuGet
Magicodes.IE.Excel.AspNetCore NuGet
Magicodes.IE.Pdf NuGet
Magicodes.IE.Word NuGet
Magicodes.IE.Html NuGet
Magicodes.IE.Csv NuGet
Magicodes.IE.AspNetCore NuGet
Magicodes.IE.EPPlus NuGet
Magicodes.IE.Excel.Abp NuGet
Magicodes.IE.Csv.Abp NuGet
Magicodes.IE.Html.Abp NuGet
Magicodes.IE.Pdf.Abp NuGet
Magicodes.IE.Word.Abp NuGet
Magicodes.IE.Stash NuGet

注意事项

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

教程

  1. 基础教程之导入学生数据点此访问国内文档
  2. 基础教程之导出Excel (点此访问国内文档)
  3. 基础教程之导出Pdf收据 (点此访问国内文档)
  4. 在Docker中使用
  5. 动态导出
  6. 多Sheet导入
  7. Csv导入导出
  8. Excel图片导入导出 (点此访问国内文档)
  9. Excel模板导出之导出教材订购表点此访问国内文档
  10. 进阶篇之导入导出筛选器
  11. Magicodes.IE之花式导出
  12. Magicodes.IE.AspNetCore之一行代码多格式导出
  13. 性能测试
  14. Excel合并行导入
  15. Excel模板导出之动态导出
  16. Magicodes.IE.Excel.AspNetCore之快速导出Excel(new)

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

特点

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

            var filePath = GetTestFilePath($"{nameof(ExportAsByteArraySupportDynamicType_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.ExportAsByteArray<ExpandoObject>(shapedData);
            result.ShouldNotBeNull();
            result.Length.ShouldBeGreaterThan(0);
            File.WriteAllBytes(filePath, result);
            File.Exists(filePath).ShouldBeTrue();
        }
  • 支持值映射,支持通过“ValueMappingAttribute”特性设置值映射关系,目前仅可用于枚举和Bool类型,支持导入导出。
        /// <summary>
        ///     性别
        /// </summary>
        [ImporterHeader(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>
        [ImporterHeader(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导出

exporter.Append(list1).SeparateByColumn().Append(list2).ExportAppendData(filePath);

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

  • 支持单元格导出宽度设置
[ExporterHeader(Width = 100)]
public DateTime Time3 { get; set; }
  • Excel导出支持HeaderRowIndex,在ExcelExporterAttribute导出特性类中添加HeaderRowIndex属性,方便导出时去指定从第一行开始导出。

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

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

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

    合并行导入文件

  • 添加对Abp模块的包装,具体见#318

联系我们

订阅号

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

QQ群
  • 编程交流群<85318032>(由于不经常在线,为了避免骚扰,设置了一定门槛)
文档官网&官方博客
其他开源库

Code Contributors

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]