fantasy-ngzorro 2.1.13 → 2.1.15

package/README.md

@@ -36,6 +36,10 @@
 | — | 2026-5-20 | 补充 hd-table、hd-detail-lines-page 等组件；完善公共子类型（SelectOption、FormItem 等）文档 |
 | — | 2026-6-23 | hd-table 状态列支持 `stateField` 自定义取值字段、`isState` 按列名取值；hd-form Input 支持 `prefix` / `prefixIcon`；hd-detail-lines-page 支持 `isCrossPageSelect` 跨页勾选开关 |
 | — | 2026-7-6 | hd-form 支持 `FormListType.Checkbox`（单个复选框 / 复选框组）及 `CheckboxOption` 配置 |
+| — | 2026-8-6 | hd-form-lines：`allowEmpty` + 仅删除按钮时初始化不补空行、可删至 0 行；分页页码删空校正；ViewDom 字号 14px |
+| — | 2026-8-21 | 分页选项统一增加 500 / 1000；`hd-table` / `hd-detail-lines` / `hd-detail-lines-page` 默认 `tablePageSize` 改为 100 |
+| — | 2026-8-25 | hd-status：`statusToColor` 按 sunan-server 业务状态枚举全量去重补充（排除银行 / AGV / HTTP StatusCode） |
+| — | 2026-8-26 | 文档补齐：`hd-form-lines` 勾选/复制/插槽/暴露方法/`allowEmpty`；分页默认值与选项；`FormLine` 字段 |
 
 ## 前言
 
@@ -48,9 +52,11 @@
 
 | 模块 | 说明 |
 | ---- | ---- |
+| `FantasyNgzorroModule` | 根模块，业务侧统一引入 |
 | `ColWidth` | 列宽常量 |
 | `Page<T>` | 分页数据结构 |
 | `Utils` | 精度计算工具 |
+| `HdOverlayCleanupService` | 清理残留 tooltip/overlay（引入模块后自动生效） |
 | `HdTableColumn` / `FormLine` / `Filter` 等 | 各组件配置类型，详见 [附录：公共配置类型](#附录公共配置类型) |
 
 ---
@@ -70,14 +76,15 @@
 | ---- | ---- | ------ | ---- |
 | type | string | default | primary \| dashed \| danger \| default \| link \| reset \| add |
 | size | string | normal | 按钮尺寸 |
-| loading | boolean | false | 加载中（与 loading 配合时必须用 clickAction） |
-| disabled | boolean | false | 是否禁用 |
+| loading | boolean | false | 加载中（与 loading 配合时必须用 clickAction / nzOnConfirm） |
+| disabled | boolean | false | 是否禁用；loading 时也会禁用 |
 | clickAction | EventEmitter | — | 点击事件 |
+| nzOnConfirm | EventEmitter | — | 确认类点击事件（与 clickAction 二选一亦可） |
 
 ### 注意点
 
 - **禁止**使用 `type="submit"`，请用普通按钮 + `clickAction` 触发表单提交。
-- 设置了 `loading` 的按钮必须用 `(clickAction)`，不能用 `(click)`。
+- 设置了 `loading` 的按钮必须用 `(clickAction)` 或 `(nzOnConfirm)`，不能用 `(click)`。
 
 ---
 
@@ -154,7 +161,20 @@
 | ---- | ---- | ---- |
 | status | string | 状态值，匹配 `hd-status.service.ts` 中 `statusToColor` 配置 |
 
-匹配时不区分大小写。新增状态请在 `statusToColor` 中配置颜色。
+匹配时**不区分大小写**。未命中时圆点默认为灰色 `#9FA4A2`。新增状态请在 `statusToColor` 中配置颜色。
+
+#### statusToColor 颜色语义
+
+| 颜色 | 含义 | 常见状态码示例 |
+| ---- | ---- | -------------- |
+| `#FAB13B` 黄 | 过程中 / 中间态 | committed、picking、receiving、待生效 |
+| `#9FA4A2` 灰 | 初始 / 未开始 / 线下停用 | initial、saved、未审核、已保存、OFF_LINE |
+| `#F5222D` 红 | 作废 / 拒绝 / 失效 / 禁用 | aborted、rejected、INVALID、已作废 |
+| `#3B77E3` 蓝 | 审核流转 / 处理中 | audited、submitted、处理中、已初审 |
+| `#20B95D` 绿 | 完成 / 启用 / 生效 | finished、published、EFFECTIVE、已完成 |
+| `#F05B24` 橙 | 部分完成 / 预警 | partPublished、部分核销、willExpired |
+
+状态码已按 sunan-server 业务 `*State` / `*Status` 枚举全量去重补齐（排除银行支付 / AGV / HTTP StatusCode）。同时支持英文码、`SCREAMING_SNAKE` 与中文枚举名。
 
 ---
 
@@ -244,12 +264,16 @@ search(reset = false) {
 | tablePageSize | number | 10 | 每页条数（双向绑定） |
 | tableLoading | boolean | false | 加载状态 |
 | tableSearchEvent | EventEmitter | — | 翻页 / 改 pageSize 触发，参数 reset 表示是否重置到第一页 |
-| scroll | object | { x: '1150px' } | 横向滚动 |
+| scroll | object | { x: '1px' } | 横向滚动 |
 | showSelected | boolean | false | 是否显示勾选列 |
 | selectField | string | billNumber | 勾选主键字段 |
 | selectEvent | EventEmitter | — | 勾选变化 |
+| showTableTotal | boolean | false | 底部合计行 |
+| tableTotalOption | TableTotalOption[] | — | 合计配置（已弃用类型） |
 | tableHead / tableBody / tableTotal | TemplateRef | — | 表头 / 表体 / 顶部合计插槽 |
 
+分页可选条数：`10 / 50 / 100 / 200 / 500 / 1000`。
+
 ---
 
 ## 9、增强表格（hd-table）
@@ -307,12 +331,16 @@ tableCols: HdTableColumn[] = [{
 | ---- | ---- | ------ | ---- |
 | tableCols | HdTableColumn[] | [] | 列配置 |
 | tableData | Page\<any\> | — | 分页数据 |
-| tablePageIndex / tablePageSize | number | — | 分页（双向绑定） |
+| tablePageIndex | number | 1 | 当前页（双向绑定） |
+| tablePageSize | number | 100 | 每页条数（双向绑定）；外面传入会覆盖默认值 |
 | tableLoading | boolean | false | 加载状态 |
 | tableSearchEvent | EventEmitter | — | 翻页查询 |
+| tablePageSizeChange | EventEmitter | — | pageSize 双向绑定同步 |
+| tablePageSizeChangeEvent | EventEmitter | — | pageSize 变化（含缓存恢复），常用于重新查询 |
 | sortEvent | EventEmitter | — | 排序 |
 | selectEvent | EventEmitter | — | 勾选变化 |
 | showSelected | boolean | false | 勾选列 |
+| selectField | string | billNumber | 勾选主键字段 |
 | showOperateColWarpButton | boolean | false | 展开/缩略显示换行列 |
 | showTableTotal | boolean | false | 底部合计行 |
 | tableTotalOption | HdTableTotalOption[] | — | 合计配置 |
@@ -321,6 +349,8 @@ tableCols: HdTableColumn[] = [{
 | uuid | string | — | 列缓存唯一标识（必填，用于 IndexedDB 缓存） |
 | tableLeftButton / tableRightButton / tableTotal | TemplateRef | — | 工具栏插槽 |
 
+分页可选条数：`10 / 50 / 100 / 200 / 500 / 1000`。若本地缓存过该表 `pageSize` 且 `> 10`，初始化会优先使用缓存值并回写父组件。
+
 #### HdTableColumn 配置
 
 列定义见 [HdTableColumn](#hdtablecolumn表格列)、[OperateBtn](#operatebtn操作列按钮)、[HdTableTotalOption](#hdtabletotaloptionhd-table-底部合计)。
@@ -404,46 +434,85 @@ formChangeEvent(validateForm: FormGroup) {
 
 ## 11、明细表单（hd-form-lines）
 
-可编辑的明细行表格，支持键盘导航、行内搜索、合计等。
+可编辑的明细行表格，支持键盘导航、行内搜索、勾选批量填充、合计等。
 
 ### 示例
 
 ```html
-<hd-form-lines #hdFormLines showSearch showKeyboardOperateTip
+<hd-form-lines #hdFormLines showSearch showCheckbox showKeyboardOperateTip
   [formLines]="formLines" [formLinesData]="formLinesData"
-  [operateButtons]="['add', 'delete']" [allowEmpty]="false"
-  (changeEvent)="formLinesChangeEvent($event)">
+  [operateButtons]="['add', 'copy', 'delete']" [allowEmpty]="false"
+  (changeEvent)="formLinesChangeEvent($event)"
+  (selectionChange)="formLinesSelectionChange($event)"
+  (deleteLastLineEvent)="deleteEvent()">
+  <ng-template #formLinesLeftButton>
+    <hd-button type="primary" (clickAction)="batchFill()">批量填充</hd-button>
+  </ng-template>
+  <ng-template #formLinesRightButton>
+    <hd-button type="default">右侧操作</hd-button>
+  </ng-template>
+  <ng-template #ViewDomRightTemplate let-formItem="formItem" let-formLine="formLine">
+    <!-- ViewDom 列右侧自定义内容 -->
+  </ng-template>
 </hd-form-lines>
 ```
 
 | 参数 | 类型 | 默认值 | 说明 |
 | ---- | ---- | ------ | ---- |
 | formLines | FormLine[] | — | 列定义 |
-| formLinesData | any[] | — | 行数据 |
-| operateButtons | string[] | ['add','delete'] | 操作按钮 |
+| formLinesData | any[] | — | 行数据；空数组视为新增 |
+| operateButtons | string[] | ['add','delete'] | 操作按钮：`add` / `copy` / `delete` |
 | showDeleteConfirm | boolean | false | 删除前确认 |
 | showSearch | boolean | false | 行内搜索 |
+| showCheckbox | boolean | false | 行勾选列（用于批量操作） |
 | showKeyboardOperateTip | boolean | false | 键盘操作提示 |
 | showLineNumber | boolean | true | 序号列 |
-| allowEmpty | boolean | true | 是否允许空表 |
+| tableLoading | boolean | false | 加载状态 |
+| allowEmpty | boolean | true | 是否允许空表（见下方说明） |
 | showTotal | boolean | false | 合计行 |
 | totalOption / columnsNumber | — | — | 合计配置 |
 | scroll | object | { x: '1px' } | 横向滚动 |
 | changeEvent | EventEmitter | — | 表单变化 |
-| deleteLastLineEvent | EventEmitter | — | 删除最后一行 |
+| selectionChange | EventEmitter\<FormGroup[]\> | — | 勾选变化 |
+| deleteLastLineEvent | EventEmitter | — | `allowEmpty=false` 时删除最后一行 |
+| deleteLineEvent | EventEmitter | — | 删除行事件 |
 
-#### FormLine 配置
+### 插槽
 
-明细列使用 [FormLine](#formline明细表单项) 类型，含 [ColorOption](#coloroption)、[ExplainOption](#explainoption) 及表格型 [SelectOption](#selectoption下拉选项配置)。
+| 插槽 | 说明 |
+| ---- | ---- |
+| formLinesLeftButton | 工具栏左侧自定义按钮（同 hd-table 的 tableLeftButton） |
+| formLinesRightButton | 工具栏右侧自定义按钮 |
+| ViewDomRightTemplate | ViewDom 列右侧自定义模板，上下文：`formItem`、`formLine` |
 
----
+### allowEmpty 行为
+
+| 场景 | 行为 |
+| ---- | ---- |
+| `allowEmpty=false` | 不能删掉最后一行，触发 `deleteLastLineEvent` |
+| `allowEmpty=true` 且操作列含 add/copy | 删空后会自动补一行空行 |
+| `allowEmpty=true` 且操作列**仅有** `delete` | 初始化空数据不补空行；可删至 0 行；外部可通过 `addFormLine()` 新增 |
+
+### FormLine 配置
+
+明细列使用 [FormLine](#formline明细表单项) 类型，含 [ColorOption](#coloroption)、[ExplainOption](#explainoption) 及表格型 [SelectOption](#selectoption下拉选项配置)。
 
 开启 `showKeyboardOperateTip` 后支持 `[↑][↓][←][→]`、`Enter` 在单元格间跳转；InputNumber 上下键用于跳转，不触发 step 增减。
 
+表格分页可选条数：`10 / 50 / 100 / 200 / 500 / 1000`。
+
 #### 暴露方法
 
 ```typescript
-this.hdFormLines.getValid(); // 获取整表校验状态
+this.hdFormLines.getValid();              // 整表校验状态
+this.hdFormLines.getLines();              // 获取行 FormArray
+this.hdFormLines.addFormLine();           // 末尾新增空行（也可传当前行在其后插入）
+this.hdFormLines.resetForm();             // 重置表单
+this.hdFormLines.getSelectedLines();      // 当前勾选行 FormGroup[]
+this.hdFormLines.getSelectedLinesData();  // 勾选行数据（含跨页）
+this.hdFormLines.getSelectedCount();      // 勾选数量
+this.hdFormLines.clearSelection();        // 清空勾选
+this.hdFormLines.batchFillSelected({ remark: '批量备注' }); // 批量填充勾选行字段
 ```
 
 ---
@@ -516,6 +585,7 @@ formCols: HdOption[] = [
 | showSearch | boolean | false | 行内搜索 |
 | searchFields | string[] | [] | 搜索字段，空则搜全部字段 |
 | hdFrontPagination | boolean | false | 前端分页 |
+| tablePageSize | number | 100 | 每页条数（开启前端分页时生效） |
 | showSelected | boolean | false | 勾选 |
 | selectField | string | billNumber | 勾选主键 |
 | selectedField | string | — | 初始勾选标记字段 |
@@ -526,6 +596,8 @@ formCols: HdOption[] = [
 | totalOption | TotalOption[] | — | 合计配置，见 [TotalOption](#totaloption明细合计行) |
 | detailLineHead / detailLineBody | TemplateRef | — | 表头 / 表体插槽 |
 
+分页可选条数：`10 / 50 / 100 / 200 / 500 / 1000`。
+
 ---
 
 ## 15、详情明细-服务端分页（hd-detail-lines-page）
@@ -559,7 +631,7 @@ formCols: HdOption[] = [
 ```typescript
 detailLinesPageData: Page<any> = new Page();
 detailLinesPageIndex = 1;
-detailLinesPageSize = 5;
+detailLinesPageSize = 100;
 detailLinesPageLoading = false;
 
 loadDetailLinesPage(reset = false) {
@@ -589,7 +661,8 @@ onDetailLinesPageSizeChange(pageSize: number) {
 | ---- | ---- | ------ | ---- |
 | lines | any[] | [] | 当前页数据（也可用 tableData.content） |
 | tableData | Page\<any\> | — | 分页对象，提供 totalElements |
-| tablePageIndex / tablePageSize | number | 1 / 10 | 分页 |
+| tablePageIndex | number | 1 | 当前页 |
+| tablePageSize | number | 100 | 每页条数 |
 | tableLoading | boolean | false | 加载状态 |
 | tablePageIndexChange | EventEmitter | — | 页码变化 |
 | tablePageSizeChange | EventEmitter | — | 每页条数变化（组件内会重置到第 1 页） |
@@ -597,7 +670,7 @@ onDetailLinesPageSizeChange(pageSize: number) {
 | showSelected / allowDrop / showTotal 等 | — | — | 同 hd-detail-lines |
 | isCrossPageSelect | boolean | — | 跨页勾选 |
 
-模板中 `index` 为**全局序号**：`(pageIndex - 1) * pageSize + 行号`。
+分页可选条数：`10 / 50 / 100 / 200 / 500 / 1000`。模板中 `index` 为**全局序号**：`(pageIndex - 1) * pageSize + 行号`。
 
 ### 与 hd-detail-lines 选型
 
@@ -811,17 +884,28 @@ selectOption: {
 | 参数 | 类型 | 默认值 | 说明 |
 | ---- | ---- | ------ | ---- |
 | type | FormLineType | — | 控件类型 |
-| align | string | — | 列对齐 |
-| hideViewDomValue | boolean | false | ViewDom 隐藏 value |
+| align | string | — | 列对齐 left \| right \| center |
+| hideViewDomValue | boolean | false | ViewDom 隐藏 value（如只显示图片） |
 | isSelect | boolean | — | 聚焦后全选内容 |
 | preserveNumber | number | — | ViewDom 小数位 |
+| maxLength | number | — | Input 最大长度 |
 | disabled | boolean | — | 是否禁用 |
+| showTime | boolean | false | Date 是否含时间 |
+| hdShowToday | boolean | true | Date 是否显示「今天」按钮 |
+| hdDisabledDate | Function | — | 不可选日期 |
 | style | object | — | 列样式 |
 | canSearch | boolean | false | hide 字段参与搜索 |
-| explainOption / explainOptionRight | ExplainOption | — | 说明文字 |
+| defaultLabel | any | — | Select 未初始化时的默认展示文案 |
+| explainOption / explainOptionRight | ExplainOption | — | 说明文字（左 / 右） |
 | colorOption | ColorOption | — | 动态颜色 |
 | selectOption | SelectOption | — | 含 tableColumns 表格下拉 |
-| onChangeEventDebounceTime | number | — | change 防抖（ms） |
+| inputNumber | InputNumber | — | 数字框配置 |
+| onChangeEvent | Function | — | 值变化，签名见下 |
+| onSearchEvent | Function | — | 下拉搜索 |
+| onOpenChangeEvent | Function | — | 下拉展开/收起，回调 `(open, line)`，可按行请求 selectList |
+| onChangeEventDebounceTime | number | — | change 防抖（ms），未配置或 0 为同步 |
+| onSearchEventEventDebounceTime | number | — | search 防抖（ms） |
+| onOpenChangeEventDebounceTime | number | — | openChange 防抖（ms） |
 
 #### FormLineType 枚举
 
@@ -840,6 +924,7 @@ selectOption: {
 ```typescript
 onChangeEvent: (value, line: FormGroup) => void
 onSearchEvent: (keyword, line?: FormGroup) => void
+onOpenChangeEvent: (open: boolean, line: FormGroup) => void
 ```
 
 ### HdTableColumn（表格列）