尧图网页设计 
后端【免费下载链接】fesodFast. Easy. Done. Processing spreadsheets without worrying about large files causing OOM.项目地址https://gitcode.com/gh_mirrors/fast/fesod点击查看免费下载本篇技术指南以 Apache FesodIncubating孵化项目中的 FesodSheet 模块为对象系统讲解其全部内置注解从读写字段映射的核心注解ExcelProperty、忽略控制注解到日期/数字格式化注解再到列宽、行高、字体、单元格样式、循环合并、绝对合并与冻结窗格等写场景注解。读者读完将能够使用纯注解方式完成 POJO 与 Excel 之间的双向映射、字段格式定制与输出美化并理解这些注解在源码中的底层生效机制直接用于真实业务开发。注解体系总览实体类如何驱动读写FesodSheet 的读写操作以实体类Entity Class为基石读操作把工作表中的行数据反序列化到实体类字段写操作则把实体类实例序列化回工作表。为了让开发者免于手写大量样板代码模块提供了分布在不同包中的注解整体分为四类分类注解作用域字段映射ExcelProperty、ExcelIgnore字段忽略控制ExcelIgnoreUnannotated类TYPE格式转换DateTimeFormat、NumberFormat字段写入样式ColumnWidth、HeadRowHeight、ContentRowHeight、HeadFontStyle、ContentFontStyle、HeadStyle、ContentStyle、ContentLoopMerge、OnceAbsoluteMerge、FreezePane字段 / 类所有注解均声明为Retention(RetentionPolicy.RUNTIME)且带Inherited这意味着注解在运行时可通过反射读取且子类能够继承父类的注解配置。对应的注解源码统一位于 fesod-sheet/src/main/java/org/apache/fesod/sheet/annotation格式类位于其下的format/子包样式类位于write/style/子包。字段映射核心ExcelPropertyExcelProperty是 FesodSheet 中使用频率最高的注解它定义了字段在工作表中的列名与列位置映射。源码定义于 ExcelProperty.java完整参数如下参数默认值说明value空{}用于匹配工作表中的表头必须完全匹配如果存在多行表头匹配最后一行的表头orderInteger.MAX_VALUE优先级高于value按照order的大小顺序决定实体字段与工作表列的顺序index-1优先级高于value与order直接指定该字段匹配工作表中的第几列converterAutoConverter.class自动选择指定当前字段使用的转换器默认自动选择优先级规则index order 默认排序从源码的 Javadoc 注释priority: index order default sort可以确认三条匹配路径的优先级index优先直接按列下标读写完全不依赖表头名称其次order不关心表头叫什么只按顺序对应最后value默认按表头名称精确匹配这也是最常见的用法。一个综合示例public class UserData { // 按表头名称匹配默认路径 ExcelProperty(用户名) private String name; // 按顺序匹配先于 value 生效 ExcelProperty(order 1) private Integer age; // 按下标匹配优先级最高 ExcelProperty(index 2) private String phone; }value 的多表头行为value的类型是String[]支持传入多个表头名称。写入时如果传入多个表头FesodSheet 会自动进行表头合并生成多级表头读取时当存在多行表头时取最后一行的表头进行匹配。这一读写差异直接写在了ExcelProperty.java的源码注释中是设计上的刻意行为用于兼容复杂表头的报表场景。自定义 converter 与读取接口当内置转换器无法满足需求时可通过converter参数指定自定义转换器。文档约定读取场景下只要实现Converter#convertToJavaData(ReadConverterContext?)方法即可而默认的AutoConverter会依据目标字段类型自动挑选合适的转换器。FesodSheet 内置了覆盖Boolean、Byte、Short、Integer、Long、Float、Double、BigDecimal、BigInteger、String、Date、LocalDate、LocalDateTime、LocalTime、图片字节数组 /File/InputStream/URL/ Base64 字符串等类型的转换器族位于 fesod-sheet/src/main/java/org/apache/fesod/sheet/converters 目录下。字段忽略控制ExcelIgnore 与 ExcelIgnoreUnannotatedExcelIgnore忽略单个字段默认情况下实体类的所有字段都会参与与工作表的匹配。若某个字段如逻辑标志位、冗余属性不希望出现在读写结果中直接加上ExcelIgnore即可其源码见 ExcelIgnore.java。public class OrderData { ExcelProperty(订单号) private String orderNo; ExcelIgnore private String internalFlag; // 不参与读写 }ExcelIgnoreUnannotated类级白名单模式与前者相反ExcelIgnoreUnannotated是标注在类上的Target(ElementType.TYPE)语义是默认所有未标注ExcelProperty的字段都不参与读写。它实际上把默认行为从全参与切换为仅注解字段参与适合字段多、只需导出个别列的瘦身场景。源码见 ExcelIgnoreUnannotated.java。ExcelIgnoreUnannotated public class BriefData { ExcelProperty(姓名) private String name; // 参与读写 private String address; // 被忽略 private int score; // 被忽略 }需要留意的是注解字段的筛选结果最终会沉淀在FieldCache中——源码 FieldCache.java 表明它持有一张已按类排序、剔除不需要字段的sortedFieldMap与一张使用 index 属性字段的indexFieldMap读写引擎据此决定实际处理的字段集合。格式化注解日期与数字的 String 接收FesodSheet 允许用String类型字段接收工作表中的日期或数字单元格但触发条件不同。DateTimeFormat日期格式化源码 DateTimeFormat.java 明确说明其适用范围写入时可用于java.util.Date类字段读取时可用于String类字段。即用String接收工作表中的日期格式数据时该注解才会被调用。参数默认值说明value空日期格式模式遵循java.text.SimpleDateFormat规范如yyyy-MM-dd HH:mm:ssuse1904windowingBooleanEnum.DEFAULT自动选择Excel 内部以从 1900 起算的双精度浮点数存储时间但部分工作簿如 macOS 创建的以 1904 为起始日置为true可将起始日切换为 1904示例public class RecordData { ExcelProperty(创建时间) DateTimeFormat(yyyy-MM-dd HH:mm:ss) private String createTime; ExcelProperty(记录时间) DateTimeFormat(value yyyy/MM/dd, use1904windowing BooleanEnum.TRUE) private String recordTime; }use1904windowing参数使用模块自定义的BooleanEnum三态枚举DEFAULT/TRUE/FALSEDEFAULT表示由框架自动判断。NumberFormat数字格式化源码 NumberFormat.java 说明其适用范围写入时可用于继承自java.lang.Number的类读取时可用于String类字段。即用String接收工作表中的数字格式数据时触发。参数默认值说明value空数字格式模式遵循java.text.DecimalFormat规范如#,##0.00roundingModeRoundingMode.HALF_UP格式化时的舍入模式示例public class PriceData { ExcelProperty(单价) NumberFormat(#,##0.00) private String price; ExcelProperty(折扣) NumberFormat(value 0.00%, roundingMode RoundingMode.DOWN) private String discount; }写入样式注解列宽、行高与字体以下注解均位于 fesod-sheet/src/main/java/org/apache/fesod/sheet/annotation/write/style 目录专门作用于写入场景的表格外观控制。ColumnWidth指定列宽标注在字段或类上均可Target({FIELD, TYPE})类级别可统一设置整表列宽。参数value默认-1表示使用默认列宽设置具体数值即为该列宽度。源码见 ColumnWidth.java。public class ProductData { ExcelProperty(商品名称) ColumnWidth(20) private String name; }HeadRowHeight 与 ContentRowHeight表头/内容行高两者都标注在类上Target(TYPE)分别指定表头行与内容行的高度参数value默认-1表示自动行高源码注释明确 -1 mean the auto set height源码见 HeadRowHeight.java。HeadRowHeight(30) ContentRowHeight(22) public class EmployeeData { ExcelProperty(姓名) private String name; }HeadFontStyle 与 ContentFontStyle字体定制分别定制表头与内容数据的字体样式可标注在字段或类上。两者参数完全一致参数默认值说明fontName空字体名称如 ArialfontHeightInPoints-1字号单位磅 pointitalicBooleanEnum.DEFAULT是否斜体strikeoutBooleanEnum.DEFAULT是否添加贯穿文字的删除线color-1字体颜色参照org.apache.poi.ss.usermodel.IndexedColors或org.apache.poi.ss.usermodel.Font如Font.COLOR_NORMALtypeOffset-1上标/下标偏移参照Font如Font.SS_NONE、Font.SS_SUPER、Font.SS_SUBunderline-1下划线类型参照Font如Font.U_SINGLE、Font.U_DOUBLE等charset-1字符集参照org.apache.poi.common.usermodel.fonts.FontCharset或Font如Font.ANSI_CHARSETboldBooleanEnum.DEFAULT是否加粗源码 HeadFontStyle.java 中还补充了各参数的可选常量typeOffset可取值SS_NONE/SS_SUPER/SS_SUBunderline可取值U_NONE/U_SINGLE/U_DOUBLE/U_SINGLE_ACCOUNTING/U_DOUBLE_ACCOUNTINGcharset可取值ANSI_CHARSET/DEFAULT_CHARSET/SYMBOL_CHARSET。public class HeaderData { ExcelProperty(姓名) HeadFontStyle(fontName Arial, fontHeightInPoints 14, bold BooleanEnum.TRUE) ContentFontStyle(fontName Arial, fontHeightInPoints 11) private String name; }单元格样式HeadStyle 与 ContentStyle这两个注解分别定制表头单元格与内容单元格的完整样式边框、对齐、颜色、填充等参数完全一致可标注在字段或类上。完整的 21 项参数如下参数默认值说明dataFormat-1数据格式必须是org.apache.poi.ss.usermodel.BuiltinFormats中定义的有效格式hiddenBooleanEnum.DEFAULT隐藏单元格仅在 sheet 受保护时生效lockedBooleanEnum.DEFAULT锁定单元格仅在 sheet 受保护时生效quotePrefixBooleanEnum.DEFAULT是否开启 Quote Prefix把形似数字/公式的内容当作文本处理类似于在 Excel 中手动加前缀horizontalAlignmentHorizontalAlignmentEnum.DEFAULT水平对齐方式wrappedBooleanEnum.DEFAULT文本是否在单元格内自动换行多行显示verticalAlignmentVerticalAlignmentEnum.DEFAULT垂直对齐方式rotation-1文本旋转角度。注意 HSSF 使用 -90~90XSSF 使用 0~180POI 实现会自动映射换算indent-1文本缩进的空格数borderLeft/borderRight/borderTop/borderBottomBorderStyleEnum.DEFAULT四边边框样式leftBorderColor/rightBorderColor/topBorderColor/bottomBorderColor-1四边边框颜色参照org.apache.poi.ss.usermodel.IndexedColorsfillPatternTypeFillPatternTypeEnum.DEFAULT填充图案类型如SOLID_FOREGROUND实心前景填充fillBackgroundColor-1背景填充色fillForegroundColor-1前景填充色必须先于背景色设置源码注释特别强调 Ensure Foreground color is set prior to background colorshrinkToFitBooleanEnum.DEFAULT文本过长时是否自动缩小字号以适配单元格这些对齐、边框、填充枚举定义在 fesod-sheet/src/main/java/org/apache/fesod/sheet/enums/poiHorizontalAlignmentEnum、VerticalAlignmentEnum、BorderStyleEnum、FillPatternTypeEnum它们将 FesodSheet 的声明式枚举安全映射到 POI 底层枚举。源码 HeadStyle.java 进一步说明rotation的 -90~90HSSF与 0~180XSSF两套取值范围由 POI 实现自动映射quotePrefix的效果近似于在 Excel 中给单元格值加单引号前缀。典型应用——表头灰底加边框、内容右对齐public class LedgerData { ExcelProperty(金额) HeadStyle( fillPatternType FillPatternTypeEnum.SOLID_FOREGROUND, fillForegroundColor 22, // IndexedColors.GREY_25_PERCENT borderTop BorderStyleEnum.THIN, borderBottom BorderStyleEnum.THIN, borderLeft BorderStyleEnum.THIN, borderRight BorderStyleEnum.THIN ) ContentStyle(horizontalAlignment HorizontalAlignmentEnum.RIGHT) private BigDecimal amount; }合并单元格ContentLoopMerge 与 OnceAbsoluteMergeContentLoopMerge内容循环合并定义一个循环合并策略把每 N 行的相同内容单元格按列方向合并常用于商品、订单等按分组重复数据的展示。参数默认值说明eachRow1每个合并循环包含的行数columnExtend1合并延伸的列数public class OrderGroupData { ExcelProperty(订单号) ContentLoopMerge(eachRow 2, columnExtend 1) private String orderNo; }OnceAbsoluteMerge一次性绝对合并定义一次性的绝对合并区域直接以行、列下标圈定合并矩形适合合并固定的标题区或汇总区。参数默认值说明firstRowIndex-1合并起始行下标lastRowIndex-1合并结束行下标firstColumnIndex-1合并起始列下标lastColumnIndex-1合并结束列下标OnceAbsoluteMerge(firstRowIndex 0, lastRowIndex 0, firstColumnIndex 0, lastColumnIndex 3) public class ReportData { // 首行前 4 列合并为一个标题单元格 }两种合并注解分别对应框架中的循环合并策略与一次性合并策略实现LoopMergeStrategy与OnceAbsoluteMergeStrategy在写入执行器处理表头与内容时会按注解配置生成对应的合并区域。冻结窗格FreezePaneFreezePane标注在类上用于定义工作表的冻结窗格——滚动时保持指定行列区域始终可见适合固定表头或首列。参数默认值说明colSplit0冻结窗格的水平位置左侧冻结列数rowSplit0冻结窗格的垂直位置顶部冻结行数leftmostColumn-1右窗格中可见的最左列默认等于colSplittopRow-1下窗格中可见的最上行默认等于rowSplit源码见 FreezePane.java。示例——冻结首行与首列FreezePane(colSplit 1, rowSplit 1) public class FrozenData { ExcelProperty(编号) private String id; }leftmostColumn与topRow两个可选参数用于精确控制滚动后窗格内首个可见单元格的位置日常场景通常只需指定colSplit与rowSplit即可。注解如何被读写引擎消费FesodSheet 的读写引擎通过运行时反射消费上述注解整个过程分为两步字段筛选与排序引擎读取类上的ExcelIgnoreUnannotated决定仅注解字段或全字段策略再按ExcelIgnore剔除忽略字段最终按ExcelProperty的index/order优先级构建字段映射。筛选结果以FieldCacheFieldCache.java形式缓存——sortedFieldMap保存按序排列的FieldWrapperindexFieldMap单独保存使用index属性的字段避免重复扫描并加速后续读写。按场景分发DateTimeFormat、NumberFormat交由格式化转换器在处理String接收的日期/数字单元格时生效样式类注解则在写入流程中由写处理器write handler转换为 POI 的CellStyle/Font设置合并与冻结注解分别对应合并策略与冻结窗格策略的执行。因此开发者只需维护一个实体类即可同时驱动读列映射、格式转换与写表头、样式、合并、冻结两条链路这与 FesodSheet 文档中实体类是读写操作基础的设计一致。小结与最佳实践场景推荐注解组合简单按表头读写ExcelProperty(列名)固定列序或跳过表头匹配ExcelProperty(index n)或ExcelProperty(order n)排除无关字段单个用ExcelIgnore批量白名单用类级ExcelIgnoreUnannotatedString 接收日期/数字DateTimeFormat(yyyy-MM-dd)/NumberFormat(#,##0.00)输出排版ColumnWidthHeadRowHeight/ContentRowHeight 字体与样式注解报表合并与固定表头ContentLoopMerge/OnceAbsoluteMerge/FreezePane几点实践提醒多表头读取时value只匹配最后一行表头若需精确控制应改用index样式注解中的hidden/locked仅在 sheet 受保护时生效fillForegroundColor必须先于fillBackgroundColor设置否则实心填充可能失效。本文所述注解的完整源码与单元测试可在仓库 fesod-sheet 模块的annotation目录及 fesod-sheet/src/test/java/org/apache/fesod/sheet/style 测试中进一步查阅验证。赞分享后端【免费下载链接】fesodFast. Easy. Done. Processing spreadsheets without worrying about large files causing OOM.项目地址https://gitcode.com/gh_mirrors/fast/fesod点击查看免费下载相关推荐Apache Fesod注解系统完全指南ExcelProperty、ExcelIgnore深度实战教程Apache Fesod注解系统完全指南ExcelProperty、ExcelIgnore深度实战教程 Apache Fesod作为easyexcel作者后端EasyExcel终极指南ExcelProperty注解value属性的完整解析与应用实践EasyExcel终极指南ExcelProperty注解value属性的完整解析与应用实践 在数据处理领域Excel作为最常用的办公软件其文件处理一直是J后端Apache Fesod合并策略完全指南LoopMerge与OnceAbsoluteMerge实战解析Apache Fesod合并策略完全指南LoopMerge与OnceAbsoluteMerge实战解析 Apache Fesod作为easyexcel作者最新后端上一篇社区贡献指南如何参与Qwen3.5-9B-GLM5.1-Distill-v1的改进与优化下一篇开源项目 OpenHMD 安装与使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Apache FesodSheet 注解使用全指南：@ExcelProperty 到样式与合并的完整实战解析
后端【免费下载链接】fesodFast. Easy. Done. Processing spreadsheets without worrying about large files causing OOM.项目地址https://gitcode.com/gh_mirrors/fast/fesod点击查看免费下载本篇技术指南以 Apache FesodIncubating孵化项目中的 FesodSheet 模块为对象系统讲解其全部内置注解从读写字段映射的核心注解ExcelProperty、忽略控制注解到日期/数字格式化注解再到列宽、行高、字体、单元格样式、循环合并、绝对合并与冻结窗格等写场景注解。读者读完将能够使用纯注解方式完成 POJO 与 Excel 之间的双向映射、字段格式定制与输出美化并理解这些注解在源码中的底层生效机制直接用于真实业务开发。注解体系总览实体类如何驱动读写FesodSheet 的读写操作以实体类Entity Class为基石读操作把工作表中的行数据反序列化到实体类字段写操作则把实体类实例序列化回工作表。为了让开发者免于手写大量样板代码模块提供了分布在不同包中的注解整体分为四类分类注解作用域字段映射ExcelProperty、ExcelIgnore字段忽略控制ExcelIgnoreUnannotated类TYPE格式转换DateTimeFormat、NumberFormat字段写入样式ColumnWidth、HeadRowHeight、ContentRowHeight、HeadFontStyle、ContentFontStyle、HeadStyle、ContentStyle、ContentLoopMerge、OnceAbsoluteMerge、FreezePane字段 / 类所有注解均声明为Retention(RetentionPolicy.RUNTIME)且带Inherited这意味着注解在运行时可通过反射读取且子类能够继承父类的注解配置。对应的注解源码统一位于 fesod-sheet/src/main/java/org/apache/fesod/sheet/annotation格式类位于其下的format/子包样式类位于write/style/子包。字段映射核心ExcelPropertyExcelProperty是 FesodSheet 中使用频率最高的注解它定义了字段在工作表中的列名与列位置映射。源码定义于 ExcelProperty.java完整参数如下参数默认值说明value空{}用于匹配工作表中的表头必须完全匹配如果存在多行表头匹配最后一行的表头orderInteger.MAX_VALUE优先级高于value按照order的大小顺序决定实体字段与工作表列的顺序index-1优先级高于value与order直接指定该字段匹配工作表中的第几列converterAutoConverter.class自动选择指定当前字段使用的转换器默认自动选择优先级规则index order 默认排序从源码的 Javadoc 注释priority: index order default sort可以确认三条匹配路径的优先级index优先直接按列下标读写完全不依赖表头名称其次order不关心表头叫什么只按顺序对应最后value默认按表头名称精确匹配这也是最常见的用法。一个综合示例public class UserData { // 按表头名称匹配默认路径 ExcelProperty(用户名) private String name; // 按顺序匹配先于 value 生效 ExcelProperty(order 1) private Integer age; // 按下标匹配优先级最高 ExcelProperty(index 2) private String phone; }value 的多表头行为value的类型是String[]支持传入多个表头名称。写入时如果传入多个表头FesodSheet 会自动进行表头合并生成多级表头读取时当存在多行表头时取最后一行的表头进行匹配。这一读写差异直接写在了ExcelProperty.java的源码注释中是设计上的刻意行为用于兼容复杂表头的报表场景。自定义 converter 与读取接口当内置转换器无法满足需求时可通过converter参数指定自定义转换器。文档约定读取场景下只要实现Converter#convertToJavaData(ReadConverterContext?)方法即可而默认的AutoConverter会依据目标字段类型自动挑选合适的转换器。FesodSheet 内置了覆盖Boolean、Byte、Short、Integer、Long、Float、Double、BigDecimal、BigInteger、String、Date、LocalDate、LocalDateTime、LocalTime、图片字节数组 /File/InputStream/URL/ Base64 字符串等类型的转换器族位于 fesod-sheet/src/main/java/org/apache/fesod/sheet/converters 目录下。字段忽略控制ExcelIgnore 与 ExcelIgnoreUnannotatedExcelIgnore忽略单个字段默认情况下实体类的所有字段都会参与与工作表的匹配。若某个字段如逻辑标志位、冗余属性不希望出现在读写结果中直接加上ExcelIgnore即可其源码见 ExcelIgnore.java。public class OrderData { ExcelProperty(订单号) private String orderNo; ExcelIgnore private String internalFlag; // 不参与读写 }ExcelIgnoreUnannotated类级白名单模式与前者相反ExcelIgnoreUnannotated是标注在类上的Target(ElementType.TYPE)语义是默认所有未标注ExcelProperty的字段都不参与读写。它实际上把默认行为从全参与切换为仅注解字段参与适合字段多、只需导出个别列的瘦身场景。源码见 ExcelIgnoreUnannotated.java。ExcelIgnoreUnannotated public class BriefData { ExcelProperty(姓名) private String name; // 参与读写 private String address; // 被忽略 private int score; // 被忽略 }需要留意的是注解字段的筛选结果最终会沉淀在FieldCache中——源码 FieldCache.java 表明它持有一张已按类排序、剔除不需要字段的sortedFieldMap与一张使用 index 属性字段的indexFieldMap读写引擎据此决定实际处理的字段集合。格式化注解日期与数字的 String 接收FesodSheet 允许用String类型字段接收工作表中的日期或数字单元格但触发条件不同。DateTimeFormat日期格式化源码 DateTimeFormat.java 明确说明其适用范围写入时可用于java.util.Date类字段读取时可用于String类字段。即用String接收工作表中的日期格式数据时该注解才会被调用。参数默认值说明value空日期格式模式遵循java.text.SimpleDateFormat规范如yyyy-MM-dd HH:mm:ssuse1904windowingBooleanEnum.DEFAULT自动选择Excel 内部以从 1900 起算的双精度浮点数存储时间但部分工作簿如 macOS 创建的以 1904 为起始日置为true可将起始日切换为 1904示例public class RecordData { ExcelProperty(创建时间) DateTimeFormat(yyyy-MM-dd HH:mm:ss) private String createTime; ExcelProperty(记录时间) DateTimeFormat(value yyyy/MM/dd, use1904windowing BooleanEnum.TRUE) private String recordTime; }use1904windowing参数使用模块自定义的BooleanEnum三态枚举DEFAULT/TRUE/FALSEDEFAULT表示由框架自动判断。NumberFormat数字格式化源码 NumberFormat.java 说明其适用范围写入时可用于继承自java.lang.Number的类读取时可用于String类字段。即用String接收工作表中的数字格式数据时触发。参数默认值说明value空数字格式模式遵循java.text.DecimalFormat规范如#,##0.00roundingModeRoundingMode.HALF_UP格式化时的舍入模式示例public class PriceData { ExcelProperty(单价) NumberFormat(#,##0.00) private String price; ExcelProperty(折扣) NumberFormat(value 0.00%, roundingMode RoundingMode.DOWN) private String discount; }写入样式注解列宽、行高与字体以下注解均位于 fesod-sheet/src/main/java/org/apache/fesod/sheet/annotation/write/style 目录专门作用于写入场景的表格外观控制。ColumnWidth指定列宽标注在字段或类上均可Target({FIELD, TYPE})类级别可统一设置整表列宽。参数value默认-1表示使用默认列宽设置具体数值即为该列宽度。源码见 ColumnWidth.java。public class ProductData { ExcelProperty(商品名称) ColumnWidth(20) private String name; }HeadRowHeight 与 ContentRowHeight表头/内容行高两者都标注在类上Target(TYPE)分别指定表头行与内容行的高度参数value默认-1表示自动行高源码注释明确 -1 mean the auto set height源码见 HeadRowHeight.java。HeadRowHeight(30) ContentRowHeight(22) public class EmployeeData { ExcelProperty(姓名) private String name; }HeadFontStyle 与 ContentFontStyle字体定制分别定制表头与内容数据的字体样式可标注在字段或类上。两者参数完全一致参数默认值说明fontName空字体名称如 ArialfontHeightInPoints-1字号单位磅 pointitalicBooleanEnum.DEFAULT是否斜体strikeoutBooleanEnum.DEFAULT是否添加贯穿文字的删除线color-1字体颜色参照org.apache.poi.ss.usermodel.IndexedColors或org.apache.poi.ss.usermodel.Font如Font.COLOR_NORMALtypeOffset-1上标/下标偏移参照Font如Font.SS_NONE、Font.SS_SUPER、Font.SS_SUBunderline-1下划线类型参照Font如Font.U_SINGLE、Font.U_DOUBLE等charset-1字符集参照org.apache.poi.common.usermodel.fonts.FontCharset或Font如Font.ANSI_CHARSETboldBooleanEnum.DEFAULT是否加粗源码 HeadFontStyle.java 中还补充了各参数的可选常量typeOffset可取值SS_NONE/SS_SUPER/SS_SUBunderline可取值U_NONE/U_SINGLE/U_DOUBLE/U_SINGLE_ACCOUNTING/U_DOUBLE_ACCOUNTINGcharset可取值ANSI_CHARSET/DEFAULT_CHARSET/SYMBOL_CHARSET。public class HeaderData { ExcelProperty(姓名) HeadFontStyle(fontName Arial, fontHeightInPoints 14, bold BooleanEnum.TRUE) ContentFontStyle(fontName Arial, fontHeightInPoints 11) private String name; }单元格样式HeadStyle 与 ContentStyle这两个注解分别定制表头单元格与内容单元格的完整样式边框、对齐、颜色、填充等参数完全一致可标注在字段或类上。完整的 21 项参数如下参数默认值说明dataFormat-1数据格式必须是org.apache.poi.ss.usermodel.BuiltinFormats中定义的有效格式hiddenBooleanEnum.DEFAULT隐藏单元格仅在 sheet 受保护时生效lockedBooleanEnum.DEFAULT锁定单元格仅在 sheet 受保护时生效quotePrefixBooleanEnum.DEFAULT是否开启 Quote Prefix把形似数字/公式的内容当作文本处理类似于在 Excel 中手动加前缀horizontalAlignmentHorizontalAlignmentEnum.DEFAULT水平对齐方式wrappedBooleanEnum.DEFAULT文本是否在单元格内自动换行多行显示verticalAlignmentVerticalAlignmentEnum.DEFAULT垂直对齐方式rotation-1文本旋转角度。注意 HSSF 使用 -90~90XSSF 使用 0~180POI 实现会自动映射换算indent-1文本缩进的空格数borderLeft/borderRight/borderTop/borderBottomBorderStyleEnum.DEFAULT四边边框样式leftBorderColor/rightBorderColor/topBorderColor/bottomBorderColor-1四边边框颜色参照org.apache.poi.ss.usermodel.IndexedColorsfillPatternTypeFillPatternTypeEnum.DEFAULT填充图案类型如SOLID_FOREGROUND实心前景填充fillBackgroundColor-1背景填充色fillForegroundColor-1前景填充色必须先于背景色设置源码注释特别强调 Ensure Foreground color is set prior to background colorshrinkToFitBooleanEnum.DEFAULT文本过长时是否自动缩小字号以适配单元格这些对齐、边框、填充枚举定义在 fesod-sheet/src/main/java/org/apache/fesod/sheet/enums/poiHorizontalAlignmentEnum、VerticalAlignmentEnum、BorderStyleEnum、FillPatternTypeEnum它们将 FesodSheet 的声明式枚举安全映射到 POI 底层枚举。源码 HeadStyle.java 进一步说明rotation的 -90~90HSSF与 0~180XSSF两套取值范围由 POI 实现自动映射quotePrefix的效果近似于在 Excel 中给单元格值加单引号前缀。典型应用——表头灰底加边框、内容右对齐public class LedgerData { ExcelProperty(金额) HeadStyle( fillPatternType FillPatternTypeEnum.SOLID_FOREGROUND, fillForegroundColor 22, // IndexedColors.GREY_25_PERCENT borderTop BorderStyleEnum.THIN, borderBottom BorderStyleEnum.THIN, borderLeft BorderStyleEnum.THIN, borderRight BorderStyleEnum.THIN ) ContentStyle(horizontalAlignment HorizontalAlignmentEnum.RIGHT) private BigDecimal amount; }合并单元格ContentLoopMerge 与 OnceAbsoluteMergeContentLoopMerge内容循环合并定义一个循环合并策略把每 N 行的相同内容单元格按列方向合并常用于商品、订单等按分组重复数据的展示。参数默认值说明eachRow1每个合并循环包含的行数columnExtend1合并延伸的列数public class OrderGroupData { ExcelProperty(订单号) ContentLoopMerge(eachRow 2, columnExtend 1) private String orderNo; }OnceAbsoluteMerge一次性绝对合并定义一次性的绝对合并区域直接以行、列下标圈定合并矩形适合合并固定的标题区或汇总区。参数默认值说明firstRowIndex-1合并起始行下标lastRowIndex-1合并结束行下标firstColumnIndex-1合并起始列下标lastColumnIndex-1合并结束列下标OnceAbsoluteMerge(firstRowIndex 0, lastRowIndex 0, firstColumnIndex 0, lastColumnIndex 3) public class ReportData { // 首行前 4 列合并为一个标题单元格 }两种合并注解分别对应框架中的循环合并策略与一次性合并策略实现LoopMergeStrategy与OnceAbsoluteMergeStrategy在写入执行器处理表头与内容时会按注解配置生成对应的合并区域。冻结窗格FreezePaneFreezePane标注在类上用于定义工作表的冻结窗格——滚动时保持指定行列区域始终可见适合固定表头或首列。参数默认值说明colSplit0冻结窗格的水平位置左侧冻结列数rowSplit0冻结窗格的垂直位置顶部冻结行数leftmostColumn-1右窗格中可见的最左列默认等于colSplittopRow-1下窗格中可见的最上行默认等于rowSplit源码见 FreezePane.java。示例——冻结首行与首列FreezePane(colSplit 1, rowSplit 1) public class FrozenData { ExcelProperty(编号) private String id; }leftmostColumn与topRow两个可选参数用于精确控制滚动后窗格内首个可见单元格的位置日常场景通常只需指定colSplit与rowSplit即可。注解如何被读写引擎消费FesodSheet 的读写引擎通过运行时反射消费上述注解整个过程分为两步字段筛选与排序引擎读取类上的ExcelIgnoreUnannotated决定仅注解字段或全字段策略再按ExcelIgnore剔除忽略字段最终按ExcelProperty的index/order优先级构建字段映射。筛选结果以FieldCacheFieldCache.java形式缓存——sortedFieldMap保存按序排列的FieldWrapperindexFieldMap单独保存使用index属性的字段避免重复扫描并加速后续读写。按场景分发DateTimeFormat、NumberFormat交由格式化转换器在处理String接收的日期/数字单元格时生效样式类注解则在写入流程中由写处理器write handler转换为 POI 的CellStyle/Font设置合并与冻结注解分别对应合并策略与冻结窗格策略的执行。因此开发者只需维护一个实体类即可同时驱动读列映射、格式转换与写表头、样式、合并、冻结两条链路这与 FesodSheet 文档中实体类是读写操作基础的设计一致。小结与最佳实践场景推荐注解组合简单按表头读写ExcelProperty(列名)固定列序或跳过表头匹配ExcelProperty(index n)或ExcelProperty(order n)排除无关字段单个用ExcelIgnore批量白名单用类级ExcelIgnoreUnannotatedString 接收日期/数字DateTimeFormat(yyyy-MM-dd)/NumberFormat(#,##0.00)输出排版ColumnWidthHeadRowHeight/ContentRowHeight 字体与样式注解报表合并与固定表头ContentLoopMerge/OnceAbsoluteMerge/FreezePane几点实践提醒多表头读取时value只匹配最后一行表头若需精确控制应改用index样式注解中的hidden/locked仅在 sheet 受保护时生效fillForegroundColor必须先于fillBackgroundColor设置否则实心填充可能失效。本文所述注解的完整源码与单元测试可在仓库 fesod-sheet 模块的annotation目录及 fesod-sheet/src/test/java/org/apache/fesod/sheet/style 测试中进一步查阅验证。赞分享后端【免费下载链接】fesodFast. Easy. Done. Processing spreadsheets without worrying about large files causing OOM.项目地址https://gitcode.com/gh_mirrors/fast/fesod点击查看免费下载相关推荐Apache Fesod注解系统完全指南ExcelProperty、ExcelIgnore深度实战教程Apache Fesod注解系统完全指南ExcelProperty、ExcelIgnore深度实战教程 Apache Fesod作为easyexcel作者后端EasyExcel终极指南ExcelProperty注解value属性的完整解析与应用实践EasyExcel终极指南ExcelProperty注解value属性的完整解析与应用实践 在数据处理领域Excel作为最常用的办公软件其文件处理一直是J后端Apache Fesod合并策略完全指南LoopMerge与OnceAbsoluteMerge实战解析Apache Fesod合并策略完全指南LoopMerge与OnceAbsoluteMerge实战解析 Apache Fesod作为easyexcel作者最新后端上一篇社区贡献指南如何参与Qwen3.5-9B-GLM5.1-Distill-v1的改进与优化下一篇开源项目 OpenHMD 安装与使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考