表单 | UI SDK

ui-sdk 的控件遵循原生表单约定。给控件一个 name，它的值就随表单提交——选择器、组合框与输入框、复选框都一样。字段（Field）把控件连到它的标签、描述与错误消息。

提交值

import { Checkbox } from "@ui-sdk/react/checkbox";

function Example() {
  return (
    <form action="/preferences" method="post">
      <label>
        <Checkbox name="updates" value="yes" defaultChecked />
        接收邮件更新
      </label>
      <button type="submit">保存</button>
      <button type="reset">重置</button>
    </form>
  );
}

选中时提交 updates=yes，重置恢复默认值。

重置受控值

重置同样走 onCheckedChange。像处理点击一样在那里更新你的 React 状态：

const [checked, setChecked] = React.useState<CheckedState>(true);

<Checkbox
  name="updates"
  defaultChecked
  checked={checked}
  onCheckedChange={(next, details) => {
    setChecked(next);
    // details.reason === "reset"
  }}
/>;

defaultChecked 提供重置目标值，回调收到 true 且 details.reason 为 "reset"。仅当重置请求的值与当前不同才触发回调；已经在默认值上则不触发。参见状态与事件。

标注与校验字段

Field 把控件连到标签、描述与错误：

import { Field, FieldDescription, FieldError, FieldLabel } from "@ui-sdk/react/field";
import { Input } from "@ui-sdk/react/input";

<Field name="email">
  <FieldLabel>邮箱</FieldLabel>
  <Input type="email" required />
  <FieldDescription>仅用于发送回执。</FieldDescription>
  <FieldError />
</Field>;

把 Input 换成多行文本、复选框、开关、单选框或选择器即可，连接方式见字段。

支持原生表单约定的控件接受这些属性：

属性	作用
`name`	提交的字段名。没有它就不提交值。
`required`	提交前必须有值。
`disabled`	禁止交互，且不参与提交。
`readOnly`	禁止编辑，但仍可聚焦、仍提交值。
`form`	控件在表单外时，按 id 连到某个表单。

处理提交

正常提交时，浏览器先检查 required、type="email" 等约束，再运行你的处理器。

服务端仍可能拒绝一个看起来合法的值。把 invalid 传给字段并显示服务端消息；用户编辑时清除消息、把 invalid 还原为 undefined，让字段回到原生校验：

const [error, setError] = React.useState("");

async function save(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault();
  const response = await fetch("/api/preferences", {
    method: "POST",
    body: new FormData(event.currentTarget),
  });
  setError(response.ok ? "" : "该邮箱已被占用。");
}

<form onSubmit={save}>
  <Field name="email" invalid={error ? true : undefined}>
    <FieldLabel>邮箱</FieldLabel>
    <Input type="email" required onValueChange={() => setError("")} />
    <FieldError>{(state) => error || state.message}</FieldError>
  </Field>
  <button type="submit">保存</button>
</form>;

没有处理器时，表单通过它的 action 提交，包括 React server action。

表单

提交值

重置受控值

标注与校验字段

处理提交

相关页面