fantasy-ngzorro 2.1.0 → 2.1.2

package/README.md

@@ -2,382 +2,453 @@
 
 # Fantasy-Ngzorro
 
-## 更新记录
-
-| 更新人 | 更新时间  | 更新内容                                                     |
-| ------ | --------- | ------------------------------------------------------------ |
-| MC     | 2023-2-10 | 1、Readme文件目录结构创建 <br/>2、新增按钮、按钮组、通用表格、筛选器、状态、详情头、详情单头、详情明细相关文档。 |
-| MC     | 2023-2-13 | 1、新增表单、明细表单、间隔、小标题相关文档<br/>2、所有组件字段增加必填选项。 |
-|        |           |                                                              |
+基于 **Angular 8** + **ng-zorro-antd 8.5.x** 的业务组件库，封装按钮、表格、表单、详情页等常用 UI 模式。
+
+## 组件一览
+
+| 序号 | 选择器 | 说明 |
+| ---- | ------ | ---- |
+| 1 | `hd-button` | 按钮 |
+| 2 | `hd-button-group` | 按钮组（左右布局） |
+| 3 | `hd-space` | 间隔占位 |
+| 4 | `hd-tip` | 小标题 |
+| 5 | `hd-status` | 状态标签 |
+| 6 | `hd-popconfirm` | 气泡确认框 |
+| 7 | `hd-filter` | 筛选器 |
+| 8 | `hd-current-table` | 通用表格（自定义列模板） |
+| 9 | `hd-table` | 增强表格（列配置、排序、列缓存） |
+| 10 | `hd-form` | 表单 |
+| 11 | `hd-form-lines` | 明细表单（可编辑表格） |
+| 12 | `hd-detail-tip` | 详情头 |
+| 13 | `hd-detail-form` | 详情单头 |
+| 14 | `hd-detail-lines` | 详情明细（前端分页 / 搜索） |
+| 15 | `hd-detail-lines-page` | 详情明细（服务端分页） |
+| 16 | `hd-log` | 操作日志 |
+
+> 配置类型（SelectOption、FormItem、HdTableColumn 等）见 [附录：公共配置类型](#附录公共配置类型)。
 
+## 更新记录
 
+| 更新人 | 更新时间 | 更新内容 |
+| ------ | -------- | -------- |
+| MC | 2023-2-10 | Readme 创建；按钮、按钮组、通用表格、筛选器、状态、详情头、详情单头、详情明细文档 |
+| MC | 2023-2-13 | 表单、明细表单、间隔、小标题文档；组件字段增加必填说明 |
+| — | 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` 配置 |
 
 ## 前言
 
-> 1、文档中的插槽概念借用vue中的插槽，在angular里面体现出来就是模板 #template。
->
-> 2、事件传递建议使用bind(this)绑定自定义的函数去实现方法, 而不是箭头函数。示例：onChangeEvent: this.formInputChange.bind(this)
->
-> 3、运行本地服务之后，访问demo路由即可查看具体交互
-
+> 1. 文档中的「插槽」对应 Angular 的模板 `#template`（`ng-template` + `@ContentChild`）。
+> 2. 事件回调建议使用 `bind(this)`，示例：`onChangeEvent: this.formInputChange.bind(this)`。
+> 3. 本地运行 `npm start`，访问 `http://localhost:13000` 查看 Demo 交互。
+> 4. 业务模块引入：`import { FantasyNgzorroModule } from 'fantasy-ngzorro'`。
 
+### 公共导出
 
-## 1、按钮(hd-button)
+| 模块 | 说明 |
+| ---- | ---- |
+| `ColWidth` | 列宽常量 |
+| `Page<T>` | 分页数据结构 |
+| `Utils` | 精度计算工具 |
+| `HdTableColumn` / `FormLine` / `Filter` 等 | 各组件配置类型，详见 [附录：公共配置类型](#附录公共配置类型) |
 
-### 效果图
+---
 
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-button.png)
+## 1、按钮（hd-button）
 
 ### 示例
 
 ```html
-<hd-button type="primary">查询</hd-button>
+<hd-button type="primary" (clickAction)="search()">查询</hd-button>
+<hd-button type="default" [loading]="loading" (clickAction)="save()">保存</hd-button>
 ```
 
-### 说明
+### 参数
 
-| 参数     | 类型   | 默认值  | 说明                                                         |
-| -------- | ------ | ------- | ------------------------------------------------------------ |
-| loading  | boolen | false   | 加载中                                                       |
-| type     | string | default | primary \| dashed \| danger \| default \| link \| submit \| reset \| add (其中add类型会默认增加加号) |
-| disabled | boolen | False   | 按钮是否禁用                                                 |
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| type | string | default | primary \| dashed \| danger \| default \| link \| reset \| add |
+| size | string | normal | 按钮尺寸 |
+| loading | boolean | false | 加载中（与 loading 配合时必须用 clickAction） |
+| disabled | boolean | false | 是否禁用 |
+| clickAction | EventEmitter | — | 点击事件 |
 
 ### 注意点
 
-- 为防止回车触发表单提交事件，禁止使用submit类型的按钮，请使用普通按钮+click事件触发表单提交!
-
-
-
-## 2、按钮组(hd-button-group)
+- **禁止**使用 `type="submit"`，请用普通按钮 + `clickAction` 触发表单提交。
+- 设置了 `loading` 的按钮必须用 `(clickAction)`，不能用 `(click)`。
 
-### 效果图
+---
 
-![hd-button-group](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-button-group.png)
+## 2、按钮组（hd-button-group）
 
 ### 示例
 
 ```html
 <hd-button-group>
   <ng-template #buttonGroupLeft>
-    <hd-button type="add">add</hd-button>
-    <hd-button type="default">default</hd-button>
-    <hd-button type="default">default</hd-button>
-    <hd-button type="default">default</hd-button>
+    <hd-button type="add">新增</hd-button>
   </ng-template>
   <ng-template #buttonGroupRight>
-    <hd-button type="default">default</hd-button>
+    <hd-button type="default">导出</hd-button>
   </ng-template>
 </hd-button-group>
 ```
 
-### 说明
+### 插槽
 
-| 参数             | 类型                            | 说明           |
-| ---------------- | ------------------------------- | -------------- |
-| buttonGroupLeft  | @ContentChild TemplateRef<void> | 按钮组左侧插槽 |
-| buttonGroupRight | @ContentChild TemplateRef<void> | 按钮组右侧插槽 |
+| 插槽 | 说明 |
+| ---- | ---- |
+| buttonGroupLeft | 左侧按钮区 |
+| buttonGroupRight | 右侧按钮区 |
 
-### 注意点
+按钮间距自动 12px。
+
+---
 
-- hd-button-group中的按钮会自动增加间距12px
+## 3、间隔（hd-space）
 
+### 示例
 
+```html
+<hd-space background="#fff" type="row" size="12"></hd-space>
+```
 
-## 3、通用表格(hd-current-table)
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| background | string | inherit | 背景色 |
+| type | string | row | row \| column |
+| size | number | — | 高度或宽度（px） |
 
-### 效果图
+---
 
-![hd-current-table](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-current-table.png)
+## 4、小标题（hd-tip）
 
 ### 示例
 
 ```html
-<hd-current-table #hdCurrentTable [(tablePageIndex)]="pageIndex" [(tablePageSize)]="pageSize" [scroll]="{x: '600px'}" [tableData]="page" (tableSearchEvent)="search($event)" showSelected selectField="billNumber" (selectEvent)="selectResult($event)">
-  <ng-template #tableTotal>
-    <nz-alert nzType="info" [nzMessage]="nzAlertTotal" nzShowIcon></nz-alert>
-    <ng-template #nzAlertTotal>
-      <span>已选择{{ tableSelectList.length }}项服务</span>&nbsp;&nbsp;
-      <span>调用总计：36.4万</span>&nbsp;&nbsp;
-      <span class="common-btn-group">
-        <a (click)="hdCurrentTable.resetStatus()">清空</a>
-      </span>
-    </ng-template>
-  </ng-template>
+<hd-tip title="基本信息" [fontSize]="14"></hd-tip>
+<hd-tip title="新增" [showIcon]="false" [fontSize]="16"></hd-tip>
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| title | string | — | 标题文案 |
+| showIcon | boolean | true | 是否显示左侧竖线 |
+| fontSize | number | — | 字体大小 |
+
+---
+
+## 5、状态（hd-status）
+
+### 示例
+
+```html
+<hd-status status="initial">未审核</hd-status>
+<hd-status status="audited">已审核</hd-status>
+<hd-status status="received">已收货</hd-status>
+```
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| status | string | 状态值，匹配 `hd-status.service.ts` 中 `statusToColor` 配置 |
+
+匹配时不区分大小写。新增状态请在 `statusToColor` 中配置颜色。
+
+---
+
+## 6、气泡确认（hd-popconfirm）
+
+### 示例
+
+```html
+<hd-popconfirm message="确认删除该记录吗？" (confirmOption)="onConfirm()" (cancelOption)="onCancel()">
+</hd-popconfirm>
+```
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| message | string | 提示文案 |
+| confirmOption | EventEmitter | 点击确认 |
+| cancelOption | EventEmitter | 点击取消 |
+
+---
+
+## 7、筛选器（hd-filter）
+
+### 示例
+
+```html
+<hd-filter [filterList]="filterList" (searchEvent)="filterChange($event)" (resetEvent)="resetFilterChange($event)">
+</hd-filter>
+```
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| filterList | Array\<Filter\> | 筛选项配置 |
+| searchEvent | EventEmitter | 查询，带回筛选数据 |
+| resetEvent | EventEmitter | 重置 |
+
+#### Filter 配置
+
+筛选项使用 [Filter](#filter筛选项) 类型，下拉/数字/级联等子配置见 [SelectOption](#selectoption下拉选项配置)、[InputNumber](#inputnumber数字输入配置)、[CascaderOption](#cascaderoption级联选择配置)。
+
+---
+
+## 8、通用表格（hd-current-table）(已废弃、禁用)
+
+适用于**完全自定义**表头、表体模板的列表页。
+
+### 示例
+
+```html
+<hd-current-table #hdCurrentTable [(tablePageIndex)]="pageIndex" [(tablePageSize)]="pageSize"
+  [scroll]="{x: '600px'}" [tableData]="page" [tableLoading]="loading"
+  (tableSearchEvent)="search($event)" showSelected selectField="billNumber"
+  (selectEvent)="selectResult($event)">
+  <ng-template #tableTotal>...</ng-template>
   <ng-template #tableHead>
-    <th nzLeft="40px" style="width: 100px">配送单号</th>
-    <th>收货日期</th>
+    <th>配送单号</th>
     <th>状态</th>
-    <th nzRight="0px">操作</th>
   </ng-template>
   <ng-template #tableBody let-data>
-    <!-- 父页面自己的样式，不允许用行内样式，全都定义class写到css文件中，颜色、字号等属性用通用文件中的变量，不允许直接写颜色值 -->
-    <td nzLeft="40px" style="width: 100px" class="common-billNumber"><a>{{ data.billNumber || '&lt;空&gt;' }}</a></td>
-    <td>{{ data.distDate || '&lt;空&gt;' }}</td>
-    <td>
-      <hd-status [status]="'initial'">未审核</hd-status>
-    </td>
-    <td nzRight="0px" style="width: 200px">
-      <span class="common-btn-group">
-        <a>复制</a>
-        <a>修改详情</a>
-        <a>修改日期</a>
-        <a class="common-danger-btn">删除</a>
-      </span>
-    </td>
+    <td>{{ data.billNumber }}</td>
+    <td><hd-status [status]="data.state">{{ data.stateText }}</hd-status></td>
   </ng-template>
 </hd-current-table>
 ```
 
-```tsx
-// 通用表格的相关变量
-page: Page<any> = new Page<any>();
+```typescript
+page: Page<any> = new Page();
 pageIndex = 1;
 pageSize = 10;
-loading: boolean = false;
-tableSelectList: Array<any> = [];
-
-// 表格的查询事件
-search(reset: boolean = false): void {
-  if (reset) {
-    this.pageIndex = 1;
-  }
+loading = false;
 
+search(reset = false) {
+  if (reset) { this.pageIndex = 1; }
   this.queryFilter.pageNumber = this.pageIndex - 1;
   this.queryFilter.pageSize = this.pageSize;
-
   this.loading = true;
-  this.hdDemoService.queryDemo(this.queryFilter).subscribe(
-    result => {
-      this.loading = false;
-      this.page = result;
-    }, error => {
-      this.loading = false;
-    }
+  this.service.query(this.queryFilter).subscribe(
+    result => { this.loading = false; this.page = result; },
+    () => { this.loading = false; }
   );
 }
-
-/**
-  * 表格的选择事件
-  * @param selectList 勾选的所有的数据集合
-  */
-selectResult(selectList?: any) {
-  // 拿到勾选的所有的数据
-  // console.log('selectList', selectList);
-  this.tableSelectList = selectList;
-}
 ```
 
-### 说明
-
-| 参数                     | 类型                           | 默认值          | 说明                                                         |
-| ------------------------ | ------------------------------ | --------------- | ------------------------------------------------------------ |
-| *tableData               | Page<any>                      |                 | 表格源数据                                                   |
-| scroll                   | { [*key*: string]: string }    | { x: '1150px' } | 滚动参数                                                     |
-| *tablePageIndex          | number                         |                 | 当前页码（双向绑定）                                         |
-| *tablePageSize           | number                         |                 | 每页展示的数据量（双向绑定）                                 |
-| *tableSearchEvent        | EventEmitter<reset: boolen>    |                 | 表格更换tablePageIndex、tablePageSize触发函数，emit重置标识  |
-| showSelected             | boolean                        | false           | 是否开启勾选功能                                             |
-| selectEvent              | EventEmitter<array>            |                 | 勾选状态改变触发函数，emit已勾选数组                         |
-| selectField              | string                         | billNumber      | 与showSelected配合使用，勾选判断逻辑的关键词（传入源数据中的主键字段） |
-| tableHead                | @ContentChild TemplateRef<any> |                 | 表格头插槽                                                   |
-| tableBody                | @ContentChild TemplateRef<any> |                 | 表格数据主体插槽                                             |
-| tableTotal               | @ContentChild TemplateRef<any> |                 | 表格顶部合计插槽                                             |
-| showTableTotal（弃用）   | boolean                        | False           | 是否显示底部合计区域                                         |
-| tableTotalOption（弃用） | Array<TableTotalOption>        |                 | 底部合计区域的合计字段选项集合                               |
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| tableData | Page\<any\> | — | 分页数据 |
+| tablePageIndex | number | 1 | 当前页（双向绑定） |
+| tablePageSize | number | 10 | 每页条数（双向绑定） |
+| tableLoading | boolean | false | 加载状态 |
+| tableSearchEvent | EventEmitter | — | 翻页 / 改 pageSize 触发，参数 reset 表示是否重置到第一页 |
+| scroll | object | { x: '1150px' } | 横向滚动 |
+| showSelected | boolean | false | 是否显示勾选列 |
+| selectField | string | billNumber | 勾选主键字段 |
+| selectEvent | EventEmitter | — | 勾选变化 |
+| tableHead / tableBody / tableTotal | TemplateRef | — | 表头 / 表体 / 顶部合计插槽 |
 
-### 注意点
+---
+
+## 9、增强表格（hd-table）
+
+在通用表格基础上支持**列配置渲染**、**排序**、**列宽/顺序/pageSize 本地缓存**、**设置列**等能力。列表页**优先推荐使用**。
+
+### 示例
+
+```html
+<hd-table #hdTable [(tablePageIndex)]="pageIndex" [(tablePageSize)]="pageSize"
+  [tableCols]="tableCols" [tableData]="page" [tableLoading]="loading"
+  (tableSearchEvent)="search($event)" showSelected showOperateColWarpButton
+  selectField="billNumber" (selectEvent)="selectResult($event)"
+  uuid="74907b48-1b17-4e51-9fa9-81fd0ac94051"
+  (sortEvent)="sortEvent($event)" (tablePageSizeChangeEvent)="search(true)">
+  <ng-template #tableLeftButton>
+    <hd-button type="default" (clickAction)="search()">刷新</hd-button>
+  </ng-template>
+  <ng-template #tableRightButton>
+    <hd-button type="default">导出</hd-button>
+  </ng-template>
+  <ng-template #tableTotal>...</ng-template>
+</hd-table>
+```
+
+```typescript
+tableCols: HdTableColumn[] = [{
+  title: '配送单号',
+  name: 'billNumber',
+  fixed: 'left',
+  click: (line) => { /* 点击行 */ }
+}, {
+  title: '状态',
+  name: 'state',
+  width: ColWidth.enumColWidth,
+  // stateField: 'orderStatus', // 可选，自定义状态取值字段，默认取 data.state
+  render: (line) => line.state === 'received' ? '已收货' : '未收货'
+}, {
+  title: '订单状态',
+  name: 'orderStatus',
+  isState: true, // 按 hd-status 渲染，取值字段为 name（orderStatus）
+  width: ColWidth.enumColWidth,
+  render: (line) => line.orderStatusText
+}, {
+  title: '操作',
+  name: 'operate',
+  width: ColWidth.operateColWidth,
+  btnList: [{ name: '删除', showConfirm: true, click: (line) => this.remove(line) }]
+  // showConfirm 也可传函数，按行属性决定是否二次确认
+  // btnList: [{ name: '删除', showConfirm: (line) => line.state !== 'draft', click: (line) => this.remove(line) }]
+}];
+```
 
-- 如果发现tableSearchEvent绑定的函数当tablePageSize改变时会触发两次，请不要惊慌，这是ngzorro8.5.x版本的bug，不会影响使用体验，只会额外调用一次接口，浪费些性能。
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| tableCols | HdTableColumn[] | [] | 列配置 |
+| tableData | Page\<any\> | — | 分页数据 |
+| tablePageIndex / tablePageSize | number | — | 分页（双向绑定） |
+| tableLoading | boolean | false | 加载状态 |
+| tableSearchEvent | EventEmitter | — | 翻页查询 |
+| sortEvent | EventEmitter | — | 排序 |
+| selectEvent | EventEmitter | — | 勾选变化 |
+| showSelected | boolean | false | 勾选列 |
+| showOperateColWarpButton | boolean | false | 展开/缩略显示换行列 |
+| showTableTotal | boolean | false | 底部合计行 |
+| tableTotalOption | HdTableTotalOption[] | — | 合计配置 |
+| isFirstEntrySearch | boolean | — | 首次进入是否自动查询 |
+| isCrossPageSelect | boolean | — | 跨页勾选 |
+| uuid | string | — | 列缓存唯一标识（必填，用于 IndexedDB 缓存） |
+| tableLeftButton / tableRightButton / tableTotal | TemplateRef | — | 工具栏插槽 |
 
+#### HdTableColumn 配置
 
+列定义见 [HdTableColumn](#hdtablecolumn表格列)、[OperateBtn](#operatebtn操作列按钮)、[HdTableTotalOption](#hdtabletotaloptionhd-table-底部合计)。
 
-## 4、筛选器(hd-filter)
+当 `name` 为 `state` 或 `isState` 为 `true` 时，列内容使用 `hd-status` 渲染。取值规则：`isState` 时取 `data[name]`；否则可通过 `stateField` 指定字段，未配置时默认取 `state`。
 
-### 效果图
+---
 
-![hd-filter](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-filter.png)
+## 10、表单（hd-form）
 
 ### 示例
 
-```js
-<hd-filter [filterList]="filterList" (searchEvent)="search(true, $event)"></hd-filter>
+```html
+<hd-form [formList]="formInput" (changeEvent)="formChangeEvent($event)"></hd-form>
 ```
 
-```tsx
-filterList: Array<Filter> = [];
-filterListTemplate: Array<Filter> = [{
-  type: FilterListType.Input,
+```typescript
+formInput: FormItem[] = [{
+  type: FormListType.Input,
   label: '配送单号',
-  name: 'billNumberEq',
-  value: '',
-  onChangeEvent: (item) => {
-    console.log('item', item);
-  }
+  name: 'billNumber',
+  require: true,
+  width: 2,
+  onChangeEvent: this.formInputChange.bind(this)
 }, {
-  type: FilterListType.Select,
-  label: '单项选择器测试测',
-  name: 'selectValue',
-  value: true,
-  selectOption: {
-    value: 'value',
-    label: 'label',
-    selectList: [{
-      value: true,
-      label: '是是是是是是是是是是是是是是是是是是是是是是'
-    }, {
-      value: false,
-      label: '否'
-    }]
-  },
-  onChangeEvent: (item) => {
-    console.log('item', item);
-  }
+  type: FormListType.Select,
+  label: '是否启用',
+  name: 'enabled',
+  width: 1,
+  selectOption: { value: 'value', label: 'label', selectList: [...] }
 }, {
-  type: FilterListType.MultipleSelect,
-  label: '多项选择器选择',
-  name: 'multipleSelectValue',
-  value: null,
-  onChangeEvent: (item) => {
-    console.log('onChangeEvent', item);
-  },
-  onSearchEvent: (item) => {
-    console.log('onSearchEvent', item);
-  },
-  selectOption: {
-    value: 'value',
-    label: 'label',
-    selectList: [{
-      value: '01',
-      label: '第一个第一个第一个第一个第一个'
-    }, {
-      value: '02',
-      label: '第二个'
-    }, {
-      value: '03',
-      label: '第三个'
-    }, {
-      value: '04',
-      label: '第四个'
-    }]
-  }
+  type: FormListType.Input,
+  label: '金额',
+  name: 'amount',
+  prefix: '¥' // 前缀文字，对应 nz-input-group nzPrefix
 }, {
-  type: FilterListType.Select,
-  label: '测试label',
-  name: 'selectValue1',
-  value: null,
-  selectOption: {
-    value: 'productCode',
-    label: 'productName',
-    showLabelAndValue: true,
-    selectList: []
-  },
-  onSearchEvent: (item, selectOption) => {
-    console.log('onSearchEvent', item);
-    console.log('selectOption', selectOption);
-    // 在这里去调接口查数据 定时器模拟调接口
-    setTimeout(() => {
-      selectOption.selectList = [{
-        productCode: '123213213',
-        productName: '测试商品1'
-      }, {
-        productCode: 'qwertyuiop',
-        productName: '测试商品2'
-      }]
-    }, 1000);
-  }
+  type: FormListType.Input,
+  label: '手机号',
+  name: 'mobile',
+  prefixIcon: 'phone' // 前缀图标，对应 nz-icon nzType
+}, {
+  type: FormListType.InputNumber,
+  label: '数量',
+  name: 'qty',
+  inputNumber: { min: 0, max: 9999, step: 1, precision: 2 }
 }, {
-  type: FilterListType.Date,
-  label: '单个日期选择',
-  name: 'dateValue',
-  value: '2020-1-2'
+  type: FormListType.Checkbox,
+  label: '是否启用',
+  name: 'enabled',
+  value: false // 单个复选框，值为 boolean
 }, {
-  type: FilterListType.DateRange,
-  label: '日期范围选择',
-  name: 'dateRangeValue',
-  value: ['2020-1-2', '2020-1-2']
+  type: FormListType.Checkbox,
+  label: '权限',
+  name: 'permissions',
+  value: ['read'],
+  checkboxOption: {
+    label: 'name',
+    value: 'code',
+    optionList: [
+      { code: 'read', name: '查看' },
+      { code: 'edit', name: '编辑' }
+    ]
+  }
 }];
 
-// 查询、重置按钮触发函数
-filterChange(filter?: any) {
-  console.log('filter',filter);
-  if (filter) {
-    this.queryFilter = filter;
-    // 因为更改了filter 需要清空所有的勾选 触发组件的重置事件
-    this.hdCurrentTable.resetStatus();
-    this.search(true);
-  }
+formChangeEvent(validateForm: FormGroup) {
+  this.validateHdForm = validateForm;
 }
 ```
 
-### 说明
-
-| 参数        | 类型           | 默认值 | 说明                                   |
-| ----------- | -------------- | ------ | -------------------------------------- |
-| filterList  | Array<Filter>  |        | 所有的筛选器空间数据                   |
-| searchEvent | EventEmitter<> |        | 查询、重置按钮触发函数，带回筛选器数据 |
-
-#### Filter
-
-| 参数          | 类型                                                        | 默认值 | 说明                                                         |
-| ------------- | ----------------------------------------------------------- | ------ | ------------------------------------------------------------ |
-| *type         | FilterListType                                              |        | 控件类型  Input \| Select \| Date \| DateRange \| MultipleSelect |
-| *label        | string                                                      |        | 控件前文案                                                   |
-| *name         | string                                                      |        | 字段名称                                                     |
-| placeholder   | string                                                      |        | 输入框提示文案                                               |
-| value         | string \| boolen \| number \| Array<string \| Date> \| null | null   | 初始值                                                       |
-| selectOption  | SelectOption                                                |        | select选择器选项配置                                         |
-| onSearchEvent | EventEmitter<>                                              |        | select选择器搜索事件 可用于更新备选集合                      |
-| onChangeEvent | EventEmitter<>                                              |        | 控件的值改变事件 可用于控件间联动                            |
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| formList | FormItem[] | 表单项配置 |
+| changeEvent | EventEmitter | 表单值变化，返回 FormGroup |
 
-#### SelectOption
+#### FormItem 配置
 
-| 参数                       | 类型       | 默认值 | 说明                                                   |
-| -------------------------- | ---------- | ------ | ------------------------------------------------------ |
-| *label                     | string     |        | label字段，取selectList数组中的某个字段作为选择器label |
-| *value                     | string     |        | Value字段，取selectList数组中的某个字段作为选择器value |
-| *selectList                | Array<any> |        | 选项列表                                               |
-| showLabelAndValue          | boolean    | false  | 选项同时展示label和value，格式：[value]label           |
-| hdDropdownMatchSelectWidth | boolean    | false  | 选择框长度是否和控件长度保持一致，默认不保持           |
+表单项使用 [FormItem](#formitem表单项) 类型，下拉/数字等子配置见 [SelectOption](#selectoption下拉选项配置)、[InputNumber](#inputnumber数字输入配置)、[RadioOption](#radiooption单选配置)、[CheckboxOption](#checkboxoption复选框配置)。
 
-### 注意点
-
-- 事件函数如果内部语句过多，请使用bind（this）方法，示例：onChangeEvent: this.formInputChange.bind(this)
+---
 
-## 5、状态(hd-status)
+## 11、明细表单（hd-form-lines）
 
-### 效果图
-
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-status.png)
+可编辑的明细行表格，支持键盘导航、行内搜索、合计等。
 
 ### 示例
 
 ```html
-<hd-status status="initial">未审核</hd-status>
-<hd-status status="audited">已审核</hd-status>
-<hd-status status="picking">拣货中</hd-status>
-<hd-status status="partshipped">部分收货</hd-status>
-<hd-status status="received">已收货</hd-status>
-<hd-status status="deleted">已删除</hd-status>
-<hd-status status="shipped">已配送</hd-status>
+<hd-form-lines #hdFormLines showSearch showKeyboardOperateTip
+  [formLines]="formLines" [formLinesData]="formLinesData"
+  [operateButtons]="['add', 'delete']" [allowEmpty]="false"
+  (changeEvent)="formLinesChangeEvent($event)">
+</hd-form-lines>
 ```
 
-### 说明
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| formLines | FormLine[] | — | 列定义 |
+| formLinesData | any[] | — | 行数据 |
+| operateButtons | string[] | ['add','delete'] | 操作按钮 |
+| showDeleteConfirm | boolean | false | 删除前确认 |
+| showSearch | boolean | false | 行内搜索 |
+| showKeyboardOperateTip | boolean | false | 键盘操作提示 |
+| showLineNumber | boolean | true | 序号列 |
+| allowEmpty | boolean | true | 是否允许空表 |
+| showTotal | boolean | false | 合计行 |
+| totalOption / columnsNumber | — | — | 合计配置 |
+| scroll | object | { x: '1px' } | 横向滚动 |
+| changeEvent | EventEmitter | — | 表单变化 |
+| deleteLastLineEvent | EventEmitter | — | 删除最后一行 |
 
-| 参数   | 类型   | 说明   |
-| ------ | ------ | ------ |
-| status | string | 状态值 |
+#### FormLine 配置
 
-### 注意点
+明细列使用 [FormLine](#formline明细表单项) 类型，含 [ColorOption](#coloroption)、[ExplainOption](#explainoption) 及表格型 [SelectOption](#selectoption下拉选项配置)。
 
-- state需要在hd-status.service.ts中的statusToColor添加值，选择对应的颜色
+---
 
+开启 `showKeyboardOperateTip` 后支持 `[↑][↓][←][→]`、`Enter` 在单元格间跳转；InputNumber 上下键用于跳转，不触发 step 增减。
 
+#### 暴露方法
 
-## 6、详情头(hd-detail-tip)
+```typescript
+this.hdFormLines.getValid(); // 获取整表校验状态
+```
 
-### 效果图
+---
 
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-detail-tip.png)
+## 12、详情头（hd-detail-tip）
 
 ### 示例
 
@@ -385,590 +456,480 @@ filterChange(filter?: any) {
 <hd-detail-tip state="shipped" stateText="配送中" billNumber="202111030001"></hd-detail-tip>
 ```
 
-### 说明
-
-| 参数       | 类型   | 说明     |
-| ---------- | ------ | -------- |
-| state      | string | 状态值   |
-| stateText  | string | 状态文案 |
-| billNumber | string | 单号     |
-
-### 注意点
-
-- state需要在hd-status.service.ts中的statusToColor添加值，选择对应的颜色
-
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| state | string | 状态值 |
+| stateText | string | 状态文案 |
+| billNumber | string | 单号 |
+| tip | string | 前缀文案，默认「详情」 |
 
+---
 
-## 7、详情单头(hd-detail-form)
-
-### 效果图
-
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-detail-form.png)
+## 13、详情单头（hd-detail-form）
 
 ### 示例
 
 ```html
 <hd-detail-form [formCols]="formCols"></hd-detail-form>
+<!-- 固定两列：<hd-detail-form [formCols]="formCols" [nzColumn]="2"></hd-detail-form> -->
 ```
 
-```tsx
-// 详情页面单头组件数据
-formCols: Array<HdOption> = [
-  {
-    label: '收货单号收货单号收货单号',
-    value: '202111030001'
-  },
-  {
-    label: '收货单号',
-    value: '202111030001'
-  },
-  {
-    label: '收货单号',
-    value: '202111030001'
-  },
-  {
-    label: '收货单号',
-    value: ''
-  },
-  {
-    label: '收货单号',
-    value: '202111030001'
-  },
-  {
-    label: '备注',
-    value: '字数很多字数很多字数很多字数很多202111030001字数很多字数很多字数很多字数很多202111030001字数很多字数很多字数很多字数很多202111030001'
-  },
+```typescript
+formCols: HdOption[] = [
+  { label: '收货单号', value: '202111030001' },
+  { label: '备注', value: '...' }
 ];
 ```
 
-### 说明
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| formCols | HdOption[] | — | 展示字段，见 [HdOption](#hdoption键值展示项) |
+| nzColumn | number \| object | `{ xxl: 4, xl: 3, lg: 3, md: 3, sm: 2, xs: 1 }` | 列数；传数字为固定列数，传对象为响应式列数 |
+
+---
 
-| 参数     | 类型                 | 说明         |
-| -------- | -------------------- | ------------ |
-| formCols | Array<{label,value}> | 展示的列数组 |
+## 14、详情明细（hd-detail-lines）
 
+详情页只读/轻编辑明细表格，支持**前端分页**和**行内搜索**。
 
+### 示例
 
-## 8、详情明细(hd-detail-lines)
+```html
+<!-- 带搜索 + 前端分页 -->
+<hd-detail-lines showSearch [lines]="lines" [scroll]="{x: '1150px'}">
+  <ng-template #detailLineHead>...</ng-template>
+  <ng-template #detailLineBody let-data let-index="index">...</ng-template>
+</hd-detail-lines>
 
-### 效果图
+<!-- 勾选 + 合计 + 前端分页 -->
+<hd-detail-lines [lines]="lines" showSelected selectField="uuid"
+  hdFrontPagination showTotal columnsNumber="4" [totalOption]="detailLinesTotalOption"
+  (selectEvent)="selectResultLines($event)">
+  ...
+</hd-detail-lines>
+```
 
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-detail-lines.png)
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| lines | any[] | — | 明细数据 |
+| scroll | object | { x: '1px' } | 横向滚动 |
+| showSearch | boolean | false | 行内搜索 |
+| searchFields | string[] | [] | 搜索字段，空则搜全部字段 |
+| hdFrontPagination | boolean | false | 前端分页 |
+| showSelected | boolean | false | 勾选 |
+| selectField | string | billNumber | 勾选主键 |
+| selectedField | string | — | 初始勾选标记字段 |
+| selectEvent | EventEmitter | — | 勾选变化 |
+| allowDrop | boolean | false | 拖拽排序 |
+| showTotal | boolean | false | 合计行 |
+| columnsNumber | number | — | 总列数（含合计） |
+| totalOption | TotalOption[] | — | 合计配置，见 [TotalOption](#totaloption明细合计行) |
+| detailLineHead / detailLineBody | TemplateRef | — | 表头 / 表体插槽 |
+
+---
+
+## 15、详情明细-服务端分页（hd-detail-lines-page）
+
+与 `hd-detail-lines` 模板用法相同，但**不做内部分页和搜索**，分页由父组件控制（对齐 `hd-table`）。
 
 ### 示例
 
 ```html
-<hd-detail-lines [scroll]="{x: '1150px'}" selectField="uuid" (selectEvent)="selectResultLines($event)"
-  [lines]="lines" showSelected columnsNumber="4" showTotal [totalOption]="detailLinesTotalOption">
+<hd-detail-lines-page [scroll]="{x: '1150px'}"
+  [lines]="detailLinesPageData.content"
+  [tableData]="detailLinesPageData"
+  [tableLoading]="detailLinesPageLoading"
+  [tablePageIndex]="detailLinesPageIndex"
+  [tablePageSize]="detailLinesPageSize"
+  (tablePageIndexChange)="onDetailLinesPageIndexChange($event)"
+  (tablePageSizeChange)="onDetailLinesPageSizeChange($event)">
   <ng-template #detailLineHead>
     <th style="width: 40px">序号</th>
     <th style="width: 150px">商品编码</th>
     <th>商品名称</th>
-    <th style="width: 80px" nzRight="0">操作</th>
   </ng-template>
-  <ng-template #detailLineBody let-data>
-    <td style="width: 40px">{{ data.lineNumber || '&lt;空&gt;' }}</td>
-    <td style="width: 150px">
-      <span *ngIf="!modifyFlag;else modifyTmp">{{ data.productCode || '&lt;空&gt;'  }}</span>
-      <ng-template #modifyTmp>
-        <input nz-input placeholder="请输入商品编码" [(ngModel)]="data.productCode" />
-      </ng-template>
-    </td>
-    <td>{{ data.productName || '&lt;空&gt;'  }}</td>
-    <td style="width: 80px" nzRight="0">
-      <span class="common-btn-group">
-        <a>详情</a>
-        <a class="common-danger-btn">删除</a>
-      </span>
-    </td>
+  <ng-template #detailLineBody let-data let-index="index">
+    <td>{{ index + 1 }}</td>
+    <td>{{ data.productCode }}</td>
+    <td>{{ data.productName }}</td>
   </ng-template>
-</hd-detail-lines>
+</hd-detail-lines-page>
 ```
 
-```tsx
-detailLinesTotalOption = [{
-  insertIndex: 1,
-  insertValue: 100
-},{
-  insertIndex: 2,
-  insertValue: 200,
-  align: 'right'
-}]
-
-/**
-  * 明细的选择事件
-  * @param selectList 勾选的所有的数据集合
-  */
-selectResultLines(selectList?: any) {
-   // 拿到勾选的所有的数据
-   // console.log('selectResultLines', selectList);
+```typescript
+detailLinesPageData: Page<any> = new Page();
+detailLinesPageIndex = 1;
+detailLinesPageSize = 5;
+detailLinesPageLoading = false;
+
+loadDetailLinesPage(reset = false) {
+  if (reset) { this.detailLinesPageIndex = 1; }
+  this.detailLinesPageLoading = true;
+  this.service.queryLines({
+    pageNumber: this.detailLinesPageIndex - 1,
+    pageSize: this.detailLinesPageSize
+  }).subscribe(result => {
+    this.detailLinesPageData = result;
+    this.detailLinesPageLoading = false;
+  });
 }
-```
 
-### 说明
+onDetailLinesPageIndexChange(pageIndex: number) {
+  this.detailLinesPageIndex = pageIndex;
+  this.loadDetailLinesPage();
+}
 
-| 参数           | 类型                           | 默认值     | 说明                                                         |
-| -------------- | ------------------------------ | ---------- | ------------------------------------------------------------ |
-| *lines         | Array<any>                     |            | 接口返回的源数据                                             |
-| showTotal      | boolean                        | false      | 是否显示合计                                                 |
-| columnsNumber  | number \| string               |            | 列数（detailLineHead中所有的列数）                           |
-| totalOption    | Array<TotalOption>             |            | 合计列选项                                                   |
-| showSelected   | boolean                        | false      | 是否开启勾选功能                                             |
-| selectEvent    | EventEmitter<array>            |            | 勾选状态改变触发函数，emit已勾选数组                         |
-| selectField    | string                         | billNumber | 与showSelected配合使用，勾选判断逻辑的关键词（传入源数据中的主键字段） |
-| detailLineHead | @ContentChild TemplateRef<any> |            | 表格头插槽                                                   |
-| detailLineBody | @ContentChild TemplateRef<any> |            | 表格数据主体插槽                                             |
+onDetailLinesPageSizeChange(pageSize: number) {
+  this.detailLinesPageSize = pageSize;
+  this.loadDetailLinesPage(true);
+}
+```
 
-#### TotalOption
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| lines | any[] | [] | 当前页数据（也可用 tableData.content） |
+| tableData | Page\<any\> | — | 分页对象，提供 totalElements |
+| tablePageIndex / tablePageSize | number | 1 / 10 | 分页 |
+| tableLoading | boolean | false | 加载状态 |
+| tablePageIndexChange | EventEmitter | — | 页码变化 |
+| tablePageSizeChange | EventEmitter | — | 每页条数变化（组件内会重置到第 1 页） |
+| pageChange | EventEmitter | — | 任意分页变化 |
+| showSelected / allowDrop / showTotal 等 | — | — | 同 hd-detail-lines |
+| isCrossPageSelect | boolean | — | 跨页勾选 |
 
-| 参数        | 类型   | 说明                                |
-| ----------- | ------ | ----------------------------------- |
-| insertIndex | number | 插入下标                            |
-| insertValue | any    | 插入值                              |
-| align       | string | 列对齐方式  left \| right \| center |
+模板中 `index` 为**全局序号**：`(pageIndex - 1) * pageSize + 行号`。
 
+### 与 hd-detail-lines 选型
 
+| 场景 | 推荐组件 |
+| ---- | -------- |
+| 数据量小、前端筛选/分页 | hd-detail-lines |
+| 接口分页、数据量大 | hd-detail-lines-page |
 
-## 9、表单(hd-form)
+---
 
-### 效果图
+## 16、操作日志（hd-log）
 
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-form.png)
+基于 `hd-detail-lines` 封装的日志展示，内置列：时间、操作人、事件、描述。
 
 ### 示例
 
 ```html
-<hd-form [formList]="formInput" (changeEvent)="formChangeEvent($event)"></hd-form>
+<hd-log [logs]="logs"></hd-log>
 ```
 
-```tsx
-validateHdForm: FormGroup;
-formInput: Array<FormItem> = [{
-  type: FormListType.Input,
-  label: '配送单号',
-  name: 'billNumberEq',
-  require: true,
-  width: 2,
-  value: '',
-  maxLength: 10,
-  color: 'blue',
-  // 事件传递的建议写法, 建议使用bind(this), 而不是箭头函数
-  onChangeEvent: this.formInputChange.bind(this)
-}, {
-  type: FormListType.ViewDom,
-  label: '学校',
-  name: 'school',
-  width: 2,
-  value: '[T8888]测试用中学'
-}, {
-  type: FormListType.Select,
-  label: '单项选择器选择',
-  name: 'selectValue',
-  value: 'qwer',
-  require: true,
-  defaultLabel: '组件外默认的选项',
-  width: 2,
-  onChangeEvent: (item) => {
-    console.log('onChangeEvent', item);
-    console.log('测试this', this);
-    this.validateHdForm.get('qwer').setValue(true);
-  },
-  onSearchEvent: (item) => {
-    console.log('onSearchEvent', item);
-  },
-  selectOption: {
-    value: 'value',
-    label: 'label',
-    showLabelAndValue: true, // 使用此配置，最后展示为[value]label
-    selectList: [{
-      value: true,
-      label: '是'
-    }, {
-      value: false,
-      label: '否'
-    }]
-  }
-}, {
-  type: FormListType.MultipleSelect,
-  label: '多项选择器选择',
-  name: 'multipleSelectValue',
-  value: ['05', '06'],
-  require: true,
-  defaultLabel: ['第五个', '第六个'],
-  width: 2,
-  onChangeEvent: (item) => {
-    console.log('onChangeEvent', item);
-  },
-  onSearchEvent: (item) => {
-    console.log('onSearchEvent', item);
-  },
-  selectOption: {
-    value: 'value',
-    label: 'label',
-    selectList: [{
-      value: '01',
-      label: '第一个'
-    }, {
-      value: '02',
-      label: '第二个'
-    }, {
-      value: '03',
-      label: '第三个'
-    }, {
-      value: '04',
-      label: '第四个'
-    }]
-  }
-}, {
-  type: FormListType.Date,
-  label: '单个日期选择选择',
-  name: 'dateValue',
-  width: 1,
-  value: '2020-1-2'
-}, {
-  type: FormListType.DateRange,
-  label: '日期范围选择',
-  require: true,
-  width: 1,
-  name: 'dateRangeValue',
-  value: ['2020-1-2', '2020-1-2']
-}, {
-  type: FormListType.InputNumber,
-  label: '数字输入',
-  require: true,
-  width: 1,
-  name: 'inputNumberValue',
-  value: null,
-  disabled: false,
-  color: 'red'
-}, {
-  type: FormListType.TextArea,
-  label: '备注',
-  require: true,
-  name: 'remark',
-  width: 4,
-  value: '这是个备注'
-}];
-
-
-/**
-  * form组件值改变函数
-  * @param validateForm form组件返回的表单对象
-  */
-formChangeEvent(validateForm: any) {
-  this.validateHdForm = validateForm;
-  // console.log('form组件返回',this.validateHdForm.getRawValue());
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| logs | any[] | 日志列表，字段：`createInfo.operateTime`、`createInfo.operatorName`、`event`、`describe` |
+
+也可作为 Modal 内容组件使用（`entryComponents: HdLogComponent`）。
+
+---
+
+## 附录：公共配置类型
+
+以下类型在 `hd-filter`、`hd-form`、`hd-form-lines`、`hd-table` 等组件中复用。
+
+### SelectOption（下拉选项配置）
+
+用于 `Filter.selectOption`、`FormItem.selectOption`、`FormLine.selectOption`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| label | string | — | selectList 中作为显示文案的字段名 |
+| value | string | — | selectList 中作为绑定值的字段名 |
+| selectList | any[] | — | 静态选项列表 |
+| selectListName | string | — | 选项来自行数据某字段时使用（配合 hide 字段） |
+| showLabelAndValue | boolean | false | 选项展示为 `[value]label` |
+| hdDropdownMatchSelectWidth | boolean | false | 下拉宽度是否与控件一致 |
+| hdServerSearch | boolean | false | 是否远程搜索 |
+| hdShowSearch | boolean | true | 是否可搜索 |
+| hdAllowClear | boolean | true | 是否允许清空 |
+| hdShowItemCode | boolean | false | 已选展示是否带 `[value]` 前缀 |
+| tableColumns | SelectOptionTableColumn[] | — | 表格型下拉列配置（商品选择器等） |
+
+```typescript
+selectOption: {
+  value: 'productCode',
+  label: 'productName',
+  showLabelAndValue: true,
+  hdServerSearch: true,
+  selectList: [],
+  tableColumns: [
+    { width: ColWidth.codeNameColWidth, label: '商品', name: 'product',
+      render: (line) => `[${line.productCode}] ${line.productName}` },
+    { width: ColWidth.enumColWidth, label: '规格', name: 'specification' }
+  ]
 }
 ```
 
-### 说明
-
-| 参数            | 类型            | 默认值 | 说明                             |
-| --------------- | --------------- | ------ | -------------------------------- |
-| formInput       | Array<FormItem> |        | 表单控件数组                     |
-| formChangeEvent | EventEmitter<>  |        | 表单值改变事件，返回当前表单内容 |
-
-#### TotalOption
-
-| 参数          | 类型                                                         | 说明                                                         |
-| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| *type         | FormListType                                                 | 控件类型  Input \| Select \| Date \| DateRange \| MultipleSelect \| TextArea \| InputNumber \| ViewDom（单纯的显示控件） |
-| *label        | string                                                       | 文本                                                         |
-| *name         | string                                                       | 字段名                                                       |
-| require       | boolen                                                       | 是否必填                                                     |
-| placeholder   | string                                                       | 输入框提示文案                                               |
-| width         | number                                                       | 占据的列数。默认1                                            |
-| value         | string \| boolen \| number \| Array<Date> \| Array<string> \| null | 值                                                           |
-| disabled      | boolen                                                       | 是否禁用                                                     |
-| color         | string                                                       | 控件文本颜色                                                 |
-| hide          | boolean                                                      | 是否为隐藏字段，仅用于填充表单的字段，不显示在页面上         |
-| maxLength     | number                                                       | input控件的输入长度                                          |
-| selectOption  | SelectOption                                                 | 控件为Select时，选项列表                                     |
-| inputNumber   | InputNumber                                                  | number组件的选项，min、max、step                             |
-| onChangeEvent | Function                                                     | 控件的值改变事件 可用于控件间联动                            |
-| onSearchEvent | Function                                                     | select选择器搜索事件 可用于更新备选集合                      |
-| defaultLabel  | string \| Array<string>                                      | select选择器不初始化的时候可以使用defaultLabel搭配value，设置默认值 |
-
-#### InputNumber
-
-| 参数 | 类型   | 默认值   | 说明   |
-| ---- | ------ | -------- | ------ |
-| min  | number | 0        | 最小值 |
-| max  | number | 99999999 | 最大值 |
-| step | number | 1        | 步阶   |
-
-#### SelectOption
-
-| 参数                       | 类型       | 默认值 | 说明                                                   |
-| -------------------------- | ---------- | ------ | ------------------------------------------------------ |
-| *label                     | string     |        | label字段，取selectList数组中的某个字段作为选择器label |
-| *value                     | string     |        | Value字段，取selectList数组中的某个字段作为选择器value |
-| *selectList                | Array<any> |        | 选项列表                                               |
-| showLabelAndValue          | boolean    | false  | 选项同时展示label和value，格式：[value]label           |
-| hdDropdownMatchSelectWidth | boolean    | false  | 选择框长度是否和控件长度保持一致，默认不保持           |
-
-## 10、明细表单(hd-form-lines)
-
-### 效果图
-
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-form-lines.png)
-
-### 示例
-
-```html
-<hd-form-lines [formLines]="formLines" [operateButtons]="['delete']" showDeleteConfirm     			[formLinesData]="formLinesData" (changeEvent)="formLinesChangeEvent($event)"></hd-form-lines>
-```
-
-```tsx
-validateHdFormLines: FormGroup;
-formLines: Array<FormLine> = [{
-  type: FormLineType.Select,
-  label: '商品',
-  name: 'productCode',
-  require: true,
-  onChangeEvent: (item, line: FormGroup) => {
-    // 列之间的交互赋值等等
-    console.log('item', item);
-    console.log('测试this', line);
-    if (item) {
-      line.get('productSpec').setValue(12);
-      line.get('money').setValue(22);
-    }
-  },
-  onSearchEvent: (item) => {
-    console.log('onSearchEvent', item);
-    // 在这里去调接口查数据
-    this.formLines[0].selectOption.selectList = [{
-      productCode: '03',
-      productName: '第三个'
-    }, {
-      productCode: '04',
-      productName: '第四个'
-    }]
-    console.log('formLines', this.formLines);
-  },
-  selectOption: {
-    value: 'productCode',
-    label: 'productName',
-    showLabelAndValue: true,
-    selectList: [{
-      productCode: '01',
-      productName: '第一个'
-    }, {
-      productCode: '02',
-      productName: '第二个'
-    }]
-  }
-},{
-  type: FormLineType.MultipleSelect,
-  label: '多项选择器选择',
-  name: 'multipleSelectValue',
-  require: true,
-  onChangeEvent: (item) => {
-    console.log('onChangeEvent', item);
-  },
-  onSearchEvent: (item) => {
-    console.log('onSearchEvent', item);
-  },
-  selectOption: {
-    value: 'multipleSelectValue',
-    label: 'multipleSelectValueLabel',
-    selectList: [{
-      multipleSelectValue: '01',
-      multipleSelectValueLabel: '第一个'
-    }, {
-      multipleSelectValue: '02',
-      multipleSelectValueLabel: '第二个'
-    }, {
-      multipleSelectValue: '03',
-      multipleSelectValueLabel: '第三个'
-    }, {
-      multipleSelectValue: '04',
-      multipleSelectValueLabel: '第四个'
-    }]
-  }
-}, {
-  type: FormLineType.Input,
-  label: '测试输入框',
-  name: 'testInput',
-  maxLength: 10,
-  explainOption: {
-    show: true,
-    name: 'explain',
-    color: 'red'
-  },
-  onChangeEvent: (item, line: FormGroup) => {
-    // 这里利用隐藏属性 根据line里面的相关字段 去判断是否需要展示出来
-    if(line.get('hideQuantity').value === 100 && item){
-      line.get('explain').setValue('这是一个测试文案qaq');
-    }else{
-      line.get('explain').setValue('');
-    }
-  },
-}, {
-  type: FormLineType.InputNumber,
-  label: '测试输入框1',
-  name: 'testInput1',
-  maxLength: 10,
-  colorOption: {
-    name: 'inputColor',
-    color: 'red'
-  },
-  onChangeEvent: (item, line: FormGroup) => {
-    // 这里利用隐藏属性 根据line里面的相关字段 去判断是否需要展示出来
-    if(line.get('testInput1').value >= 50 && item){
-      line.get('inputColor').setValue('red');
-    }else{
-      line.get('inputColor').setValue(null);
-    }
-  },
-}, {
-  type: FormLineType.ViewDom,
-  label: '规格',
-  name: 'productSpec'
-}, {
-  type: FormLineType.ViewDom,
-  label: '金额',
-  name: 'money',
-  preserveNumber: 1
-}, {
-  type: FormLineType.ViewDom,
-  label: '价格',
-  align: 'right',
-  name: 'price',
-  preserveNumber: 2
-}, {
-  type: FormLineType.ViewDom,
-  label: '数量',
-  name: 'quantity'
-}, {
-  type: FormLineType.ViewDom,
-  label: '隐藏数量',
-  hide: true,
-  name: 'hideQuantity'
-}, {
-  type: FormLineType.ViewDom,
-  label: '隐藏的说明',
-  hide: true,
-  name: 'explain'
-}, {
-  type: FormLineType.ViewDom,
-  label: '隐藏的颜色，用于表示',
-  hide: true,
-  name: 'inputColor'
-}];
+### SelectOptionTableColumn（表格型下拉列）
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| width | number | 列宽（px），参考 `ColWidth` |
+| label | string | 表头文案 |
+| name | string | selectList item 字段名 |
+| render | (line) => string | 自定义渲染，优先级高于 name |
+| icons | SelectOptionTableColumnIcon[] | 图标列（如推荐、协采标签） |
+
+### SelectOptionTableColumnIcon（表格型下拉图标列）
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| iconName | string | `hd-select-close`（禁用）、`hd-select-purchase`（协）、`hd-recommend-star`、`hd-img-star` |
+| fieldName | string | selectList item 中控制显示的布尔字段 |
+
+### InputNumber（数字输入配置）
+
+用于 `Filter.inputNumber`、`FormItem.inputNumber`、`FormLine.inputNumber`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| min | number | 0 | 最小值 |
+| max | number | 99999999 | 最大值 |
+| step | number | 1 | 步进值 |
+| precision | number | 4 | 小数精度 |
+| nzFormatter | Function | — | 展示格式化 |
+| nzParser | Function | — | 输入解析 |
+
+### CascaderOption（级联选择配置）
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| options | any[] | 级联数据源（ng-zorro cascader 格式） |
+
+### RadioOption（单选配置）
+
+用于 `FormItem.radioOption`（`FormListType.Radio`）。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| label | string | — | optionList 中作为显示文案的字段名 |
+| value | string | — | optionList 中作为绑定值的字段名 |
+| optionList | any[] | — | 选项列表 |
+| showLabelAndValue | boolean | false | 选项展示为 `[value]label` |
+
+### CheckboxOption（复选框配置）
+
+用于 `FormItem.checkboxOption`（`FormListType.Checkbox` 多选组）。未配置 `checkboxOption` 时渲染单个复选框，值为 `boolean`，默认 `false`；配置后为复选框组，值为选中项 `value` 组成的数组，默认 `[]`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| label | string | — | optionList 中作为显示文案的字段名 |
+| value | string | — | optionList 中作为绑定值的字段名 |
+| optionList | any[] | — | 选项列表 |
+| showLabelAndValue | boolean | false | 选项展示为 `[value]label` |
+
+### HdOption（键值展示项）
+
+用于 `hd-detail-form` 的 `formCols`。
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| label | string | 标签 |
+| value | any | 值 |
+| color | string | 文字颜色 |
+| hide | boolean | 是否隐藏 |
+| clickText | string | 可点击文案 |
+| click | (value) => void | 点击回调 |
+
+### Filter（筛选项）
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| type | FilterListType | — | 控件类型 |
+| label | string | — | 标签 |
+| name | string | — | 字段名（提交给后端的 key） |
+| value | any | null | 初始值 |
+| placeholder | string | — | 占位符 |
+| require | boolean | false | 是否必填 |
+| show | boolean | — | 是否显示 |
+| selectOption | SelectOption | — | Select / MultipleSelect 配置 |
+| inputNumber | InputNumber | — | InputNumber 配置 |
+| cascaderOption | CascaderOption | — | Cascader 配置 |
+| showTime | boolean | false | Date 是否含时间 |
+| hdDisabledDate | Function | — | 不可选日期 `(date) => boolean` |
+| onChangeEvent | Function | — | 值变化 |
+| onSearchEvent | Function | — | 下拉搜索 |
+| onBlurEvent | Function | — | 失焦 |
+| onChangeEventDebounceTime | number | — | change 防抖（ms） |
+| onSearchEventEventDebounceTime | number | — | search 防抖（ms） |
+
+#### FilterListType 枚举
+
+`Input` \| `Select` \| `MultipleSelect` \| `Date` \| `DateRange` \| `Cascader` \| `Month` \| `InputNumber`
+
+### FormItem（表单项）
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| type | FormListType | — | 控件类型 |
+| label / name | string | — | 标签 / 字段名 |
+| require | boolean | false | 是否必填 |
+| width | number | 1 | 占据列数（总宽 4 列） |
+| hide | boolean | false | 隐藏字段 |
+| value | any | null | 初始值 |
+| placeholder | string | — | 占位符 |
+| disabled | boolean | — | 是否禁用 |
+| color / labelColor | string | — | 控件 / 标签颜色 |
+| maxLength | number | — | Input 最大长度 |
+| prefix | string | — | Input 前缀文字（`nzPrefix`） |
+| prefixIcon | string | — | Input 前缀图标（`nz-icon` 的 `nzType`） |
+| textAreaRows | number | — | TextArea 行数 |
+| explain | string | — | label 下方说明 |
+| showTime | boolean | false | Date 含时间 |
+| format | string | — | 时间格式化 |
+| selectOption | SelectOption | — | 下拉配置 |
+| radioOption | RadioOption | — | 单选配置 |
+| checkboxOption | CheckboxOption | — | 复选框组配置；不传则为单个复选框 |
+| inputNumber | InputNumber | — | 数字框配置 |
+| cascaderOption | CascaderOption | — | 级联配置 |
+| defaultLabel | string \| string[] | — | Select 默认展示文案 |
+| hdDisabledDate | Function | — | 不可选日期 |
+| validatorKeys | ValidatorKey[] | — | 校验键 |
+| validator | ValidatorFn | — | 自定义校验 |
+| onChangeEvent / onSearchEvent | Function | — | 值变化 / 下拉搜索 |
+| onChangeEventDebounceTime | number | — | change 防抖（ms） |
+| onSearchEventEventDebounceTime | number | — | search 防抖（ms） |
+
+#### FormListType 枚举
+
+`Input` \| `Select` \| `MultipleSelect` \| `Date` \| `DateRange` \| `TextArea` \| `InputNumber` \| `ViewDom` \| `Switch` \| `Time` \| `Cascader` \| `Radio` \| `Checkbox`
+
+#### ValidatorKey
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| key | string | 校验规则 key |
+| label | string | 校验失败提示 |
+
+### FormLine（明细表单项）
+
+在 FormItem 基础上用于行内编辑，额外字段：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| type | FormLineType | — | 控件类型 |
+| align | string | — | 列对齐 |
+| hideViewDomValue | boolean | false | ViewDom 隐藏 value |
+| isSelect | boolean | — | 聚焦后全选内容 |
+| preserveNumber | number | — | ViewDom 小数位 |
+| disabled | boolean | — | 是否禁用 |
+| style | object | — | 列样式 |
+| canSearch | boolean | false | hide 字段参与搜索 |
+| explainOption / explainOptionRight | ExplainOption | — | 说明文字 |
+| colorOption | ColorOption | — | 动态颜色 |
+| selectOption | SelectOption | — | 含 tableColumns 表格下拉 |
+| onChangeEventDebounceTime | number | — | change 防抖（ms） |
+
+#### FormLineType 枚举
+
+`Input` \| `Select` \| `Date` \| `DateRange` \| `TextArea` \| `InputNumber` \| `MultipleSelect` \| `ViewDom` \| `Switch` \| `Time`
+
+#### ColorOption / ExplainOption
+
+| ColorOption | ExplainOption |
+| ----------- | ------------- |
+| name：hide 字段名存颜色 | show：是否显示 |
+| color：默认颜色 | name：hide 字段名存文案 |
+| | color：文字颜色 |
+
+#### FormLine 事件签名
+
+```typescript
+onChangeEvent: (value, line: FormGroup) => void
+onSearchEvent: (keyword, line?: FormGroup) => void
 ```
 
-### 说明
-
-| 参数              | 类型            | 默认值           | 说明                                                         |
-| ----------------- | --------------- | ---------------- | ------------------------------------------------------------ |
-| formInput         | Array<FormItem> |                  | 表单控件数组                                                 |
-| operateButtons    | Array<string>   | ['add','delete'] | 操作按钮组，默认有添加和删除，如传入['delete']则不显示新增按钮 |
-| showDeleteConfirm | boolen          | false            | 删除按钮是否显示确认提示框                                   |
-| formChangeEvent   | EventEmitter<>  |                  | 表单值改变事件，返回当前表单内容                             |
-
-#### TotalOption
-
-| 参数           | 类型                                                         | 说明                                                         |
-| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| *type          | FormListType                                                 | 控件类型  Input \| Select \| Date \| DateRange \| MultipleSelect \| TextArea \| InputNumber \| ViewDom（单纯的显示控件） |
-| *label         | string                                                       | 文本                                                         |
-| *name          | string                                                       | 字段名                                                       |
-| placeholder    | string                                                       | 输入框提示文案                                               |
-| require        | boolen                                                       | 是否必填                                                     |
-| width          | number                                                       | 占据的列数。默认1                                            |
-| value          | string \| boolen \| number \| Array<Date> \| Array<string> \| null | 值                                                           |
-| align          | string                                                       | 列对齐方式，'left' \| 'right' \| 'center'                    |
-| isSelect       | boolean                                                      | 输入框等是否允许点击之后全选内容，默认不允许                 |
-| colorOption    | ColorOption                                                  | 颜色选项                                                     |
-| explainOption  | ExplainOption                                                | 说明字段                                                     |
-| hide           | boolean                                                      | 是否为隐藏字段，仅用于填充表单的字段，不显示在页面上         |
-| maxLength      | number                                                       | input控件的输入长度                                          |
-| selectOption   | SelectOption                                                 | 控件为Select时，选项列表                                     |
-| inputNumber    | InputNumber                                                  | number组件的选项，min、max、step                             |
-| onChangeEvent  | Function                                                     | 控件的值改变事件 可用于控件间联动                            |
-| onSearchEvent  | Function                                                     | select选择器搜索事件 可用于更新备选集合                      |
-| defaultLabel   | any                                                          | select选择器不初始化的时候可以使用defaultLabel搭配value，设置默认值 |
-| preserveNumber | number                                                       | 需要保留小数的列的位数                                       |
-
-#### ColorOption
-
-| 参数  | 类型   | 说明 |
-| ----- | ------ | ---- |
-| *name | string | 字段 |
-| color | string | 颜色 |
-
-#### ExplainOption
-
-| 参数  | 类型   | 说明     |
-| ----- | ------ | -------- |
-| *name | string | 字段     |
-| *show | string | 是否显示 |
-| color | string | 颜色     |
-
-#### InputNumber
-
-| 参数 | 类型   | 默认值   | 说明   |
-| ---- | ------ | -------- | ------ |
-| min  | number | 0        | 最小值 |
-| max  | number | 99999999 | 最大值 |
-| step | number | 1        | 步阶   |
-
-#### SelectOption
-
-| 参数                       | 类型       | 默认值 | 说明                                                         |
-| -------------------------- | ---------- | ------ | ------------------------------------------------------------ |
-| *label                     | string     |        | label字段，取selectList数组中的某个字段作为选择器label       |
-| *value                     | string     |        | Value字段，取selectList数组中的某个字段作为选择器value       |
-| selectList                 | Array<any> |        | 选项列表                                                     |
-| selectListName             | String     |        | 选项列表为数据object的某个字段的时候，增加hide viewdom，selectListName设置为该hide  viewdom的name |
-| showLabelAndValue          | boolean    | false  | 选项同时展示label和value，格式：[value]label                 |
-| hdDropdownMatchSelectWidth | boolean    | false  | 选择框长度是否和控件长度保持一致，默认不保持                 |
-
-## 11、间隔(hd-space)
-
-### 效果图(组件间的空白区域)
-
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-space.png)
-
-### 示例
-
-```html
-<hd-space background="#fff" type="row" size="12"></hd-space>
+### HdTableColumn（表格列）
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| title / name | string | — | 列标题 / 字段名 |
+| width / minWidth | number | — | 列宽 / 最小列宽 |
+| align | string | left | 对齐方式 |
+| color | string | — | 文字颜色 |
+| fixed / fixedWidth | — | — | 固定列 |
+| isShow | boolean | true | 设置列可见性 |
+| canSort / canWarp | boolean | false | 排序 / 换行 |
+| isState | boolean | false | 是否按状态列渲染，取值字段为 `name` |
+| stateField | string | — | 状态列取值字段（`name` 为 `state` 且未设置 `isState` 时生效，默认 `state`） |
+| render / click | Function | — | 渲染 / 点击 |
+| btnList | OperateBtn[] | — | 操作按钮 |
+
+#### OperateBtn（操作列按钮）
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ---- | ---- | ------ | ---- |
+| name | string | — | 按钮文案 |
+| showConfirm | boolean \| (line) => boolean | false | 是否 popconfirm 确认；传函数时按行数据判断 |
+| isRepeat | boolean | false | 与其他按钮互斥显示 |
+| click | (line) => void | — | 点击回调 |
+| permission | (line) => boolean | — | 是否显示 |
+
+#### HdTableTotalOption（hd-table 底部合计）
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| columnNumber | number | 总列数 |
+| insertIndex | number | 插入列下标 |
+| insertName | string | 合计字段名 |
+
+#### TotalOption（明细合计行）
+
+用于 `hd-detail-lines`、`hd-detail-lines-page`、`hd-form-lines`。
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| insertIndex | number | 插入列下标（从 1 开始） |
+| insertValue | any | 合计值 |
+| align | string | 对齐方式 |
+| showDecimal | boolean | 始终显示小数 |
+| isHide | boolean | 隐藏该合计列 |
+
+#### TableTotalOption（hd-current-table 合计，已弃用）
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| columnNumber | number | 总列数 |
+| insertIndex | number | 插入列下标 |
+| insertName | string | 合计字段名 |
+
+---
+
+## 附录：ColWidth 列宽常量
+
+```typescript
+import { ColWidth } from 'fantasy-ngzorro';
+
+ColWidth.tableImageColWidth    // 25   表格单图标
+ColWidth.tableTwoImageColWidth  // 40   表格双图标（Select 表格下拉）
+ColWidth.billNumberColWidth    // 150  单号
+ColWidth.nameColWidth          // 150  名称
+ColWidth.codeColWidth          // 100  代码
+ColWidth.codeNameColWidth      // 200  [code]name
+ColWidth.enumColWidth          // 100  枚举
+ColWidth.dateColWidth          // 100  日期
+ColWidth.dateTimeColWidth      // 150  日期时间
+ColWidth.dateRangeWidth        // 200  日期范围
+ColWidth.operateColWidth       // 150  操作列
+ColWidth.numberColWidth        // 100  数字
+ColWidth.remarkColWidth        // 250  备注
+ColWidth.fixColWidth           // 150  通用固定宽
+ColWidth.maxColWidth           // 350  超长省略展开
 ```
 
-### 说明
-
-| 参数       | 类型      | 默认值    | 说明                    |
-| ---------- | --------- | --------- | ----------------------- |
-| background | string    | 'inherit' | 加载中                  |
-| type       | SpaceType |           | 类型，'row' \| 'column' |
-| size       | number    |           | 高度 \| 宽度            |
-
-## 12、小标题(hd-tip)
-
-### 效果图
-
-![hd-button](../../../../../海鼎/code/fantasy-ngzorro-project/projects/fantasy-ngzorro/readme/img/hd-tip.png)
-
-### 示例
-
-```html
-<hd-tip title="基本信息" [fontSize]="14"></hd-tip>
-<hd-tip title="新增" [showIcon]="false" [fontSize]="16"></hd-tip>
+## 附录：Page 分页结构
+
+```typescript
+class Page<T> {
+  totalPages: number;
+  totalElements: number;
+  pageNumber: number;   // 从 0 开始
+  pageSize: number;
+  hasContent: boolean;
+  hasNext: boolean;
+  content: T[];
+}
 ```
-
-### 说明
-
-| 参数     | 类型   | 默认值 | 说明                   |
-| -------- | ------ | ------ | ---------------------- |
-| showIcon | boolen | true   | 是否显示前面的竖线icon |
-| fontSize | number |        | 字体大小               |
-| title    | string | False  | 标题文案               |
-
-## TODO
-
-- [x] 文档示例
-- [x] 更新记录
-- [x]