[TOC]

Fantasy-Ngzorro

基于 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 | 操作日志 | | 17 | hd-accessory-list | 附件列表（分组标签 + 可下载文件行） |

配置类型（SelectOption、FormItem、HdTableColumn 等）见 附录：公共配置类型。

更新记录

| 更新人 | 更新时间 | 更新内容 | | ------ | -------- | -------- | | — | 2026-10-24 | hd-table：勾选列支持 selectType="radio" 单选（默认仍为 checkbox 多选）（2.2.24） | | — | 2026-10-23 | hd-form-lines：筛选结果中点「添加/复制」不再把当前可见行重复写入全量数据（2.2.23） | | — | 2026-10-20 | hd-table：行内 Select 支持 onOpenChangeEvent / onSearchEvent（对齐 form-lines；可 return 数组/Promise/Observable 由组件写回并刷新）（2.2.22） | | — | 2026-10-13 | hd-table：showColSettings（默认 true）可关闭列设置；hd-filter：可见条件 ≤2 自动加宽且整行占满 100%；hd-form-lines：全局搜索时左侧按钮紧挨搜索框（2.2.21） | | — | 2026-10-12 | hd-form-lines / hd-detail-lines：全局搜索框 width 改挂 nz-input-group，修复放大镜贴到最右侧（2.2.20） | | — | 2026-10-9 | hd-button-group：左侧区域 flex:1，tableLeftButton 等内容可占满右侧按钮前的剩余宽度（2.2.19） | | — | 2026-10-9 | hd-filter：新增 hidePadding，为 true 时去掉 .hd-filter-container 的 padding（2.2.18） | | — | 2026-10-8 | hd-filter：Select / MultipleSelect 支持 onOpenChangeEvent（展开先清空 selectList）；多选空态光标与 placeholder 左对齐（2.2.16） | | — | 2026-10-8 | hd-table：列能放下时不误开横滚；合计行仅在表体有竖滚条时预留右槽，窗口/容器缩放后自动重算对齐（2.2.15） | | — | 2026-10-8 | hd-table：底部合计行走 nzFooter（分页之上、不进虚拟滚动）；tableTotalOption 共用 TotalOption；列未撑满与横滚两套对齐；序号列固定宽（2.2.14） | | — | 2026-10-3 | hd-form-lines：enableKeyboardOperate=false 时 Select 选中后不再自动聚焦下一个控件（2.2.13） | | — | 2026-10-3 | hd-table：横向滚动时表头/表体 table 改为 table-layout: fixed，修复表体单元格内容超宽把列撑开导致表头表体列线错位（2.2.12） | | — | 2026-10-3 | hd-filter：筛选组进页只请求一次（跳过 ngOnChanges firstChange，避免与 ngOnInit 重复导致首次请求被取消）（2.2.11） | | — | 2026-10-3 | hd-status：补充对账/登记/付款状态色（未对账、对账中、已对账、未登记、已登记、未付款、可付款、可对账）（2.2.10） | | MC | 2023-2-10 | Readme 创建；按钮、按钮组、通用表格、筛选器、状态、详情头、详情单头、详情明细文档 | | MC | 2023-2-13 | 表单、明细表单、间隔、小标题文档；组件字段增加必填说明 | | — | 2026-5-20 | 补充 hd-table、hd-detail-lines-page 等组件；完善公共子类型（SelectOption、FormItem 等）文档 | | — | 2026-9-18 | hd-form-lines 选中回显（nzHide）认 showLabelAndValue，与下拉 [value]label 一致（对齐 hd-form） | | — | 2026-9-18 | hd-detail-lines-page 对齐 hd-table 支持虚拟滚动（virtualScroll / virtualItemSize）；千行勾选时减少 DOM 卡顿 | | — | 2026-9-21 | hd-table 列支持 rowNo：字段值后竖线展示行号，前面字段仍可超链接 | | — | 2026-9-22 | hd-form-lines 支持列设置（showColSettings，默认关，需展示时手工传 true）：仅非 hide 的 ViewDom 可显隐，禁止调序；可选 uuid 缓存 | | — | 2026-9-22 | hd-tip 支持右侧展开/收起（showCollapse / [(expanded)]），暴露 expand / collapse / toggle 供父组件控制其它区块 | | — | 2026-9-22 | hd-form-lines 勾选提示改为 tableTotal 插槽（同 hd-table），组件内不再默认渲染已选中块 | | — | 2026-10-1 | hd-table 支持轻量行内编辑：editType（input / inputNumber / select）+ (cellChange)；Select 双写 value/label，事件带 previous* 供接口失败回滚 | | — | 2026-9-22 | hd-table / hd-detail-form 字段值后支持编辑笔图标（editable + edit 回调，图标对齐 Figma） | | — | 2026-9-28 | hd-detail-lines / hd-detail-lines-page：CSS 纵滚场景下提高冻结列表头 z-index，修复横滚盖住冻结列名 | | — | 2026-9-28 | hd-detail-lines / hd-detail-lines-page：仅有 scroll.x 时用 CSS max-height 做表内纵滚（不补 nzScroll.y），修复无列宽多行平铺无法纵滚，同时避免拆表头错位 | | — | 2026-9-28 | hd-filter：可选筛选组（enableFilterScheme / filterSchemeKey + HD_FILTER_SCHEME_STORE），支持切换/保存为当前/另存为/删除 | | — | 2026-9-29 | hd-filter 筛选组：弹窗标题「保存筛选组」；操作下拉「删除」红色；操作无左右 padding；选择/另存为改 hd-form；长名称省略；按钮顺序与间距对齐稿面 | | — | 2026-9-30 | hd-filter 筛选组：选择/保存弹窗宽度 560px；筛选组名称 maxLength 50 | | — | 2026-10-1 | hd-accessory-list：某分组 accessoryList 为空时仍展示分组标签，内容显示「暂无附件」（2.2.8） | | — | 2026-9-30 | hd-filter：筛选组弹窗未打开时不渲染空 hd-form；hd-form 空 formList 时初始化空 FormGroup，修复列表页 formGroup 报错（2.2.7） | | — | 2026-9-24 | hd-detail-lines / hd-detail-lines-page：恢复历史默认 scroll={x:'1px'}；不再自动补 scroll.y（仅父组件显式传 y，或 page 虚拟滚动才设 y）；去掉 table-layout:fixed。对齐 2.1.64 前无列宽自适应 | | — | 2026-9-24 | hd-detail-lines / hd-detail-lines-page：横滚时加固表头/表体 scrollLeft 同步与 table-layout: fixed，修复列名与列值不对齐 | | — | 2026-9-24 | hd-detail-lines：补 scroll.y 后重建表格并同步表头横滚，修复列头不跟随左右滚动 | | — | 2026-9-24 | hd-detail-lines / hd-detail-lines-page：自动或仅传 scroll.x 时补 scroll.y，修复窄屏下无法纵向滚动 | | — | 2026-9-22 | hd-table 支持 pagination / frontPagination：全量 content 可「不分页展示」或「前端切片分页」，列表默认仍为服务端分页 | | — | 2026-9-21 | hd-table 列 color 支持函数，按行给某一个字段标红 | | — | 2026-9-20 | hd-detail-form 附件图片：最多展示 4 张，超出末张蒙版 +n；弹窗预览支持左右翻页 | | — | 2026-9-20 | hd-detail-form 附件图片点击弹窗预览大图（不再 window.open） | | — | 2026-9-20 | hd-detail-form 支持附件图片字段（HdDetailFormFieldType.Accessory，Figma 48×48 缩略图横排，不复用 hd-accessory-list） | | — | 2026-9-17 | hd-table / hd-detail-lines / hd-detail-lines-page 支持 selectDisabledField / rowInvalidField：按行字段控制勾选禁用、失效行样式 | | — | 2026-9-14 | 新增 hd-accessory-list 附件列表组件（分组 name + accessoryList，点击下载/查看） | | — | 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-9-8 | hd-form 支持 FormListType.RegionAddress（省市区级联 + 详细地址，双 FormControl，固定占 2 列） | | — | 2026-9-9 | hd-detail-form 默认固定一行 4 列；HdOption.width 支持占列（默认 1，最大 4） | | — | 2026-8-6 | hd-form-lines：allowEmpty + 仅删除按钮时初始化不补空行、可删至 0 行；分页页码删空校正；ViewDom 字号 14px | | — | 2026-8-26 | hd-table 默认开启虚拟滚动（virtualScroll / virtualItemSize）；文档补齐 | | — | 2026-8-25 | hd-status：statusToColor 按 sunan-server 业务状态枚举全量去重补充（排除银行 / AGV / HTTP StatusCode） | | — | 2026-8-21 | 分页选项统一增加 500 / 1000；hd-table / hd-detail-lines / hd-detail-lines-page 默认 tablePageSize 改为 100 | | — | 2026-9-14 | TotalOption 增加 preserveNumber（合计小数位数，不传默认 2）；用于 hd-detail-lines / hd-detail-lines-page / hd-form-lines | | — | 2026-9-14 | hd-table：普通列支持文案后挂 btnList 操作按钮；OperateBtn.name 支持按行动态文案 |

前言

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'。

公共导出

| 模块 | 说明 | | ---- | ---- | | FantasyNgzorroModule | 根模块，业务侧统一引入 | | ColWidth | 列宽常量 | | Page<T> | 分页数据结构 | | Utils | 精度计算工具 | | HdOverlayCleanupService | 清理残留 tooltip/overlay（引入模块后自动生效） | | HdTableColumn / FormLine / Filter 等 | 各组件配置类型，详见 附录：公共配置类型 |

1、按钮（hd-button）

示例

<hd-button type="primary" (clickAction)="search()">查询</hd-button>
<hd-button type="default" [loading]="loading" (clickAction)="save()">保存</hd-button>

参数

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | type | string | default | primary | dashed | danger | default | link | reset | add | | size | string | normal | 按钮尺寸 | | loading | boolean | false | 加载中（与 loading 配合时必须用 clickAction / nzOnConfirm） | | disabled | boolean | false | 是否禁用；loading 时也会禁用 | | clickAction | EventEmitter | — | 点击事件 | | nzOnConfirm | EventEmitter | — | 确认类点击事件（与 clickAction 二选一亦可） |

注意点

• 禁止使用 type="submit"，请用普通按钮 + clickAction 触发表单提交。
• 设置了 loading 的按钮必须用 (clickAction) 或 (nzOnConfirm)，不能用 (click)。

2、按钮组（hd-button-group）

示例

<hd-button-group>
  <ng-template #buttonGroupLeft>
    <hd-button type="add">新增</hd-button>
  </ng-template>
  <ng-template #buttonGroupRight>
    <hd-button type="default">导出</hd-button>
  </ng-template>
</hd-button-group>

插槽

| 插槽 | 说明 | | ---- | ---- | | buttonGroupLeft | 左侧按钮区 | | buttonGroupRight | 右侧按钮区 |

按钮间距自动 12px。

3、间隔（hd-space）

示例

<hd-space background="#fff" type="row" size="12"></hd-space>

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | background | string | inherit | 背景色 | | type | string | row | row | column | | size | number | — | 高度或宽度（px） |

4、小标题（hd-tip）

示例

<hd-tip title="基本信息" [fontSize]="14"></hd-tip>
<hd-tip title="新增" [showIcon]="false" [fontSize]="16"></hd-tip>

<!-- 右侧展开/收起：父组件控制其它区块显隐 -->
<hd-tip #basicTip title="基本信息" showCollapse [(expanded)]="showBasicBlock"></hd-tip>
<div *ngIf="showBasicBlock">…其它内容…</div>

<!-- 或 ViewChild 调用 -->
<!-- this.basicTip.expand() / collapse() / toggle() -->

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | title | string | — | 标题文案 | | showIcon | boolean | true | 是否显示左侧竖线 | | fontSize | number | — | 字体大小 | | showCollapse | boolean | false | 是否在右侧显示展开/收起 | | expanded | boolean | true | 当前是否展开；可 [(expanded)] 双向绑定 | | expandedChange | EventEmitter<boolean> | — | 展开状态变化 |

暴露方法（ViewChild）

| 方法 | 说明 | | ---- | ---- | | expand() | 展开，并触发 expandedChange | | collapse() | 收起，并触发 expandedChange | | toggle() | 切换，并触发 expandedChange |

hd-tip 本身不包裹内容块，由父组件根据 expanded / 方法结果自行控制其它区域的 *ngIf 等显隐。

5、状态（hd-status）

示例

<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 配置 |

匹配时不区分大小写。未命中时圆点默认为灰色 #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 与中文枚举名。

6、气泡确认（hd-popconfirm）

示例

<hd-popconfirm message="确认删除该记录吗？" (confirmOption)="onConfirm()" (cancelOption)="onCancel()">
</hd-popconfirm>

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | message | string | 提示文案 | | confirmOption | EventEmitter | 点击确认 | | cancelOption | EventEmitter | 点击取消 |

7、筛选器（hd-filter）

示例

<hd-filter [filterList]="filterList" (searchEvent)="filterChange($event)" (resetEvent)="resetFilterChange($event)">
</hd-filter>

筛选组（可选，默认关闭；需业务仓 provide HD_FILTER_SCHEME_STORE）：

<hd-filter
  [filterList]="filterList"
  [enableFilterScheme]="true"
  [filterSchemeKey]="'erp.offerPlan.list'"
  (searchEvent)="filterChange($event)">
</hd-filter>

本地 Demo（npm start）在「筛选器 · 筛选组」区块有可操作示例，使用内存 DemoFilterSchemeService。

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | filterList | Array<Filter> | 筛选项配置 | | enableFilterScheme | boolean | 是否启用筛选组，默认 false | | filterSchemeKey | string | 筛选器标识；开启筛选组时必传 | | hidePadding | boolean | 去掉 .hd-filter-container 的 padding，默认 false | | （布局） | — | 可见筛选项 ≤2 个时自动加宽字段列（1 个 → nzSpan=18，2 个 → nzSpan=9），查询/重置仍占 6；≥3 个与现网一致（nzSpan=6 + computeOffset） | | searchEvent | EventEmitter | 查询，带回筛选数据 | | resetEvent | EventEmitter | 重置 |

Filter 配置

筛选项使用 Filter 类型，下拉/数字/级联等子配置见 SelectOption、InputNumber、CascaderOption。

8、通用表格（hd-current-table）(已废弃、禁用)

适用于完全自定义表头、表体模板的列表页。

示例

<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>配送单号</th>
    <th>状态</th>
  </ng-template>
  <ng-template #tableBody let-data>
    <td>{{ data.billNumber }}</td>
    <td><hd-status [status]="data.state">{{ data.stateText }}</hd-status></td>
  </ng-template>
</hd-current-table>

page: Page<any> = new Page();
pageIndex = 1;
pageSize = 10;
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.service.query(this.queryFilter).subscribe(
    result => { this.loading = false; this.page = result; },
    () => { this.loading = false; }
  );
}

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | tableData | Page<any> | — | 分页数据；非分页时 content 放全量，totalElements 建议等于 content.length | | pagination | boolean | true | 是否显示分页；false 时一次展示全部 content | | frontPagination | boolean | false | 前端分页：对 content 全量切片，翻页不触发 tableSearchEvent。详情全量数据时与 pagination 搭配：pagination=false 全展示，pagination=true + frontPagination 前端分页。列表服务端分页保持默认即可（frontPagination 不传） | | tablePageIndex | number | 1 | 当前页（双向绑定）；pagination=false 时无意义 | | tablePageSize | number | 10 | 每页条数（双向绑定） | | tableLoading | boolean | false | 加载状态 | | tableSearchEvent | EventEmitter | — | 翻页 / 改 pageSize 触发，参数 reset 表示是否重置到第一页 | | 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）

在通用表格基础上支持列配置渲染、排序、列宽/顺序/pageSize 本地缓存、设置列等能力。列表页优先推荐使用。

示例

<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>

tableCols: HdTableColumn[] = [{
  title: '配送单号',
  name: 'billNumber',
  fixed: 'left',
  click: (line) => { /* 点击行 */ },
  // 按行控制是否显示为超链接（例如仅有网址时才可点）
  // canClick: (line) => !!line.url
}, {
  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: 'autoReport',
  width: 140,
  render: (line) => (line.autoReport ? '是' : '否'),
  // 普通列挂 btnList：文案后跟操作按钮（见 Figma 操作列单元格）
  btnList: [{
    name: (line) => (line.autoReport ? '解除' : '设置'),
    click: (line) => { line.autoReport = !line.autoReport; }
  }]
}, {
  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) }]
}];

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | tableCols | HdTableColumn[] | [] | 列配置 | | tableData | Page<any> | — | 数据；服务端分页时为当前页；全量场景 content 放全部行 | | pagination | boolean | true | 是否显示分页；false 一次展示全部 content | | frontPagination | boolean | false | 前端分页：对 content 切片，翻页不触发 tableSearchEvent。详情全量数据：[pagination]="x" frontPagination，切 x 即可在「全展示 / 前端分页」间切换。列表保持默认（不传）即为服务端分页 | | tablePageIndex | number | 1 | 当前页（双向绑定）；pagination=false 时可忽略 | | tablePageSize | number | 100 | 每页条数（双向绑定）；外面传入会覆盖默认值；非分页时可忽略 | | tableLoading | boolean | false | 加载状态 | | tableSearchEvent | EventEmitter | — | 翻页查询 | | tablePageSizeChange | EventEmitter | — | pageSize 双向绑定同步 | | tablePageSizeChangeEvent | EventEmitter | — | pageSize 变化（含缓存恢复），常用于重新查询 | | sortEvent | EventEmitter | — | 排序 | | selectEvent | EventEmitter | — | 勾选变化 | | cellChange | EventEmitter<HdTableCellChange> | — | 行内编辑变更（已写回行对象；含 previous* 供接口失败回滚） | | showSelected | boolean | false | 勾选列 | | selectType | 'checkbox' | 'radio' | checkbox | 勾选形态。radio 为单选：无表头全选，选中新行会清掉其它行；selectEvent 仍回传数组（0 或 1 条） | | selectField | string | billNumber | 勾选主键字段 | | selectDisabledField | string | — | 行勾选禁用字段名；行数据该字段为 true 时禁用勾选（全选也会跳过） | | rowInvalidField | string | — | 行失效字段名；为 true 时整行背景 #F7F8FA、普通文字 #868A9C（操作按钮/超链接颜色不变） | | showOperateColWarpButton | boolean | false | 展开/缩略显示换行列 | | showColSettings | boolean | true | 是否展示列设置（齿轮）；弹窗等场景可传 false 关闭 | | virtualScroll | boolean | true | 行数多自动虚拟滚动；横向滚动条按列总宽是否超出容器决定 | | virtualItemSize | number | — | 虚拟滚动行高（px）；不传则首屏自动测量 | | showTableTotal | boolean | false | 底部合计行（nzFooter，固定在表体下方、分页上方，不进虚拟滚动数据）；开启后表内强制展示序号列，「合计」对齐序号列 | | tableTotalOption | TotalOption[] | — | 合计配置，与 hd-detail-lines 共用 TotalOption；未传 insertValue 时按 insertIndex 对应列对 content 求和 | | columnsNumber | number | string | — | 合计列总数（含序号列，与 detail-lines 一致）；不传则按可见数据列数 + 1 | | isFirstEntrySearch | boolean | — | 首次进入是否自动查询 | | isCrossPageSelect | boolean | — | 跨页勾选 | | uuid | string | — | 列缓存唯一标识（必填，用于 IndexedDB 缓存） | | tableLeftButton / tableRightButton / tableTotal | TemplateRef | — | 工具栏插槽 |

分页可选条数：10 / 50 / 100 / 200 / 500 / 1000。若本地缓存过该表 pageSize 且 > 10，初始化会优先使用缓存值并回写父组件（仅 pagination=true）。

非分页示例：

<!-- 不分页：一次展示全部 -->
<hd-table [pagination]="false" frontPagination
  [tableCols]="cols" [tableData]="linesPage" uuid="detail-lines-uuid"></hd-table>

<!-- 前端分页：对全量 content 切片 -->
<hd-table [pagination]="true" frontPagination [tablePageSize]="10"
  [tableCols]="cols" [tableData]="linesPage" uuid="detail-lines-uuid"></hd-table>

// content 放全量；totalElements 建议与 content.length 一致
linesPage = { content: lines, totalElements: lines.length };

HdTableColumn 配置

列定义见 HdTableColumn、OperateBtn、TotalOption。

当 name 为 state 或 isState 为 true 时，列内容使用 hd-status 渲染。取值规则：isState 时取 data[name]；否则可通过 stateField 指定字段，未配置时默认取 state。

10、表单（hd-form）

示例

<hd-form [formList]="formInput" (changeEvent)="formChangeEvent($event)"></hd-form>

formInput: FormItem[] = [{
  type: FormListType.Input,
  label: '配送单号',
  name: 'billNumber',
  require: true,
  width: 2,
  onChangeEvent: this.formInputChange.bind(this)
}, {
  type: FormListType.Select,
  label: '是否启用',
  name: 'enabled',
  width: 1,
  selectOption: { value: 'value', label: 'label', selectList: [...] }
}, {
  type: FormListType.Input,
  label: '金额',
  name: 'amount',
  prefix: '¥' // 前缀文字，对应 nz-input-group nzPrefix
}, {
  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: FormListType.Checkbox,
  label: '是否启用',
  name: 'enabled',
  value: false // 单个复选框，值为 boolean
}, {
  type: FormListType.Checkbox,
  label: '权限',
  name: 'permissions',
  value: ['read'],
  checkboxOption: {
    label: 'name',
    value: 'code',
    optionList: [
      { code: 'read', name: '查看' },
      { code: 'edit', name: '编辑' }
    ]
  }
}, {
  type: FormListType.RegionAddress,
  label: '场所地址',
  name: 'region',                 // 省市区 string[]
  addressName: 'addressDetail',   // 详细地址 string
  require: true,                  // 两边同时必填；固定占 2 列
  cascaderOption: { options: cityOptions },
  addressPlaceholder: '请输入详细地址'
}];

// 编辑回填（两个平级字段）
// this.hdForm.validateHdForm.patchValue({
//   region: ['上海', '上海市', '浦东新区'],
//   addressDetail: '张江路 88 号',
// });

formChangeEvent(validateForm: FormGroup) {
  this.validateHdForm = validateForm;
}

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | formList | FormItem[] | 表单项配置 | | changeEvent | EventEmitter | 表单值变化，返回 FormGroup |

FormItem 配置

表单项使用 FormItem 类型，下拉/数字等子配置见 SelectOption、InputNumber、RadioOption、CheckboxOption。

11、明细表单（hd-form-lines）

可编辑的明细行表格，支持键盘导航、行内搜索、勾选批量填充、合计等。

示例

<hd-form-lines #hdFormLines showSearch showCheckbox showKeyboardOperateTip
  uuid="demo-form-lines-col-settings"
  [formLines]="formLines" [formLinesData]="formLinesData"
  [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>
  <!-- 勾选提示等同 hd-table 的 tableTotal，放在表格上方 -->
  <ng-template #tableTotal>
    <nz-alert *ngIf="hdFormLines.getSelectedCount() > 0" nzType="info"
      [nzMessage]="formLinesAlertTpl" nzShowIcon></nz-alert>
    <ng-template #formLinesAlertTpl>
      <span>已选择{{ hdFormLines.getSelectedCount() }}条数据</span>&nbsp;&nbsp;
      <span class="common-btn-group">
        <a (click)="hdFormLines.clearSelection()">清空</a>
      </span>
    </ng-template>
  </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'] | 操作按钮：add / copy / delete | | showDeleteConfirm | boolean | false | 删除前确认 | | showSearch | boolean | false | 行内搜索 | | showCheckbox | boolean | false | 行勾选列（用于批量操作） | | showColSettings | boolean | false | 是否展示列设置（齿轮，位置同 hd-table）；默认不展示，需要时页面手工 [showColSettings]="true"；仅 非 hide 的 ViewDom 可配置显示/隐藏，不可拖拽调序 | | uuid | string | — | 列设置缓存标识；有值时按用户+路由持久化到 IndexedDB | | enableKeyboardOperate | boolean | true | 键盘操作（方向键 / 回车跳格、Select 选中后自动跳到下一个控件）；为 false 时全部关闭 | | showKeyboardOperateTip | boolean | false | 键盘操作提示 | | showLineNumber | boolean | true | 序号列 | | tableLoading | boolean | false | 加载状态 | | allowEmpty | boolean | true | 是否允许空表（见下方说明） | | showTotal | boolean | false | 合计行 | | totalOption / columnsNumber | — | — | 合计配置 | | scroll | object | { x: '1px' } | 横向滚动 | | changeEvent | EventEmitter | — | 表单变化 | | selectionChange | EventEmitter<FormGroup[]> | — | 勾选变化 | | deleteLastLineEvent | EventEmitter | — | allowEmpty=false 时删除最后一行 | | deleteLineEvent | EventEmitter | — | 删除行事件 |

插槽

| 插槽 | 说明 | | ---- | ---- | | formLinesLeftButton | 工具栏左侧自定义按钮（同 hd-table 的 tableLeftButton） | | formLinesRightButton | 工具栏右侧自定义按钮 | | tableTotal | 表格上方自定义区域（同 hd-table）；勾选提示等由业务自行放入，组件内不再默认渲染 | | ViewDomRightTemplate | ViewDom 列右侧自定义模板，上下文：formItem、formLine |

allowEmpty 行为

| 场景 | 行为 | | ---- | ---- | | allowEmpty=false | 不能删掉最后一行，触发 deleteLastLineEvent | | allowEmpty=true 且操作列含 add/copy | 删空后会自动补一行空行 | | allowEmpty=true 且操作列仅有 delete | 初始化空数据不补空行；可删至 0 行；外部可通过 addFormLine() 新增 |

FormLine 配置

明细列使用 FormLine 类型，含 ColorOption、ExplainOption 及表格型 SelectOption。

开启 showKeyboardOperateTip 后支持 [↑][↓][←][→]、Enter 在单元格间跳转；InputNumber 上下键用于跳转，不触发 step 增减。

表格分页可选条数：10 / 50 / 100 / 200 / 500 / 1000。

暴露方法

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: '批量备注' }); // 批量填充勾选行字段

12、详情头（hd-detail-tip）

示例

<hd-detail-tip state="shipped" stateText="配送中" billNumber="202111030001"></hd-detail-tip>

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | state | string | 状态值 | | stateText | string | 状态文案 | | billNumber | string | 单号 | | tip | string | 前缀文案，默认「详情」 |

13、详情单头（hd-detail-form）

示例

<hd-detail-form [formCols]="formCols" (imageClick)="onDetailFormImageClick($event)"></hd-detail-form>

import { HdDetailFormFieldType, HdOption } from 'fantasy-ngzorro';

formCols: HdOption[] = [
  { label: '收货单号', value: '202111030001' },
  { label: '地址', value: '江苏/南京市/玄武区 某某路', width: 2 },
  { label: '备注', value: '...' },
  // 附件图片：label + 图片地址列表（Figma 48×48 缩略图横排）
  {
    label: '食品经营许可证',
    type: HdDetailFormFieldType.Accessory,
    width: 2,
    value: [
      { name: '正面', path: 'https://oss.xxx.com/a.png' },
      { name: '背面', path: 'https://oss.xxx.com/b.png' },
      'https://oss.xxx.com/c.png', // 也支持纯地址字符串
    ],
  },
];

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | formCols | HdOption[] | — | 展示字段，见 HdOption | | nzColumn | number | object | 4 | 一行列数，默认固定 4 列 | | imageClick | EventEmitter | — | 附件图片点击回调 { image, path, index }（type=accessory 时） |

附件字段 type: HdDetailFormFieldType.Accessory（或 'accessory'）：

• 对齐 Figma items/description-cell「图片」：标签 + 48×48 缩略图横排（间距 6px，边框 #E5E6EB，圆角 4px）；标签与首图顶对齐
• value 支持：图片地址 string / string[]，或 { name?, path?/url? }[]
• 最多直接展示 4 张；超出时第 4 张蒙版显示 +n（n 为剩余张数）
• 点击缩略图弹窗预览大图（支持左右翻页），并触发 imageClick
• 无图时展示 <空>
• 不使用 hd-accessory-list（文件列表样式请用独立附件列表组件）

14、详情明细（hd-detail-lines）

详情页只读/轻编辑明细表格，支持前端分页和行内搜索。

示例

<!-- 带搜索 + 前端分页 -->
<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>

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | lines | any[] | — | 明细数据 | | scroll | object | { x: '1px' } | 横向滚动。默认 { x: '1px' }（开启横滚、列宽自适应）；传 null 则按列宽自动测算。不要默认补 scroll.y（会拆表头导致无列宽错位）；仅有 x 时由组件 CSS 限制表体高度实现纵滚。需要分体固定表头时再显式传 y | | showSearch | boolean | false | 行内搜索 | | searchFields | string[] | [] | 搜索字段，空则搜全部字段 | | hdFrontPagination | boolean | false | 前端分页 | | tablePageSize | number | 100 | 每页条数（开启前端分页时生效） | | showSelected | boolean | false | 勾选 | | selectField | string | billNumber | 勾选主键 | | selectDisabledField | string | — | 行勾选禁用字段名；行数据该字段为 true 时禁用勾选（全选也会跳过） | | rowInvalidField | string | — | 行失效字段名；为 true 时整行背景 #F7F8FA、普通文字 #868A9C（操作按钮/超链接颜色不变） | | selectedField | string | — | 初始勾选标记字段 | | selectEvent | EventEmitter | — | 勾选变化 | | allowDrop | boolean | false | 拖拽排序 | | showTotal | boolean | false | 合计行 | | columnsNumber | number | — | 总列数（含合计） | | totalOption | TotalOption[] | — | 合计配置，见 TotalOption | | detailLineHead / detailLineBody | TemplateRef | — | 表头 / 表体插槽 |

分页可选条数：10 / 50 / 100 / 200 / 500 / 1000。

15、详情明细-服务端分页（hd-detail-lines-page）

与 hd-detail-lines 模板用法相同，但不做内部分页和搜索，分页由父组件控制（对齐 hd-table）。

示例

<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>
  </ng-template>
  <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-page>

detailLinesPageData: Page<any> = new Page();
detailLinesPageIndex = 1;
detailLinesPageSize = 100;
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();
}

onDetailLinesPageSizeChange(pageSize: number) {
  this.detailLinesPageSize = pageSize;
  this.loadDetailLinesPage(true);
}

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | lines | any[] | [] | 当前页数据（也可用 tableData.content） | | tableData | Page<any> | — | 分页对象，提供 totalElements | | tablePageIndex | number | 1 | 当前页 | | tablePageSize | number | 100 | 每页条数 | | tableLoading | boolean | false | 加载状态 | | tablePageIndexChange | EventEmitter | — | 页码变化 | | tablePageSizeChange | EventEmitter | — | 每页条数变化（组件内会重置到第 1 页） | | pageChange | EventEmitter | — | 任意分页变化 | | showSelected / allowDrop / showTotal / selectDisabledField / rowInvalidField 等 | — | — | 同 hd-detail-lines；allowDrop 开启时虚拟滚动自动关闭 | | virtualScroll | boolean | true | 与 hd-table 一致：当前页行数多（或已设 scroll.y）时自动虚拟滚动，减轻千行勾选卡顿 | | virtualItemSize | number | — | 虚拟滚动行高；不传则默认/自动测量 | | isCrossPageSelect | boolean | — | 跨页勾选 |

分页可选条数：10 / 50 / 100 / 200 / 500 / 1000。模板中 index 为全局序号：(pageIndex - 1) * pageSize + 行号。

与 hd-detail-lines 选型

| 场景 | 推荐组件 | | ---- | -------- | | 数据量小、前端筛选/分页 | hd-detail-lines | | 接口分页、数据量大 | hd-detail-lines-page |

16、操作日志（hd-log）

基于 hd-detail-lines 封装的日志展示，内置列：时间、操作人、事件、描述。

示例

<hd-log [logs]="logs"></hd-log>

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | logs | any[] | 日志列表，字段：createInfo.operateTime、createInfo.operatorName、event、describe |

也可作为 Modal 内容组件使用（entryComponents: HdLogComponent）。

17、附件列表（hd-accessory-list）

只读附件分组列表：上方标签（如「营业执照扫描件：」），下方灰色文件行；每行最多 4 个，超出自动换行；点击文件名下载/查看。某分组 accessoryList 为空时仍展示该分组标签，内容显示「暂无附件」。对齐 Figma「文件列表」样式。

示例

<hd-accessory-list
  [groups]="accessoryGroups"
  (fileClick)="onAccessoryFileClick($event)">
</hd-accessory-list>

import { HdAccessoryGroup } from 'fantasy-ngzorro';

accessoryGroups: HdAccessoryGroup[] = [
  {
    name: '营业执照扫描件',
    accessoryList: [
      { name: '文件名称.doc', path: 'https://oss.xxx.com/files/license.doc', size: 12 * 1024 * 1024 },
      { name: '副本.pdf', path: 'https://oss.xxx.com/a.pdf' }, // size 可缺省
    ],
  },
];

onAccessoryFileClick(e: { group: HdAccessoryGroup; file: any; path: string }) {
  console.log('下载', e.path);
}

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | groups | HdAccessoryGroup[] | [] | 分组数组，每项含 name + accessoryList | | labelColon | boolean | true | 标签后自动补「：」 | | autoOpen | boolean | true | 点击后默认 window.open 打开 | | fileClick | EventEmitter | — | 点击附件回调 { group, file, path } |

HdAccessoryGroup

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | name | string | 分组标签 | | accessoryList | HdAccessoryFile[] | 附件列表；空数组时展示「暂无附件」 |

HdAccessoryFile

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | name | string | 展示文件名 | | path | string | 完整下载/查看地址（由父组件直接传入） | | size | number | string | 可缺省；有值才展示。数字按字节格式化为 B/KB/MB，字符串原样展示 |

附录：公共配置类型

以下类型在 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（hd-form / hd-form-lines） | | hdDropdownMatchSelectWidth | boolean | false | 下拉宽度是否与控件一致 | | hdServerSearch | boolean | false | 是否远程搜索 | | hdShowSearch | boolean | true | 是否可搜索 | | hdAllowClear | boolean | true | 是否允许清空 | | hdShowItemCode | boolean | false | 已选展示是否带 [value] 前缀 | | tableColumns | SelectOptionTableColumn[] | — | 表格型下拉列配置（商品选择器等） |

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' }
  ]
}

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 格式） | | showSearch | boolean | CascaderShowSearchOptions | 是否开启搜索，默认 true；支持拼音字段匹配 | | pinyinField | string | 拼音字段名，默认 pinyin | | menuClassName | string | 下拉菜单额外 class | | menuStyle | object | 下拉菜单样式（对应 nzMenuStyle） | | dropdownMinWidth | number | string | 搜索结果下拉最小宽度；不传则不强制，按文案自适应（上限 560px） |

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 | 值；附件类型时为图片地址 string / string[] 或 { name?, path?/url? }[] | | type | string / HdDetailFormFieldType | 字段类型，默认文本；accessory 为附件图片缩略图 | | width | number | 占据列数，默认 1，最大 4；未传按 1 | | color | string | 文字颜色 | | hide | boolean | 是否隐藏 | | clickText | string | 可点击文案 | | click | (value) => void | 点击回调 | | editable | boolean | 值后显示编辑笔图标（Figma 14px） | | edit | (col) => void | 点击编辑笔回调，供父组件处理 |

Filter（筛选项）

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | type | FilterListType | — | 控件类型 | | label | string | — | 标签 | | name | string | — | 字段名（提交给后端的 key） | | value | any | null | 初始值 | | placeholder | string | — | 占位符 | | require | boolean | false | 是否必填 | | show | boolean | — | 是否显示 | | hdAllowClear | boolean | true | 是否允许清空；不传默认 true。Select 未配此项时可回退 selectOption.hdAllowClear | | selectOption | SelectOption | — | Select / MultipleSelect 配置 | | inputNumber | InputNumber | — | InputNumber 配置 | | cascaderOption | CascaderOption | — | Cascader 配置 | | showTime | boolean | false | Date 是否含时间 | | hdDisabledDate | Function | — | 不可选日期 (date) => boolean | | onChangeEvent | Function | — | 值变化 | | onSearchEvent | Function | — | 下拉搜索 | | onOpenChangeEvent | Function | — | 下拉展开/收起，回调 (open)；展开时组件会先清空当前 selectList，再回调，避免条件变化后请求返回前仍显示旧选项 | | onBlurEvent | Function | — | 失焦 | | onChangeEventDebounceTime | number | — | change 防抖（ms） | | onSearchEventEventDebounceTime | number | — | search 防抖（ms） | | onOpenChangeEventDebounceTime | number | — | openChange 防抖（ms）；未配置或为 0 时同步触发 |

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 | 隐藏字段 | | hdAllowClear | boolean | true | 是否允许清空；不传默认 true。Select 未配此项时可回退 selectOption.hdAllowClear | | 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 | — | 级联配置 | | addressName | string | — | RegionAddress：详细地址字段名（必填） | | addressValue | string | — | RegionAddress：详细地址初始值 | | addressPlaceholder | string | 请输入详细地址 | RegionAddress：详细地址占位符 | | addressMaxLength | number | — | RegionAddress：详细地址最大长度 | | 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 | RegionAddress

ValidatorKey

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | key | string | 校验规则 key | | label | string | 校验失败提示 |

FormLine（明细表单项）

在 FormItem 基础上用于行内编辑，额外字段：

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | type | FormLineType | — | 控件类型 | | align | string | — | 列对齐 left | right | center | | hideViewDomValue | boolean | false | ViewDom 隐藏 value（如只显示图片） | | isShow | boolean | true | 列设置可见性（仅非 hide 的 ViewDom 可由设置列切换） | | 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 字段参与搜索 | | defaultLabel | any | — | Select 未初始化时的默认展示文案 | | explainOption / explainOptionRight | ExplainOption | — | 说明文字（左 / 右） | | colorOption | ColorOption | — | 动态颜色 | | selectOption | SelectOption | — | 含 tableColumns 表格下拉 | | inputNumber | InputNumber | — | 数字框配置 | | onChangeEvent | Function | — | 值变化，签名见下 | | onSearchEvent | Function | — | 下拉搜索 | | onOpenChangeEvent | Function | — | 下拉展开/收起，回调 (open, line)，可按行请求 selectList；展开时组件会先清空当前 selectList / 行内 selectListName，再回调，避免条件变化后请求返回前仍显示旧选项 | | onChangeEventDebounceTime | number | — | change 防抖（ms），未配置或 0 为同步 | | onSearchEventEventDebounceTime | number | — | search 防抖（ms） | | onOpenChangeEventDebounceTime | number | — | openChange 防抖（ms） |

FormLineType 枚举

Input | Select | Date | DateRange | TextArea | InputNumber | MultipleSelect | ViewDom | Switch | Time

ColorOption / ExplainOption

| ColorOption | ExplainOption | | ----------- | ------------- | | name：hide 字段名存颜色 | show：是否显示 | | color：默认颜色 | name：hide 字段名存文案 | | | color：文字颜色 |

FormLine 事件签名

onChangeEvent: (value, line: FormGroup) => void
onSearchEvent: (keyword, line?: FormGroup) => void
onOpenChangeEvent: (open: boolean, line: FormGroup) => void

HdTableColumn（表格列）

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | title / name | string | — | 列标题 / 字段名 | | width / minWidth | number | — | 列宽 / 最小列宽 | | align | string | left | 对齐方式 | | color | string | (line) => string | — | 文字颜色。字符串为整列同色；函数按行返回颜色，标红可返回 #F5222D，不标色返回空 | | fixed / fixedWidth | — | — | 固定列 | | isShow | boolean | true | 设置列可见性 | | canSort / canWarp | boolean | false | 排序 / 换行 | | isState | boolean | false | 是否按状态列渲染，取值字段为 name | | stateField | string | — | 状态列取值字段（name 为 state 且未设置 isState 时生效，默认 state） | | render / click | Function | — | 渲染 / 点击 | | canClick | (line) => boolean | — | 按行控制是否可点 | | rowNo | boolean | string | — | 字段值后竖线 + 行号。true 为分页连续序号（从 1 起）；字符串为行数据字段名。前面的字段仍可用 click 做成超链接，行号不可点 | | editable | boolean | (line) => boolean | — | 值后显示编辑笔图标（Figma 14px）；函数按行控制。与 editType 互斥 | | edit | (line) => void | — | 点击编辑笔回调，供父组件处理（如弹窗改值） | | editType | 'input' | 'inputNumber' | 'select' | — | 行内编辑：该列常显控件；name 须为 string | | editDisabled | boolean | (line) => boolean | — | 禁用行内编辑 | | selectOption | SelectOption | — | editType=select 时用；选中后 line[name]=option[value]，若有 label 则再写 line[label]=option[label]；按行选项用 selectListName；远程搜索设 hdServerSearch | | onOpenChangeEvent | (open, line) => any | — | Select 展开回调；展开时先清空再回调；关闭不回调。可 return 数组 / Promise / Observable，由组件写回 options 并刷新（OnPush 下不必改 tableData 引用） | | onOpenChangeEventDebounceTime | number | 0 | 展开回调防抖（ms）；未配或 0 同步 | | onSearchEvent | (keyword, line) => any | — | Select 输入搜索；不清空 options；建议配合 hdServerSearch。同样可 return 数组 / Promise / Observable | | onSearchEventEventDebounceTime | number | 0 | 搜索防抖（ms）；命名对齐 form-lines；未配或 0 同步 | | inputNumber | InputNumber | — | editType=inputNumber 时的 min/max/step/precision | | placeholder | string | — | 输入框 / 下拉占位 | | btnList | OperateBtn[] | — | title 为「操作」时整列按钮；其他列时显示在单元格文案后的操作按钮 |

HdTableCellChange（行内编辑事件）

| 字段 | 说明 | | ---- | ---- | | line / col / name | 当前行、列配置、字段名 | | value / previousValue | 新值 / 变更前值（接口失败回滚用） | | label / previousLabel | Select 时新/旧文案字段值 | | option / previousOption | Select 时新/旧整条选项 |

接口失败回滚示例：

onTableCellChange(e: HdTableCellChange) {
  this.api.update(e.line).subscribe({
    error: () => {
      e.line[e.name] = e.previousValue;
      if (e.col.selectOption && e.col.selectOption.label) {
        e.line[e.col.selectOption.label] = e.previousLabel;
      }
    }
  });
}

行内编辑列表示例：

{
  title: '等级',
  name: 'gradeCode',
  editType: 'select',
  selectOption: {
    value: 'code',
    label: 'gradeName',
    selectList: [
      { code: 'A', gradeName: '一级' },
      { code: 'B', gradeName: '二级' },
    ],
  },
}

按行动态加载 / 远程搜索（推荐 selectListName；直接 return Observable，无需业务再刷 tableData）：

{
  title: '等级',
  name: 'gradeCode',
  editType: 'select',
  selectOption: {
    value: 'code',
    label: 'gradeName',
    selectListName: 'gradeOptions',
    hdServerSearch: true,
  },
  onOpenChangeEvent: (open, line) => this.loadGradeOptions(line, ''),
  onSearchEvent: (keyword, line) => this.loadGradeOptions(line, keyword),
  onSearchEventEventDebounceTime: 300,
}

// loadGradeOptions(line, keyword): Observable<Array<any>>

若必须在回调里自行 line.gradeOptions = list（不 return），可 ViewChild 调 hdTable.markForCheck()。

OperateBtn（操作列按钮）

| 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | name | string | (line) => string | — | 按钮文案；支持按行动态（如 是/否 旁的「解除/设置」） | | showConfirm | boolean | (line) => boolean | false | 是否 popconfirm 确认；传函数时按行数据判断 | | isRepeat | boolean | false | 与其他按钮互斥显示 | | click | (line) => void | — | 点击回调 | | permission | (line) => boolean | — | 是否显示 |

TotalOption（明细合计行 / hd-table 底部合计）

用于 hd-detail-lines、hd-detail-lines-page、hd-form-lines、hd-table（tableTotalOption）。

hd-table 开启 showTableTotal 后左侧固定增加「序号」列；合计通过 nzFooter 固定在表体下方、分页上方。「合计」对齐序号列；insertIndex 从 1 起对应可见数据列。未传 insertValue 时按该列 name 对当前 content 数值求和。

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | insertIndex | number | 插入列下标（从 1 开始） | | insertValue | any | 合计值；hd-table 可不传，按列自动求和 | | align | string | 对齐方式 | | showDecimal | boolean | 始终显示小数 | | preserveNumber | number | 保留小数位数，不传默认 2 | | isHide | boolean | 隐藏该合计列 |

TableTotalOption（hd-current-table 合计，已弃用）

| 参数 | 类型 | 说明 | | ---- | ---- | ---- | | columnNumber | number | 总列数 | | insertIndex | number | 插入列下标 | | insertName | string | 合计字段名 |

附录：ColWidth 列宽常量

发布后的 .d.ts 带字面量类型（as const），业务仓 IDE 悬停 ColWidth.xxx 可直接看到数值与说明。

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  超长省略展开

附录：Page 分页结构

class Page<T> {
  totalPages: number;
  totalElements: number;
  pageNumber: number;   // 从 0 开始
  pageSize: number;
  hasContent: boolean;
  hasNext: boolean;
  content: T[];
}