For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/zh/components/form.md.
v0.0.57
  • 简体中文
  • Form

    数据录入@rockshin/tao-ui

    管理表单值、校验规则、提交状态与字段布局。

    何时使用

    多个字段需要统一的数据收集、校验和提交生命周期时使用 Form。

    Form 的直接子级 Form.Item 在有提示行时默认保留 4px 底部间距(--tao-size-unit),其余字段为 20px(--tao-padding-md);--tao-form-field-item-gap 可覆盖两者。放入 Stack 或 FormSection 后由容器管理间距;noStyle 不产生外壳或间距,独立 FormField 的布局不变。

    默认 12–14px 提示字号下,预留行高为 18px,加上 2px 上间距和 4px 下间距,提示区域合计 24px。自定义更大的提示字号时,行高可随之增长。

    Form.Item 配有校验规则,或显式设置 help、extra、validateStatus 时,在控件下方预留一行提示空间。单行校验消息出现和消失时不会挤动后续字段或按钮;长文案换行时允许自然撑高,避免遮挡内容。没有校验或提示的字段不预留空行。手动控制提示时,可用 help="" 保留空提示行。

    推荐

    • 校验消息说明问题和恢复方式。
    • 按用户任务组织字段,而不是按数据模型机械排列。
    • 通过 setFields(包括受控 fields 属性)写入的值会清掉该字段因旧值产生的残留校验错误;需要在同一条目里直接提供新的校验状态时,可同时传 errors/warnings。

    避免

    • 不要为单个无校验输入引入完整 Form。

    代码演示

    基础用法

    TSX

    表单校验

    TSX

    水平布局

    TSX

    完整表单

    组合字段、分组和操作区,在一个页面中展示实际填写与提交路径。

    Personal Information

    Basic details about you.

    ✉️
    +86

    Optional. Used for recovery.

    Preferences

    Configure your workspace.

    TSX

    跨字段校验

    使用其他字段的值进行校验,并在相关值变化后更新反馈。

    TSX

    动态字段列表

    用 Form.List 增加和移除重复字段,表单值与字段索引同步维护。

    TSX

    滚动到理赔字段

    使用 Form.useForm()、Form 的 ref 或 Form.useFormInstance() 获取实例。支持数组路径和 Form.List 完整路径,例如 ['claims', 0, 'email']。

    向下滚动,或点击按钮定位字段。

    TSX

    默认使用 scrollMode: 'if-needed' 和 block: 'nearest'。可传入 behavior、block、inline、boundary、scrollMode 等选项,focus: true 会在发起滚动后聚焦控件。只定位已挂载字段;条件渲染或未挂载的 Tab 内容需要先展开。自定义控件必须转发 ref(DOM 或带 nativeElement 的实例)或 id。

    <Form
      form={form}
      onFinishFailed={({ errorFields }) => {
        if (errorFields.length) {
          form.scrollToField(errorFields[0].name, { focus: true });
        }
      }}
    />

    API

    Form

    属性说明类型默认值
    layoutLabel/control arrangement inherited by Form.Item. Defaults to 'vertical'."vertical" | "horizontal" | undefined-
    sizeCascades a control size to everything inside the form.TaoSize | undefined-
    disabledDisables every tao-ui control inside the form (e.g. while submitting).boolean | undefined-