Checkbox
ui.widgets.Checkbox独立布尔选择,支持未选、已选和不确定态。
BEHAVIOR CONTRACT
状态、焦点、label 命中区和 on_change 使用同一交互边界。
RECORDED INTERACTION
Harness 点击真实 checkbox,状态文本变为 changed → checked。
pub fn buildCheckbox(scope: *ui.Scope, cx: *ui.Cx) anyerror!*ui.Node {
const a = cx.allocator;
const c = try col(cx, 12);
const status = try ui.text(cx, "changed → (none)", .{ .font_size = 13, .color = light.color.fg_secondary });
status.meta.ownership.meta.test_id = "story.checkbox.status";
const story = try cx.bindState(CheckboxStory, .{ .status = status });
const unchecked = try ui.widgets.Checkbox(.{
.label_text = "Unchecked",
.initial_checked = false,
.on_change = ui.Cx.boolHandlerFrom(CheckboxStory, story, CheckboxStory.onChange),
}).mount(scope, cx);
unchecked.meta.ownership.meta.test_id = "story.checkbox.box";
try c.appendChild(a, unchecked);
try c.appendChild(a, try ui.widgets.Checkbox(.{ .label_text = "Checked", .initial_checked = true }).mount(scope, cx));
try c.appendChild(a, try ui.widgets.Checkbox(.{ .label_text = "Indeterminate", .indeterminate = true }).mount(scope, cx));
try c.appendChild(a, try ui.widgets.Checkbox(.{ .label_text = "Disabled", .disabled = true }).mount(scope, cx));
try c.appendChild(a, status);
return c;
}这是 Storybook 中该 story 的原样代码(zenit 5f9add5+wip 2026-09-30)。其中 W 即 ui.widgets,col / row / label 是 Storybook 内的布局小工具。
CheckboxProps
ui.widgets.Checkboxfn Checkbox(props: CheckboxProps) CheckboxBuilder字段
类型
默认值
说明
initial_checkedboolfalse选中状态 初始勾选态。**只在 mount 时读取一次**,之后改无效(组件持有 自己的 CheckboxState)。需要外部驱动请用 mountResult 拿 state 后 调 setChecked,或用 ui.Show 重建。
indeterminateboolfalse不确定状态
label_text?[]const u8null标签
disabledboolfalse禁用
on_change?core.HandlerRefnull变化回调。2026-07-31 并轨为 `?core.HandlerRef`。 需要拿到新值用 `cx.boolHandlerFrom(State, ptr, method)` 构造; 只关心"变了"用 `cx.handlerFrom(...)`。
state_id?u64null状态 ID (用于 StateStore)
check_icon_asset?svg_assets.AssetnullCheck icon SVG 资产
*Node
ui.widgets.Checkboxmount 直接返回 *Node,把它 append 到父节点即可。