Skip to content

docs: add documentation for the annotations on the website #793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
delei merged 8 commits into from
Jan 16, 2026
Merged

docs: add documentation for the annotations on the website #793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
414c0f9
docs: add documentation for annotations
bengbengbalabalabeng Jan 12, 2026
1bcf9d7
docs: unified parameter header description
bengbengbalabalabeng Jan 12, 2026
725ea73
docs: replace non-essential English in zh-CN version
bengbengbalabalabeng Jan 12, 2026
636afe2
Merge branch 'main' into add-annotation-introduction
delei Jan 12, 2026
9ac8045
docs: fix MD047/single-trailing-newline
bengbengbalabalabeng Jan 13, 2026
1fe8d51
Merge branch 'add-annotation-introduction' of https://github.com/beng…
bengbengbalabalabeng Jan 13, 2026
6965992
Merge branch 'main' into add-annotation-introduction
bengbengbalabalabeng Jan 15, 2026
061f9f6
Merge branch 'main' into add-annotation-introduction
delei Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions website/docs/sheet/help/annotation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,78 @@ Number conversion, using `String` to receive data in spreadsheet number format w
### `@ColumnWidth`

Specifies the column width.

### `@HeadRowHeight` & `@ContentRowHeight`

Specifies the height of the header rows (`@HeadRowHeight`) or the content rows (`@ContentRowHeight`). The
parameters are as follows:

| Name | Default Value | Description |
|-------|---------------|----------------------------------------------------------|
| value | -1 | Set the height. `-1` indicates automatic height setting. |

### `@HeadFontStyle` & `@ContentFontStyle`

Customizes the font style for headers (`@HeadFontStyle`) or content data (`@ContentFontStyle`). The
parameters are as follows:

| Name | Default Value | Description |
|--------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| fontName | Empty | The name for the font (e.g., "Arial"). |
| fontHeightInPoints | -1 | Set font height. |
| italic | BooleanEnum.DEFAULT | Whether to use italics. |
| strikeout | BooleanEnum.DEFAULT | Whether to use a strikeout horizontal line through the text. |
| color | -1 | The color for the font. (See `org.apache.poi.ss.usermodel.IndexedColors` or `org.apache.poi.ss.usermodel.Font`, e.g., `Font.COLOR_NORMAL`). |
| typeOffset | -1 | Set the font type offset to normal, super, or subscript (See `org.apache.poi.ss.usermodel.Font`, e.g., `Font.SS_NONE`). |
| underline | -1 | Set type of text underlining (See `org.apache.poi.ss.usermodel.Font`, e.g., `Font.U_SINGLE`). |
| charset | -1 | Set character-set to use (See `org.apache.poi.common.usermodel.fonts.FontCharset` or `org.apache.poi.ss.usermodel.Font`, e.g., `Font.ANSI_CHARSET`). |
| bold | BooleanEnum.DEFAULT | Whether to apply bold style. |

### `@HeadStyle` & `@ContentStyle`

Customizes the cell style (borders, alignment, colors...) for header data (`@HeadStyle`) or content data (`@ContentStyle`).
The parameters are as follows:

| Name | Default Value | Description |
|---------------------|---------------------------------|-------------------------------------------------------------------------------------------------------|
| dataFormat | -1 | Set the data format (must be a valid format defined at `org.apache.poi.ss.usermodel.BuiltinFormats`). |
| hidden | BooleanEnum.DEFAULT | set the cell to be hidden. **Note: This only takes effect if the sheet is protected.** |
| locked | BooleanEnum.DEFAULT | Set the cell to be locked. **Note: This only takes effect if the sheet is protected.** |
| quotePrefix | BooleanEnum.DEFAULT | Turn on/off "Quote Prefix" (treats numeric/formula as text). |
| horizontalAlignment | HorizontalAlignmentEnum.DEFAULT | Set the horizontal alignment. |
| wrapped | BooleanEnum.DEFAULT | Set whether the text should be wrapped within the cell. |
| verticalAlignment | VerticalAlignmentEnum.DEFAULT | Set the vertical alignment. |
| rotation | -1 | Set the degree of rotation for the text. |
| indent | -1 | Set the number of spaces to indent the text. |
| borderLeft | BorderStyleEnum.DEFAULT | Set the border style for the left border. |
| borderRight | BorderStyleEnum.DEFAULT | Set the border style for the right border. |
| borderTop | BorderStyleEnum.DEFAULT | Set the border style for the top border. |
| borderBottom | BorderStyleEnum.DEFAULT | Set the border style for the bottom border. |
| leftBorderColor | -1 | Set the color for the left border (See `org.apache.poi.ss.usermodel.IndexedColors`). |
| rightBorderColor | -1 | Set the color for the right border (See `org.apache.poi.ss.usermodel.IndexedColors`). |
| topBorderColor | -1 | Set the color for the top border (See `org.apache.poi.ss.usermodel.IndexedColors`). |
| bottomBorderColor | -1 | Set the color for the bottom border (See `org.apache.poi.ss.usermodel.IndexedColors`). |
| fillPatternType | FillPatternTypeEnum.DEFAULT | Set the fill pattern |
| fillBackgroundColor | -1 | Set the background fill color. |
| fillForegroundColor | -1 | Set the foreground fill color. **Note: Ensure Foreground color is set prior to background color.** |
| shrinkToFit | BooleanEnum.DEFAULT | Controls if the Cell should be auto-sized to shrink to fit if text is too long. |

### `@ContentLoopMerge`

Defines a loop merge strategy for content cells. The parameters are as follows:

| Name | Default Value | Description |
|--------------|---------------|---------------------------------------------------|
| eachRow | 1 | The number of rows to include in each merge loop. |
| columnExtend | 1 | The number of columns to extend the merge. |

### `@OnceAbsoluteMerge`

Defines a one-time absolute merge region. The parameters are as follows:

| Name | Default Value | Description |
|------------------|---------------|----------------------------------------------|
| firstRowIndex | -1 | The index of the first row to merge. |
| lastRowIndex | -1 | The index of the last row to merge. |
| firstColumnIndex | -1 | The index of the first column to merge. |
| lastColumnIndex | -1 | The index of the last column to merge. |
76 changes: 74 additions & 2 deletions website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/annotation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ title: '注解'

| 名称 | 默认值 | 描述 |
|-----------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| value | 空 | 用于匹配电子表格中的头，必须全匹配,如果有多行头，会匹配最后一行头 |
| value | 空 | 用于匹配电子表格中的头，必须全匹配，如果有多行头，会匹配最后一行头 |
| order | Integer.MAX_VALUE | 优先级高于 `value`，会根据 `order` 的顺序来匹配实体和电子表格中数据的顺序 |
| index | -1 | 优先级高于 `value` 和 `order`，会根据 `index` 直接指定到电子表格中具体的哪一列 |
| converter | 自动选择 | 指定当前字段用什么转换器，默认会自动选择。读的情况下只要实现 `org.apache.fesod.sheet.converters.Converter#convertToJavaData(org.apache.fesod.sheet.converters.ReadConverterContext<?>)` 方法即可 |
Expand All @@ -32,7 +32,7 @@ title: '注解'

### **`@DateTimeFormat`**

日期转换，用 `String` 去接收电子表格日期格式的数据会调用这个注解,参数如下：
日期转换，用 `String` 去接收电子表格日期格式的数据会调用这个注解，参数如下：

| 名称 | 默认值 | 描述 |
|------------------|------|--------------------------------------------------------------------|
Expand All @@ -51,3 +51,75 @@ title: '注解'
### **`@ColumnWidth`**

指定列宽。

### `@HeadRowHeight` & `@ContentRowHeight`

指定表头行（`@HeadRowHeight`）或内容行（`@ContentRowHeight`）的高度。具体参数如下：

| 名称 | 默认值 | 描述 |
|-------|-----|--------------------|
| value | -1 | 设置高度。`-1` 表示自动设置高度 |

### `@HeadFontStyle` & `@ContentFontStyle`

自定义表头（`@HeadFontStyle`）或内容数据（`@ContentFontStyle`）的字体样式。具体参数如下：

| 名称 | 默认值 | 描述 |
|--------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------|
| fontName | 空 | 字体名称（例如 "Arial"） |
| fontHeightInPoints | -1 | 设置字体高度 |
| italic | BooleanEnum.DEFAULT | 是否使用斜体 |
| strikeout | BooleanEnum.DEFAULT | 文本是否显示水平删除线 |
| color | -1 | 设置字体颜色（参照 `org.apache.poi.ss.usermodel.IndexedColors` 或 `org.apache.poi.ss.usermodel.Font`，例如 `Font.COLOR_NORMAL`） |
| typeOffset | -1 | 设置字体的类型偏移，用于控制文本显示为正常、上标或下标（参照 `org.apache.poi.ss.usermodel.Font`，例如 `Font.SS_NONE`） |
| underline | -1 | 设置下划线类型（参照 `org.apache.poi.ss.usermodel.Font`，例如 `Font.U_SINGLE`） |
| charset | -1 | 设置字符集（参照 `org.apache.poi.common.usermodel.fonts.FontCharset` 或 `org.apache.poi.ss.usermodel.Font`，例如 `Font.ANSI_CHARSET`） |
| bold | BooleanEnum.DEFAULT | 是否加粗 |

### `@HeadStyle` & `@ContentStyle`

自定义表头数据（`@HeadStyle`）或内容数据（`@ContentStyle`）的单元格样式（边框、对齐、颜色等）。具体参数如下：

| 名称 | 默认值 | 描述 |
|---------------------|---------------------------------|-------------------------------------------------------------------|
| dataFormat | -1 | 设置数据格式（必须是 `org.apache.poi.ss.usermodel.BuiltinFormats` 中定义的有效格式） |
| hidden | BooleanEnum.DEFAULT | 设置单元格为隐藏，**注意：此选项仅在工作表受保护时生效** |
| locked | BooleanEnum.DEFAULT | 设置单元格为锁定，**注意：此选项仅在工作表受保护时生效。** |
| quotePrefix | BooleanEnum.DEFAULT | 开启/关闭前缀引号（将看起来像数字或公式的内容视为文本处理） |
| horizontalAlignment | HorizontalAlignmentEnum.DEFAULT | 设置水平对齐方式 |
| wrapped | BooleanEnum.DEFAULT | 设置文本是否在单元格内自动换行 |
| verticalAlignment | VerticalAlignmentEnum.DEFAULT | 设置垂直对齐方式 |
| rotation | -1 | 设置文本的旋转角度 |
| indent | -1 | 设置文本缩进的空格数 |
| borderLeft | BorderStyleEnum.DEFAULT | 设置左边框的样式 |
| borderRight | BorderStyleEnum.DEFAULT | 设置右边框的样式 |
| borderTop | BorderStyleEnum.DEFAULT | 设置上边框的样式 |
| borderBottom | BorderStyleEnum.DEFAULT | 设置下边框的样式 |
| leftBorderColor | -1 | 设置左边框的颜色（参照 `org.apache.poi.ss.usermodel.IndexedColors`） |
| rightBorderColor | -1 | 设置右边框的颜色（参照 `org.apache.poi.ss.usermodel.IndexedColors`） |
| topBorderColor | -1 | 设置上边框的颜色（参照 `org.apache.poi.ss.usermodel.IndexedColors`） |
| bottomBorderColor | -1 | 设置下边框的颜色（参照 `org.apache.poi.ss.usermodel.IndexedColors`） |
| fillPatternType | FillPatternTypeEnum.DEFAULT | 设置填充图案类型 |
| fillBackgroundColor | -1 | 设置背景填充颜色 |
| fillForegroundColor | -1 | 设置前景填充颜色，**注意：请确保在设置背景色之前设置前景色** |
| shrinkToFit | BooleanEnum.DEFAULT | 控制单元格是否自动缩小以适应过长的文本 |

### `@ContentLoopMerge`

定义内容单元格的循环合并策略。具体参数如下：

| 名称 | 默认值 | 描述 |
|--------------|-----|-------------|
| eachRow | 1 | 每次合并循环包含的行数 |
| columnExtend | 1 | 合并需要延伸的列数 |

### `@OnceAbsoluteMerge`

定义一次性的单元格合并区域。具体参数如下：

| 名称 | 默认值 | 描述 |
|------------------|-----|-------------|
| firstRowIndex | -1 | 合并区域的第一行索引 |
| lastRowIndex | -1 | 合并区域的最后一行索引 |
| firstColumnIndex | -1 | 合并区域的第一列索引 |
| lastColumnIndex | -1 | 合并区域的最后一列索引 |
Loading