React 组件

UGForm 表单

UGForm 系列组件用于组织字段、标签、说明、错误信息与提交行为，适合搭配 useForm 管理受控表单。

导入方式

按需从包入口导入组件，并在应用入口引入一次样式文件。

tsx

import {
  UGForm, UGFormField, UGFormItem, UGFormLabel,
  UGFormControl, UGFormDescription, UGFormMessage,
} from '@ug666/ui-react'
import { useForm } from '@ug666/ui-react'

基础表单

用户注册场景：包含必填校验、邮箱格式校验、密码长度校验与 UGCheckbox 必勾项，提交成功后触发 toast。

状态展示

演示带帮助文字（UGFormDescription）的字段与已有错误（UGFormMessage 红字）的字段。

邀请码

输入邀请码后可加入团队协作空间

团队邮箱

用于接收团队通知

该邮箱已被其他账号占用

代码示例

完整注册表单，演示 useForm + UGForm 系列组件的典型组合用法。

tsx

import {
  UGForm, UGFormField, UGFormItem, UGFormLabel,
  UGFormControl, UGFormDescription, UGFormMessage,
  UGInput, UGButton, UGCheckbox, toast, UGToaster,
} from '@ug666/ui-react'
import { useForm } from '@ug666/ui-react'

interface RegisterValues {
  username: string
  email: string
  password: string
  agree: boolean
}

export function RegisterForm() {
  const { values, errors, handleChange, setError, clearErrors } = useForm<RegisterValues>({
    username: '',
    email: '',
    password: '',
    agree: false,
  })

  function handleSubmit() {
    clearErrors()
    let hasError = false

    if (!values.username.trim()) {
      setError('username', '用户名不能为空')
      hasError = true
    }
    if (!values.email.includes('@')) {
      setError('email', '请输入有效的邮箱地址')
      hasError = true
    }
    if (values.password.length < 8) {
      setError('password', '密码长度至少 8 位')
      hasError = true
    }
    if (!values.agree) {
      setError('agree', '请阅读并同意服务条款')
      hasError = true
    }

    if (!hasError) {
      toast.success('注册成功，欢迎加入！')
    }
  }

  return (
    <>
      <UGToaster />
      <UGForm onSubmit={handleSubmit} className="w-full max-w-md space-y-4">
        <UGFormField name="username" error={errors.username}>
          <UGFormItem>
            <UGFormLabel required>用户名</UGFormLabel>
            <UGFormControl>
              <UGInput
                placeholder="请输入用户名"
                value={values.username}
                onChange={(e) => handleChange('username', e.target.value)}
              />
            </UGFormControl>
            <UGFormMessage />
          </UGFormItem>
        </UGFormField>

        <UGFormField name="email" error={errors.email}>
          <UGFormItem>
            <UGFormLabel required>邮箱地址</UGFormLabel>
            <UGFormControl>
              <UGInput
                type="email"
                placeholder="you@example.com"
                value={values.email}
                onChange={(e) => handleChange('email', e.target.value)}
              />
            </UGFormControl>
            <UGFormDescription>用于接收系统通知与验证码</UGFormDescription>
            <UGFormMessage />
          </UGFormItem>
        </UGFormField>

        <UGFormField name="password" error={errors.password}>
          <UGFormItem>
            <UGFormLabel required>密码</UGFormLabel>
            <UGFormControl>
              <UGInput
                type="password"
                placeholder="至少 8 位字符"
                value={values.password}
                onChange={(e) => handleChange('password', e.target.value)}
              />
            </UGFormControl>
            <UGFormMessage />
          </UGFormItem>
        </UGFormField>

        <UGFormField name="agree" error={errors.agree}>
          <UGFormItem>
            <div className="flex items-start gap-2">
              <UGFormControl>
                <UGCheckbox
                  checked={values.agree as boolean}
                  onCheckedChange={(checked) => handleChange('agree', checked as boolean)}
                />
              </UGFormControl>
              <UGFormLabel className="cursor-pointer font-normal leading-relaxed">
                我已阅读并同意服务条款
              </UGFormLabel>
            </div>
            <UGFormMessage />
          </UGFormItem>
        </UGFormField>

        <UGButton type="submit" className="w-full">立即注册</UGButton>
      </UGForm>
    </>
  )
}

Props

属性	类型	默认值	说明
UGForm.onSubmit	(event: FormEvent) => void	—	表单提交回调，会阻止浏览器默认刷新。
UGFormField.name	string	必填	字段唯一名称，用于关联 label/message/control。
UGFormField.error	string	—	字段错误文本，有值时 UGFormMessage 显示红字。
UGFormLabel.required	boolean	false	显示必填红星。
UGFormControl.children	ReactElement	必填	单个表单控件，自动注入 id 与 aria 属性。
UGFormDescription	ReactNode	—	字段说明文字，显示为灰色小字。
UGFormMessage	ReactNode	—	错误提示，无错误时不渲染。