smart-web-components 组件库使用指南

本 skill 覆盖 packages/basic/src/components 目录下所有组件的关键用法、API 和最佳实践。

组件速查索引

详细 API 参考文档

以下组件有完整的 API 参考文档，当需要精确的属性类型、默认值、方法签名时请阅读：

• - 完整表格 API、valueType 列表、actionRef/tableRef 方法：api-pro-table.md
• 完整树节点操作 API、NodeExtensions、Ref 方法：api-pro-tree.md
• 完整表单 API、formRef 方法、所有变体组件、原子组件列表：api-form.md
• 完整字典 API、所有展示/表单组件、Hooks 用法：api-dict.md

核心组件使用要点

HtProTable — 企业级表格

CODEBLOCK0

关键属性：

• - containerHeight — 容器高度，自动固定表头（推荐替代 scroll.y）
• INLINECODE36 — 调用 reload() / reset() / INLINECODE39
• INLINECODE40 — 调用 getSelectedRows() / setSelectedRowKeys() / INLINECODE43
• INLINECODE44 — 自定义工具栏
• INLINECODE45 — 隐藏搜索栏
• INLINECODE46 — 列设置缓存 + 尺寸切换
• INLINECODE47 — 分页记忆选中

列配置 HtProColumns 扩展属性：

• - valueType — 19 种搜索表单类型（input/select/date/dateRange/cascader 等）
• INLINECODE50 — 声明为搜索项
• INLINECODE51 — 透传给表单控件的属性
• INLINECODE52 — 超出 2 行省略
• INLINECODE53 — 隐藏列

HtForm — 高级表单

CODEBLOCK1

变体组件：

• - HtModalForm — Modal 内表单，通过 trigger 触发，onFinish 返回 true 自动关闭
• INLINECODE58 — Drawer 内表单，用法同上
• INLINECODE59 — 分步表单

formRef 扩展方法：

• - getFieldsFormatValue() — 获取格式化后所有值
• INLINECODE61 — 校验并返回格式化值

HtModal / HtDrawer — 弹窗/抽屉

CODEBLOCK2

注意： 弹窗中有表单时，使用 HtModalForm / HtDrawerForm，不要用 HtModal 嵌套 HtForm。

HtProTree — 高级树组件

CODEBLOCK3

Ref 方法： expandAll() / collapseAll() / refreshNode(key?) / refreshRoot() / INLINECODE70

节点操作流程： onBeforeAdd/Edit（验证）→ onRemoteAdd/Edit（API 调用，返回 { success, data }）→ onSuccess（回调）

HtDict — 字典组件

CODEBLOCK4

INLINECODE75 可选值：'system'（默认）| 'biz' | 'dynamic'

ScrollLoadSelect / HtSelect — 选择器

CODEBLOCK5

HtNiceModal — API 弹窗

CODEBLOCK6

注意： 禁止嵌套使用 HtNiceModal.Provider，全应用只用一个。

HtTableSelect — 弹窗表格选择器

CODEBLOCK7

HtCascader / HtRegionCascader

CODEBLOCK8

HtTree / HtRegionTree

CODEBLOCK9

HtFileUpload / HtImageUpload

CODEBLOCK10

HtCard

CODEBLOCK11

HtList

CODEBLOCK12

HtDescriptions

CODEBLOCK13

HtProRegionTree

CODEBLOCK14

HtColorPicker

CODEBLOCK15

HtFloatButton

CODEBLOCK16

HtRichTextEditor

CODEBLOCK17

公共注意事项

1. 1. 所有组件均从 @ht-smart/basic 导入
2. 基于 antd@4，不兼容 antd@5
3. HtRegionCascader / HtRegionTree / HtProRegionTree 必须在 GlobalProvider（来自 @ht-smart/workbench）上下文中使用
4. HtDict 组件需要在根组件配置 HtDictContext.Provider，提供 axios 请求实例
5. HtNiceModal 需要在应用根组件包裹 HtNiceModal.Provider，且只能有一个
6. HtModal / HtDrawer 中有表单 → 用 HtModalForm / HtDrawerForm，勿嵌套 INLINECODE87
7. 表单默认值 → 使用 initialValues，勿直接绑定 INLINECODE89
8. HtProTable request 返回格式：INLINECODE91
9. HtProTree onRemoteAdd/Edit 返回格式：INLINECODE93
10. HtFileUpload 大文件上传 → 自动切片，支持断点续传，可通过 quicklyUpload 方法简单调用