smart-web-components-usage

---

name: smart-web-components-usage description: 提供 @ht-smart/basic 组件库中所有组件的使用指导和 API 参考。当用户询问如何使用、如何配置或如何集成 HtProTable、HtProTree、HtForm、HtModal、HtDrawer、HtDict、HtCard、HtCascader、HtSelect、HtSearchForm、HtList、HtNiceModal、HtProRegionTree、HtTree、HtColorPicker、HtDescription、HtFileUpload、HtFilePreview、HtFloatButton、HtGrid、HtLayout、HtDrawer、HtException、HtRichTextEditor、HtCopyright、HtDevicePlayer、HtButton、HtTab、HtTableSelect、ScrollLoadSelect、HtFormatTime、ActionSpace 等组件时使用此 skill。

---

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

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

组件速查索引

| 组件名 | 导入名 | 分类 | 说明 | |--------|--------|------|------| | HtActionSpace | HtActionSpace | 基础 | 列表操作栏，间隔布局 | | HtButton | IconButton | 基础 | 增强按钮，内置常用 icon 配置 | | HtInput | BaseInput | 基础 | 输入框封装 | | HtTab | BaseTab | 基础 | 标签页，支持 url 同步和定制样式 | | HtModal | HtModal | 基础 | 弹窗封装，简化状态管理 | | HtDrawer | HtDrawer | 基础 | 抽屉封装，支持拖拽宽度/最大化 | | HtException | HtException | 基础 | 异常页（401/403/404/500/502） | | HtCopyright | HtCopyright | 基础 | 版权信息组件 | | HtGrid | HtGrid | 基础 | 网格布局 | | HtSearchForm | HtSearchForm | 基础 | 搜索表单 | | HtRichTextEditor | HtRichTextEditor | 基础 | 富文本编辑器（基于 WangEditor） | | HtFormatTime | HtFormatTime | 基础 | 时间格式转换展示组件 | | HtForm | HtForm | 高级 | 高级表单，含 Modal/Drawer/Steps 表单 | | HtProTable | HtProTable | 高级 | 企业级表格，内置搜索/分页/列设置 | | HtTableSelect | HtTableSelect | 高级 | 弹窗表格选择器 | | HtCard | HtCard | 高级 | 高级卡片，支持栅格/折叠/统计 | | HtList | HtList | 高级 | 卡片风格列表，基于 HtProTable | | HtCascader | HtCascader / HtRegionCascader | 高级 | 级联选择，支持区划懒加载 | | HtSelect | HtSelect | 高级 | 下拉选择，支持 options 或远程请求 | | ScrollLoadSelect | ScrollLoadSelect | 高级 | 远程搜索+滚动加载选择器 | | HtDict | 多组件 | 高级 | 字典组件集合（Text/Tag/Badge/Select等） | | HtDescription | HtDescriptions | 高级 | 高级描述列表，支持远程请求 | | HtTree | HtTree / HtRegionTree | 高级 | 树形组件，支持懒加载/搜索 | | HtProTree | HtProTree | 高级 | 高级树，支持节点增删改/搜索 | | HtProRegionTree | HtProRegionTree | 高级 | 行政区划树，内置接口 | | HtColorPicker | HtColorPicker | 高级 | 颜色选择器，支持 hex/rgb/hsb | | HtDevicePlayer | HtDevicePlayer | 高级 | 设备（摄像头）实时播放组件 | | HtFileUpload | HtProFileUpload | 高级 | 大文件切片上传，支持断点续传 | | HtFilePreview | HtFilePreview | 高级 | 文件预览，通过 fileId 获取地址 | | HtFloatButton | HtFloatButton | 基础 | 悬浮按钮，支持受控选中/分组 | | HtNiceModal | HtNiceModal | 高级 | API 方式调用弹窗，解决多次渲染问题 | | HtLayout | HtProLayout | 高级 | 中后台标准布局 |

---

详细 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 — 企业级表格

import { HtProTable } from '@ht-smart/basic';
import type { HtProColumns, HtHocActionType } from '@ht-smart/basic';
const columns: HtProColumns[] = [
  { title: '名称', dataIndex: 'name', search: true },
  { title: '状态', dataIndex: 'status', valueType: 'select', search: true },
];
 {
    const res = await fetchList(params);
    return { records: res.data, total: res.total };
  }}
/>

关键属性：

containerHeight — 容器高度，自动固定表头（推荐替代 scroll.y）

actionRef — 调用 reload() / reset() / getLastParams()

tableRef — 调用 getSelectedRows() / setSelectedRowKeys() / cleanSelected()

renderToolbarLeft/Right — 自定义工具栏

searchConfig={false} — 隐藏搜索栏

options={{ setting: { cacheKey: 'xxx' }, size: true }} — 列设置缓存 + 尺寸切换

memoizedSelected — 分页记忆选中

列配置 HtProColumns 扩展属性：

valueType — 19 种搜索表单类型（input/select/date/dateRange/cascader 等）

search: true — 声明为搜索项

fieldProps — 透传给表单控件的属性

ellipsis: 2 — 超出 2 行省略

hidden: true — 隐藏列

---

HtForm — 高级表单

import { HtForm, HtFormText, HtFormDatePicker } from '@ht-smart/basic';
 {
    await submitApi(values);
    return true; // 返回 true 重置表单
  }}
  initialValues={{ name: '默认值' }}
>
  
  

变体组件：

HtModalForm — Modal 内表单，通过 trigger 触发，onFinish 返回 true 自动关闭

HtDrawerForm — Drawer 内表单，用法同上

HtStepsForm — 分步表单

formRef 扩展方法：

getFieldsFormatValue() — 获取格式化后所有值

validateFieldsReturnFormatValue() — 校验并返回格式化值

---

HtModal / HtDrawer — 弹窗/抽屉

// 触发器方式
打开} title="标题" onOk={async () => true}>
  内容
// 受控方式
// HtDrawer 额外支持

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

---

HtProTree — 高级树组件

import { HtProTree } from '@ht-smart/basic';
 ({ success: true, data: newNode }) },
    edit: { onRemoteEdit: async (data, node) => ({ success: true, data: updatedNode }) },
    delete: { onRemoteDelete: async (key, node) => api.delete(key) },
    refresh: true,
  }}
/>

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

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

---

HtDict — 字典组件

// 根组件配置请求实例

  
// 展示组件
      // 文本
       // 标签
     // 徽标
// 表单组件


// 表单集成（配合 HtForm）
// Hooks
const { dictData, loading } = useHtDict('status', 'system');

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

---

ScrollLoadSelect / HtSelect — 选择器

// 远程搜索+滚动加载
 fetchData({ page, size, keyword })}
  pageSize={30}
  mode="multiple"
  fieldNames={{ label: 'name', value: 'id' }}
  disabledValues={[1, 2]}
  params={{ departmentId: 1 }}
/>
// 静态 options（自动降级为 antd Select）

---

HtNiceModal — API 弹窗

// 1. 根组件包裹
// 2. 创建弹窗组件
const MyModal = HtNiceModal.create<{ name: string }>(({ name }) => {
  const modal = HtNiceModal.useModal();
  return (
     { modal.hide(); modal.resolve(); return true; }}
      onCancel={modal.hide}
      afterClose={() => { modal.resolveHide(); modal.remove(); }}
      destroyOnClose={!modal.keepMounted}
    >
      Hello, {name}!
    
  );
});
// 3. 调用
const result = await HtNiceModal.show(MyModal, { name: 'World' });

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

---

HtTableSelect — 弹窗表格选择器

  {(value, actions) => (
    已选 {value?.length ?? 0} 项
  )}
// 带左侧树的布局
 (
     onChange({ deptId: node.id })} />
  )}
  sideWidth={220}
>
  {(value) => 选择}

---

HtCascader / HtRegionCascader

// 基础级联，单选时 value 为 string|number，多选时为 (string|number)[]
 fetchCascaderData(params)}
  fieldNames={{ label: 'name', value: 'id' }} // 默认值
/>
// 区划级联，开箱即用（需 GlobalProvider 上下文）

---

HtTree / HtRegionTree

 node.code?.length >= 6}
/>
// 区划树（需 GlobalProvider）

---

HtFileUpload / HtImageUpload

// 文件上传
 file.size < 50 * 1024 * 1024}
  beforeRemove={async () => confirm('确认删除？')}
/>
// 图片上传
 console.log(fileId)}
/>
// 表单集成

---

HtCard

// 基础
操作}>
  内容
// 栅格布局（子卡片）

  左侧
  右侧
// 折叠

---

HtList

 
{item.name}
}
  onItemClick={(item) => console.log(item)}
/>

---

HtDescriptions

 fetchDetail(id)}
  columns={[
    { title: '名称', dataIndex: 'name' },
    { title: '状态', dataIndex: 'status', valueType: 'select', valueEnum: statusEnum },
  ]}
  bordered
  column={3}
/>

---

HtProRegionTree

// 行政区划树，无需配置 request
const treeRef = useRef();
 setSelected(node)}
/>
// ref 方法
treeRef.current.refreshRoot();
treeRef.current.expandAll();
treeRef.current.collapseAll();

---

HtColorPicker

 setColor(hex)}
  format="hex"
  showText
  allowClear
  presets={[{ label: '推荐色', colors: ['#1677ff', '#52c41a'] }]}
/>

---

HtFloatButton

  } />
  } />

---

HtRichTextEditor

// 表单集成（推荐）
// 基础用法
 setContent(html)}
/>

---

公共注意事项

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，勿嵌套 HtForm 7. 表单默认值 → 使用 initialValues，勿直接绑定 value/onChange 8. HtProTable request 返回格式：{ records: TData[], total: number } 9. HtProTree onRemoteAdd/Edit 返回格式：{ success: boolean, data?: any, error?: string } 10. HtFileUpload 大文件上传 → 自动切片，支持断点续传，可通过 quicklyUpload 方法简单调用