@hw-component/form 组件文档

基于 Ant Design 4.x 二次开发的 React 表单组件库。核心是 HForm 声明式表单：通过一份 configData 配置数组渲染整张表单，内置 28 种控件映射、弹窗表单、全局配置、联动与值格式化等能力，提供完整 TypeScript 类型定义。

HForm 声明式表单

import React from "react";
import { HForm, useHForm } from "@hw-component/form";

const Demo = () => {
  const form = useHForm();

  return (
    <HForm
      form={form}
      labelAlign="top"
      configData={[
        { label: "姓名", name: "name", type: "input" },
        {
          label: "性别",
          name: "sex",
          type: "select",
          itemProps: { options: [{ label: "男", value: 1 }, { label: "女", value: 2 }] },
        },
        {
          label: "出生日期",
          name: "birthday",
          type: "datePicker",
          itemProps: { format: "YYYY-MM-DD" },
        },
      ]}
      request={(values) => {
        // form.submit() 或表单内 submit 类型按钮触发
        return Promise.resolve(values);
      }}
    />
  );
};

export default Demo;

HFormProps

除以下扩展字段外，其余 props 与 antd FormProps 一致（initialValues、onValuesChange、colon、preserve 等）。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | configData | 表单配置数组（必填），见 HItemProps | HItemProps[] | — | | form | 经 useHForm() 创建的实例 | HFormInstance | 内部创建 | | request | 提交请求，form.submit() 触发；Promise reject 时中断并保留表单 | (values, params) => Promise | — | | infoRequest | 回显请求，挂载时自动执行，返回值写入表单；异常时渲染错误页并支持 reload | PromiseFnResult \| { request, ...BaseOptions } | — | | params | 附加参数，透传给 request / infoRequest | any | — | | valueType | 值格式化方案标识，配合自定义 addFormat 使用 | string | "float" | | labelAlign | 标签对齐 | "left" \| "right" \| "top" \| "topLeft" \| "topRight" | — | | labelWidth | 标签宽度（px），表单级默认 | number | — | | itemSpan | 表单项栅格，同 antd ColProps，表单级默认 | ColProps | — | | gutter | 栅格间距，同 antd Row | Gutter \| [Gutter, Gutter] | — | | hideLabel | 隐藏全部标签 | boolean | false | | formItemStyle | 表单项容器样式，表单级默认 | CSSProperties | — | | itemProps | 透传给全部控件的公共 props | ItemPropsType | — | | submitLoading | 外部控制的提交 loading | boolean | — | | dismissOnPressEnter | 是否拦截回车提交 | boolean | — | | rowWrapper | 表单项独占一行渲染 | boolean | — | | requiredMode | 必填模式：label 左侧红点占位对齐 | boolean | — |

HItemProps（configData 配置项）

除 type 与以下扩展字段外，其余同 antd FormItemProps（rules、dependencies、validateTrigger、noStyle 等）。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | type | 控件类型，见 控件类型映射 | string | input | | itemProps | 透传给具体控件的 props（如 options、request） | ItemPropsType | — | | name | 字段名，支持 string 或路径数组 ["a", "b"] | string \| any[] | — | | label | 标签，支持函数形式 (form) => ReactNode | ReactNode \| (form) => ReactNode | — | | hide | 不渲染该项，支持函数动态控制 | boolean \| (form) => boolean | — | | hidden | 渲染但隐藏（占位，值保留），支持函数 | boolean \| (form) => boolean | — | | hover | label 旁提示图标，文案支持 string / string[]（多段） / 函数 | string \| string[] \| HoverModal \| (form) => string \| HoverModal | — | | helper | 表单项下方辅助说明 | ReactNode \| (form) => ReactNode | — | | placeholder | 占位文案，支持 string[]（组合控件多段）；不传时按类型自动生成 | string \| string[] | 自动 | | dispatch | 联动声明：依赖字段变化时按 fnKey 触发（常用于重新请求 options） | { fnKey?: string; dependencies?: string \| string[]; manual?: boolean; reset?: boolean } | — | | render | 完全自定义渲染，返回值替换控件节点 | (props, node, form) => ReactNode | — | | labelWidth | 单项标签宽度 | number | 继承表单 | | labelAlign | 单项标签对齐 | LabelAlignModal | 继承表单 | | hideLabel | 单项隐藏标签 | boolean | 继承表单 | | itemSpan | 单项栅格 | ColProps | 继承表单 | | rowWrapper | 单项独占一行 | boolean | 继承表单 | | flexBox | flex 布局渲染 | boolean | — | | nameKey | 配合 render 嵌套表单的字段前缀 | string | — |

控件类型映射

type 与导出组件的对应关系：

| type | 组件 | 说明 | | --- | --- | --- | | input | HInput | 输入框（默认） | | trimInput | HTrimInput | 失焦自动去首尾空格的输入框 | | textArea | HTextArea | 多行文本 | | trimTextArea | HTrimTextArea | 自动去首尾空格的多行文本 | | inputNumber | HInputNumber | 数字输入 | | inputNumberGroup | HInputNumberGroup | 数字输入组（多段数值） | | selectInput | HSelectInput | 前置下拉 + 输入框，值为 { select, input } | | buttonInput | HButtonInput | 带按钮的输入框 | | select | HSelect | 下拉选择，itemProps.options / itemProps.request 提供选项 | | treeSelect | HTreeSelect | 树选择 | | tagSelect | HTagSelect | 标签多选 | | cascader | HCascader | 级联选择 | | radioGroup | HRadioGroup | 单选组 | | checkboxGroup | HCheckboxGroup | 多选组 | | checkBox | HCheckBox | 单个勾选框，取值经 valueCheckMap 映射 | | switch | HSwitch | 开关，取值经 valueSwitchMap 映射 | | datePicker | HDatePicker | 日期 | | rangePicker | HRangePicker | 日期区间，提交时按 valueRangePickerValueMap 拆为两个字段 | | timePicker | HTimePicker | 时间 | | timeRangePicker | HTimeRangePicker | 时间区间 | | upload | HUpload | 文件上传（itemProps.request 必传上传实现） | | urlUpload | HUrlUpload | URL 形式上传 | | imgCropUpload | HImgCropUpload | 图片裁剪上传 | | richEditor | HRichEditor | 富文本（braft-editor），itemProps.valueType: "html" \| "state" | | colorInput | HColorInput | 颜色选择 | | verificationCodeInput | HVerificationCodeInput | 验证码输入 | | text | HText | 纯文本展示（不参与表单值） | | submit | HSubmit | 提交按钮，点击触发表单提交 |

选择类控件（select / treeSelect / tagSelect / checkboxGroup / radioGroup 等）的 itemProps 支持 request: (params) => Promise<options> 异步选项，内部基于 ahooks useRequest；options 字段名支持经全局 fieldNames 定制。

全局配置 HFormConfigProvider

包裹任意层级即可统一定制默认行为，与内置 baseConfig 浅合并，组件局部 props 优先：

import { HFormConfigProvider } from "@hw-component/form";

<HFormConfigProvider
  // options 字段名映射（默认 { label: "label", value: "value" }）
  fieldNames={{ label: "name", value: "id" }}
  // 勾选 / 开关取值映射（默认均为 1 / 0）
  valueCheckMap={{ checked: 1, noChecked: 0 }}
  valueSwitchMap={{ open: "Y", close: "N" }}
  // rangePicker 提交时自动拆段字段名（默认 `${name}StartTime` / `${name}EndTime`）
  valueRangePickerValueMap={{
    start: (name) => `${name}Start`,
    end: (name) => `${name}End`,
  }}
  // 日期快捷项（作用于 HDatePicker / HRangePicker）
  dateRanges={{ 最近七天: () => [moment().subtract(6, "days"), moment()] }}
  // 上传默认参数（内置默认为 base64 演示实现，业务必须覆盖 request）
  uploadProps={{
    exFiles: ["JPG", "PNG"],
    maxSize: 1024 * 1024 * 2,
    request: async (file) => ({ url: await uploadFile(file) }),
  }}
  // 富文本图片上传请求
  richEditorProps={{ fileRequest: async (file) => ({ url }) }}
  // 注册自定义控件：configData 中直接以对象 key 作为 type 使用
  defaultComponent={{ myControl: MyControl }}
  // 表单项公共样式与公共控件 props
  formItemStyle={{}}
  itemProps={{}}
>
  <App />
</HFormConfigProvider>

弹窗表单 HModalForm / HDrawerForm

通过 useHDialogForm() 获取实例，支持命令式打开：

import { Button } from "antd";
import { HModalForm, useHDialogForm } from "@hw-component/form";

const Demo = () => {
  const modalForm = useHDialogForm();

  return (
    <>
      <Button
        onClick={() => {
          modalForm.show({
            title: "编辑",
            initialValues: { name: "张三" },
          });
        }}
      >
        编辑
      </Button>
      <HModalForm
        configData={[
          { label: "姓名", name: "name", type: "input" },
          { label: "备注", name: "remark", type: "textArea" },
        ]}
        form={modalForm}
        autoClear={false}
        request={async (values, params) => {
          // 点击确定时触发；Promise resolve 后自动关闭，reject 保留弹窗
          return Promise.resolve(values);
        }}
      />
    </>
  );
};

export default Demo;

弹窗表单扩展 props

HModalForm / HDrawerForm 在 HFormProps 基础上扩展：

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | visible | 受控显示隐藏 | boolean | false | | title | 弹窗标题，show() 可临时覆盖 | ReactNode | — | | autoClear | 再次打开时是否清空上次表单值；false 时保留 | boolean | true | | confirmLoading | 确定按钮外部 loading | boolean | — | | footer | 自定义底部；传 null 隐藏 | ReactNode \| (form, loading, params) => ReactNode | 默认取消/确定 | | afterClose | 关闭动画结束后的回调 | () => void | — |

useHDialogForm 实例方法

包含 antd FormInstance 全部方法与以下扩展：

| 方法 | 说明 | | --- | --- | | show({ configData, initialValues, params, title }) | 打开弹窗，可临时替换配置、回填初值、携带参数与标题 | | hide() | 关闭弹窗 | | getParams() | 读取 show() 携带的参数（提交时透传给 request） | | setParams(params) | 追加合并参数 | | resetDialogFormValue(values) | 清空表单后写入指定值 |

useHForm 实例方法

useHForm() 返回的 HFormInstance 在 antd FormInstance 基础上扩展：

| 方法 | 说明 | | --- | --- | | outputValues(values?, preserve?) | 输出经格式化（拆段、值映射、addFormat）后的表单值 | | formatValues(values?, formatKey?) | 按指定格式化链转换表单值 | | addFormat(name, { inputValue, outputValue }) | 注册某字段输入/输出值格式化 | | clearFormat(name) | 清除某字段格式化 | | dispatch({ key, name }) | 手动触发联动 | | addDispatchListener(action, fn) / removeDispatchListener() | 监听 / 移除联动事件 | | reload(params?) | 重新执行 infoRequest 回显 | | initValues() | 应用初始值 | | resetFieldsInitValue(values?) | 重置为初始值（可传入新初值） | | resetFieldsValues(values?) | 重置为当前已设值 | | resetFormStatus() | 重置校验状态 | | setSourceFieldsValue(values) | 设置源字段值 | | clear() | 清空表单 | | inited | 是否已完成初始化 |

自定义组件接入

方式一：defaultComponent 注册（推荐）

在 HFormConfigProvider 的 defaultComponent 中注册后，configData 直接以注册 key 作为 type 使用，组件按受控组件规范接收 value / onChange 即可。

方式二：render 函数

{
  label: "自定义",
  name: "custom",
  render: (props, node, form) => <MyControl {...props} />,
}

方式三：HFormConnect HOC

为自定义受控组件注入表单能力（addFormat 值格式化、addDispatchListener 联动监听）：

import { HFormConnect } from "@hw-component/form";

export default HFormConnect(({ value, onChange, addFormat, addDispatchListener }) => {
  // addFormat({ inputValue, outputValue })、addDispatchListener(key, fn) 可选调用
  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
});

导出清单

| 分类 | 导出 | | --- | --- | | 表单 | HForm、HBasicForm、HFormConnect、HFormConfigProvider、HInputGroup | | Hooks | useHForm、useHDialogForm | | 弹窗表单 | HModalForm、HDrawerForm | | 输入类 | HInput、HTrimInput、HTextArea、HTrimTextArea、HInputNumber、HInputNumberGroup、HSelectInput、HButtonInput、HVerificationCodeInput、HColorInput | | 选择类 | HSelect、HTreeSelect、HTagSelect、HCascader、HRadioGroup、HCheckboxGroup、HCheckBox | | 日期时间 | HDatePicker、HRangePicker、HTimePicker、HTimeRangePicker | | 上传 | HUpload、HUrlUpload、HImgCropUpload | | 其它 | HRichEditor、HText、HSwitch、HPageHandler |