每个有值的组件都支持两种用法:不受控(defaultValue,组件自己管状态)和受控(value 加 onValueChange,你管状态)。两者可以混用在不同组件上,互不影响。
不受控
<Switch defaultChecked onCheckedChange={(checked) => save(checked)} />组件内部持有状态,回调只是通知你。适合大多数表单与设置面板。
受控
const [channel, setChannel] = useState("push");
<Select value={channel} onValueChange={(value) => setChannel(value)} items={channels}>
…
</Select>状态在你手里,组件只负责把「想变成什么」告诉你。适合需要联动、持久化或服务端同步的场景。
details:原因、来源与取消
变更回调的第二个参数 details 携带三样东西:
reason:为什么变——指针、键盘、智能体、清除等。source:谁发起的——"pointer"、"keyboard"、"agent"等。cancel():拒绝这次变更。
<Slider
value={volume}
onValueChange={(value, details) => {
if (value > 90 && details.source !== "agent") {
details.cancel();
toast.warning("音量过高", { description: "已限制在 90 以内。" });
return;
}
setVolume(value);
}}
/>多值组件的值是数组
ToggleGroup、Accordion(multiple)、Listbox(multiple)等多值组件,值永远是数组,单选模式下也是:
<ToggleGroup
defaultValue={["light"]}
deselectable={false}
onValueChange={(values) => setTone(values[0])}
>
…
</ToggleGroup>deselectable={false} 保证始终有一个按下项。受控时传 value={[tone]}。
看状态流动
下面的面板同时展示控件与智能体快照:操作任一控件,右侧快照实时反映同一份状态。
实时演示 · 通知设置
ui-sdk · react
启用通知立即生效的设置
提示音
音量
通知渠道
智能体快照
- 正在读取组件状态…
试着调节左侧控件,或交由右侧智能体执行。