跳转到内容
AsterUI v0.12.76

Form

带验证、布局选项和字段管理的表单包装器。

导入

Section titled “导入”
import { Form } from 'asterui'

示例

Section titled “示例”

基础表单

带用户名和密码字段的简单登录表单。

 

 

 
import { Form, Input, Button } from 'asterui'

function App() {
  return (
      <Form onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
        <Form.Item name="username" label="Username">
          <Input placeholder="Enter username" />
        </Form.Item>
        <Form.Item name="password" label="Password">
          <Input type="password" placeholder="Enter password" />
        </Form.Item>
        <Form.Item>
          <Button color="primary" htmlType="submit">
            Login
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

表单验证

带必填字段和电子邮件模式验证规则的表单。

 

 

 
import { Form, Input, Button } from 'asterui'

function App() {
  return (
      <Form onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
        <Form.Item
          name="email"
          label="Email"
          rules={[
            { required: true, message: 'Please enter your email' },
            { type: 'email', message: 'Please enter a valid email' }
          ]}
        >
          <Input placeholder="name@example.com" />
        </Form.Item>
        <Form.Item
          name="password"
          label="Password"
          rules={[
            { required: true, message: 'Please enter your password' },
            { min: 6, message: 'Password must be at least 6 characters' }
          ]}
        >
          <Input type="password" placeholder="Enter password" />
        </Form.Item>
        <Form.Item>
          <Button color="primary" htmlType="submit">
            Submit
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

提示和额外内容

带提示帮助图标的标签和字段下方的额外辅助文本。

 

Username must be 3-20 characters
 
import { Form, Input, Button } from 'asterui'

function App() {
  return (
      <Form onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
        <Form.Item
          name="username"
          label="Username"
          tooltip="Your unique identifier on the platform"
          extra="Username must be 3-20 characters"
          rules={[{ required: true }, { min: 3 }, { max: 20 }]}
        >
          <Input placeholder="Choose a username" />
        </Form.Item>
        <Form.Item>
          <Button color="primary" htmlType="submit">Save</Button>
        </Form.Item>
      </Form>
    )
}

export default App

验证反馈

使用 hasFeedback 属性在输入框内显示验证图标。

 

 

 
import { Form, Input, Button } from 'asterui'

function App() {
  return (
      <Form onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
        <Form.Item
          name="email"
          label="Email"
          hasFeedback
          rules={[{ required: true }, { type: 'email' }]}
        >
          <Input placeholder="you@example.com" />
        </Form.Item>
        <Form.Item
          name="password"
          label="Password"
          hasFeedback
          rules={[
            { required: true },
            { min: 8, message: 'At least 8 characters' },
          ]}
        >
          <Input type="password" placeholder="Enter password" />
        </Form.Item>
        <Form.Item>
          <Button color="primary" htmlType="submit">Register</Button>
        </Form.Item>
      </Form>
    )
}

export default App

表单布局

不同的表单布局：水平、垂直和内联。

 

 

 
import { Form, Input, Button, Radio, Space } from 'asterui'
import { useState } from 'react'

function App() {
  const [layout, setLayout] = useState<'horizontal' | 'vertical' | 'inline'>('vertical')
  
  return (
      <Space direction="vertical" size="lg" className="w-full">
        <Radio.Group
          value={layout}
          onChange={(e) => setLayout(e.target.value as typeof layout)}
        >
          <Radio value="vertical">Vertical</Radio>
          <Radio value="horizontal">Horizontal</Radio>
          <Radio value="inline">Inline</Radio>
        </Radio.Group>
  
        <Form layout={layout} onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
          <Form.Item name="name" label="Name" required>
            <Input placeholder="Enter name" />
          </Form.Item>
          <Form.Item name="email" label="Email" required>
            <Input placeholder="Enter email" />
          </Form.Item>
          <Form.Item>
            <Button color="primary" htmlType="submit">
              Submit
            </Button>
          </Form.Item>
        </Form>
      </Space>
    )
}

export default App

初始值

带预填充初始值的表单。

 

 

 

 
import { Form, Input, Button, Textarea } from 'asterui'

function App() {
  const initialValues = {
    username: 'john_doe',
    email: 'john@example.com',
    bio: 'Software developer'
  }
  
  return (
      <Form initialValues={initialValues} onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
        <Form.Item name="username" label="Username">
          <Input />
        </Form.Item>
        <Form.Item name="email" label="Email">
          <Input />
        </Form.Item>
        <Form.Item name="bio" label="Bio">
          <Textarea rows={3} />
        </Form.Item>
        <Form.Item>
          <Button color="primary" htmlType="submit">
            Update Profile
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

浮动标签

带浮动标签的 Form.Item，聚焦时动画。

 

 

 

 
import { Form, Input, Button } from 'asterui'

function App() {
  return (
      <Form onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
        <Form.Item name="fullName" floatingLabel="Full Name" required>
          <Input />
        </Form.Item>
        <Form.Item name="email" floatingLabel="Email Address" required>
          <Input type="email" />
        </Form.Item>
        <Form.Item name="password" floatingLabel="Password" required>
          <Input type="password" />
        </Form.Item>
        <Form.Item>
          <Button color="primary" htmlType="submit">
            Sign Up
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

表单插件

带输入框前后文本/元素的 Form.Item。

 

 

 

 
import { Form, Input, Button } from 'asterui'

function App() {
  return (
      <Form onFinish={(values) => alert(JSON.stringify(values, null, 2))}>
        <Form.Item name="website" label="Website" addonBefore="https://">
          <Input placeholder="your-site.com" />
        </Form.Item>
        <Form.Item name="price" label="Price" addonBefore="$" addonAfter=".00">
          <Input type="number" placeholder="0" />
        </Form.Item>
        <Form.Item name="email" label="Email" addonAfter="@company.com">
          <Input placeholder="username" />
        </Form.Item>
        <Form.Item>
          <Button color="primary" htmlType="submit">
            Submit
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

动态字段（Form.List）

使用 Form.List 动态添加和删除表单字段。

 

 

 
import { Form, Input, Button, Space, Modal } from 'asterui'

function App() {
  return (
      <Form
        initialValues={{ guests: [{ name: '', email: '' }] }}
        onFinish={(values) => Modal.info({ title: 'Form Data', content: JSON.stringify(values, null, 2) })}
      >
        <Form.List name="guests">
          {(fields, { add, remove }) => (
            <Space direction="vertical" className="w-full">
              {fields.map((field, index) => (
                <Space key={field.id} className="w-full items-end">
                  <Form.Item
                    name={[field.name, 'name']}
                    label={index === 0 ? 'Name' : undefined}
                    rules={[{ required: true, message: 'Name required' }]}
                  >
                    <Input placeholder="Guest name" />
                  </Form.Item>
                  <Form.Item
                    name={[field.name, 'email']}
                    label={index === 0 ? 'Email' : undefined}
                    rules={[{ required: true }, { type: 'email' }]}
                  >
                    <Input placeholder="Email" />
                  </Form.Item>
                  <Form.Item>
                    <Button
                      type="button"
                      color="error"
                      variant="ghost"
                      size="sm"
                      onClick={() => remove(index)}
                      disabled={fields.length === 1}
                    >
                      Remove
                    </Button>
                  </Form.Item>
                </Space>
              ))}
              <Button type="button" variant="outline" onClick={() => add({ name: '', email: '' })}>
                + Add Guest
              </Button>
            </Space>
          )}
        </Form.List>
        <Form.Item>
          <Button color="primary" htmlType="submit" className="mt-4">
            Submit
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

API

Section titled “API”

Form

Section titled “Form”
属性描述类型默认值
onFinish成功处理器（验证通过时调用）(values: any) => void-
onFinishFailed失败处理器（验证失败时调用）(errorInfo: any) => void-
initialValues初始表单字段值Record<string, any>-
layout表单布局方向'horizontal' | 'vertical' | 'inline''vertical'
labelWidth水平布局的标签宽度（像素）number60
size表单控件的尺寸'xs' | 'sm' | 'md' | 'lg' | 'xl''md'
disabled禁用所有表单字段booleanfalse
children表单内容（Form.Item 元素）React.ReactNode-
className额外的 CSS 类名string-

Form.Item

Section titled “Form.Item”
属性描述类型默认值
name字段名称（验证所需）string-
label字段标签文本string-
floatingLabel浮动标签文本（label 的替代方案）string-
addonBefore输入框前的文本/元素（外部）React.ReactNode-
addonAfter输入框后的文本/元素（外部）React.ReactNode-
rules验证规则ValidationRule[]-
required标记字段为必填（简写）booleanfalse
valuePropName值的属性名称（例如复选框的 “checked”）string'value'
inline使用自动宽度而非全宽渲染booleanfalse
tooltip在标签旁显示的提示文本string-
extra表单控件下方的额外内容React.ReactNode-
hasFeedback显示验证反馈图标booleanfalse
dependencies更改时触发重新验证的字段名称string[]-
validateTrigger何时验证'onChange' | 'onBlur' | 'onSubmit' | array'onChange'
initialValue此字段的初始值any-
hidden隐藏字段但仍验证和提交booleanfalse
children表单控件元素（Input、Select 等）React.ReactNode-
className额外的 CSS 类名string-

Form.ErrorList

Section titled “Form.ErrorList”
属性描述类型默认值
fields要显示错误的特定字段名称（如果未指定则显示所有）string[]-
className额外的 CSS 类名string-

Form.List

Section titled “Form.List”

管理表单字段的动态数组。

属性描述类型默认值
name数组字段的名称string-
children渲染函数(fields, operations) => ReactNode-

字段数组项：

  • id - 字段的唯一标识符
  • name - 字段的索引（在 Form.Item name 中使用为 [field.name, 'fieldKey']）

操作：

  • add(value?) - 添加带可选初始值的新字段
  • remove(index) - 删除索引处的字段
  • move(from, to) - 将字段从一个索引移动到另一个索引

验证规则

Section titled “验证规则”

rules 属性接受验证规则数组：

  • required: boolean - 字段为必填
  • message: string - 要显示的错误消息
  • type: 'email' | 'url' | 'number' - 内置类型验证
  • min: number - 字符串的最小长度或数字的最小值
  • max: number - 字符串的最大长度或数字的最大值
  • pattern: RegExp - 自定义正则表达式模式验证
  • validate: (value) => boolean | string | Promise - 自定义验证函数