Checkbox
在一组选项中选择任意多项的复选框组件
复选框(Checkbox)用于在一组选项中选择任意多项。组件基于 Pressable + View 封装,指示器和标签是两个独立的可点区域:指示器带 hitSlop={4} 的热区补偿,标签可以用 labelDisabled 单独关掉。多行标签时指示器贴首行对齐,而不是整块垂直居中。
CheckboxGroup 统一维护整组选中值并下发 color / size / shape 等配置;CheckboxCard 是同一份选中逻辑的卡片形态,能直接放进 CheckboxGroup。
import { Checkbox, CheckboxCard, CheckboxGroup, CheckboxGroupCard } from '@skyroc/native-ui';基础用法
默认非受控,用 defaultChecked 给初始值。checked 除了 true / false 还接受 'indeterminate' 半选态。
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxBasic = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox defaultChecked>Checkbox</Checkbox>
<Checkbox>Unchecked</Checkbox>
<Checkbox checked="indeterminate">Indeterminate</Checkbox>
</View>
);
};
export { CheckboxBasic };半选是纯展示态:内部按未选中处理,点击后直接进入全选,不会在半选 → 全选 → 未选之间循环。
何时使用
- 一组选项中可以选择任意多项(含零项)时用
Checkbox;互斥单选用Radio。 - 单个开关型设置(立即生效、不需要提交)优先用
Switch,复选框更适合表单里需要一起提交的多选。 - 选项带图标、描述,或需要整块大热区时用
CheckboxCard;数据驱动、一次声明整组时用CheckboxGroupCard。 - 需要「全选 / 半选」的父级控制项时,用一个独立的
Checkbox+checked="indeterminate"驱动,CheckboxGroup自身不提供全选开关。
语义颜色
color 提供 8 种主题色,取值与全局 ThemeColor 一致。选中态填充 bg-{color},内部勾用 accent-{color}-foreground 取色,因此跟随主题 token 而不是硬编码白色。
| 颜色 | 选中背景 | 语义 |
|---|---|---|
primary | bg-primary | 常规选择(默认) |
destructive | bg-destructive | 危险项,如批量删除 |
success | bg-success | 成功、已完成 |
warning | bg-warning | 需要注意的选项 |
info | bg-info | 信息性选项 |
accent | bg-accent | 强调色 |
carbon | bg-carbon | 中性深色 |
secondary | bg-secondary | 次级、弱化选项 |
import { Checkbox, CheckboxGroup } from '@skyroc/native-ui';
import type { ThemeColor } from '@skyroc/native-ui';
import { View } from 'react-native';
const COLORS = ['primary', 'destructive', 'success', 'warning', 'info', 'accent', 'carbon', 'secondary'];
const CheckboxColor = () => {
return (
<View className="gap-4 bg-background p-4">
{COLORS.map(c => (
<CheckboxGroup
color={c as ThemeColor}
defaultValue={['a']}
direction="horizontal"
key={c}
>
<Checkbox name="a">{c}</Checkbox>
<Checkbox name="b">B</Checkbox>
</CheckboxGroup>
))}
</View>
);
};
export { CheckboxColor };未选中态与颜色无关,统一是 border-muted-foreground/50 的空心描边。
尺寸
size 同时决定指示器边长、内部勾的大小、标签字号与指示器到标签的间距:
| 尺寸 | 指示器 | 内部图标 | 控件行高 | 标签字号 | 指示器与标签间距 |
|---|---|---|---|---|---|
xs | 14 | 9 | 16 | text-xs | 4 |
sm | 16 | 11 | 20 | text-sm | 6 |
md | 20 | 14 | 24 | text-base | 8 |
lg | 24 | 16 | 24 | text-base | 10 |
xl | 28 | 18 | 24 | text-base | 12 |
2xl | 32 | 20 | 28 | text-lg | 14 |
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'] as const;
const CheckboxSize = () => {
return (
<View className="gap-3 bg-background p-4">
{SIZES.map(s => (
<Checkbox
key={s}
defaultChecked
size={s}
>
{s}
</Checkbox>
))}
</View>
);
};
export { CheckboxSize };「控件行高」取指示器边长与标签首行行高的较大值:标签比指示器高时把指示器撑到首行中线,指示器更高时以自身为准,避免被裁切。
形状
shape 控制指示器形状,round 是圆形(默认),square 是圆角方形(rounded)。
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxShape = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox
defaultChecked
shape="round"
>
Round (default)
</Checkbox>
<Checkbox
defaultChecked
shape="square"
>
Square
</Checkbox>
</View>
);
};
export { CheckboxShape };图标尺寸
iconSize 直接指定指示器边长(px),绕开 size 预设。此时内部勾按 0.7 倍等比缩放,避免只放大外框、内部图标还是预设尺寸导致的比例失衡。标签字号仍由 size 决定。
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxIconSize = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox
defaultChecked
iconSize={16}
>
16px
</Checkbox>
<Checkbox
defaultChecked
iconSize={28}
>
28px
</Checkbox>
<Checkbox
defaultChecked
iconSize={40}
>
40px
</Checkbox>
</View>
);
};
export { CheckboxIconSize };禁用
disabled 阻止交互并把整行降到 50% 不透明度,标签同时变为 text-muted-foreground。组级 disabled 与子项 disabled 取并集——组禁用后子项无法把自己反选为可用。
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxDisabled = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox disabled>Disabled</Checkbox>
<Checkbox
defaultChecked
disabled
>
Disabled & Checked
</Checkbox>
</View>
);
};
export { CheckboxDisabled };标签位置
labelPosition 决定标签在指示器右侧(默认)还是左侧,实现上是给根容器加 flex-row-reverse,间距不变。labelDisabled 只关掉标签的点击,指示器照常可点。
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxLabelPosition = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox labelPosition="right">Label on right</Checkbox>
<Checkbox labelPosition="left">Label on left</Checkbox>
<Checkbox labelDisabled>Label not pressable (labelDisabled)</Checkbox>
</View>
);
};
export { CheckboxLabelPosition };children 为 string / number 时会自动包一层 Text 并套用 label slot 的样式;传自定义节点时不做包裹,样式需要自己写。children 为 null / undefined / 布尔值时整个标签区不渲染,也不会留下一个撑开 gap 的空节点。
多行标签
标签换行时指示器保持贴首行,不会随文本块整体垂直居中。
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxMultilineLabel = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox defaultChecked>
A fairly long label that wraps onto more than one line so the control stays aligned with the first line rather
than the block center.
</Checkbox>
<Checkbox>{2024}</Checkbox>
</View>
);
};
export { CheckboxMultilineLabel };受控
checked + onCheckedChange 组成受控用法。分组内的子项由 CheckboxGroup 持有选中态,此时子项自己的 checked / defaultChecked 被忽略,但 onCheckedChange 依旧会触发。
import { Button, Checkbox } from '@skyroc/native-ui';
import { useState } from 'react';
import { View } from 'react-native';
const CheckboxControlled = () => {
const [controlled, setControlled] = useState(false);
return (
<View className="gap-3 bg-background p-4">
<Checkbox
checked={controlled}
onCheckedChange={setControlled}
>
{controlled ? 'Checked' : 'Unchecked'}
</Checkbox>
<Button
size="sm"
onPress={() => setControlled(v => !v)}
>
Toggle
</Button>
</View>
);
};
export { CheckboxControlled };分组
CheckboxGroup 用 value / defaultValue 维护整组选中值,子项通过 name 参与分组——组内的子项必须传 name,否则开发环境会打印告警,该项会退化成不受组控制的独立复选框(仍继承组的 color / disabled 等配置)。
import { Checkbox, CheckboxGroup, Text } from '@skyroc/native-ui';
import type { CheckedState } from '@skyroc/native-ui';
import { useState } from 'react';
import { View } from 'react-native';
const FRUIT_ITEMS = [
{ label: 'Apple', value: 'apple' },
{ label: 'Orange', value: 'orange' },
{ label: 'Banana', value: 'banana' },
{ label: 'Grape', value: 'grape' }
];
const CheckboxGroupBasic = () => {
const [groupValue, setGroupValue] = useState<string[]>(['apple']);
const [lastChanged, setLastChanged] = useState('-');
// 全选 / 半选:父级选中态由子集数量推导
const parentChecked: CheckedState =
groupValue.length === 0 ? false : groupValue.length === FRUIT_ITEMS.length || 'indeterminate';
function handleToggleAll(checked: boolean) {
setGroupValue(checked ? FRUIT_ITEMS.map(item => item.value) : []);
}
return (
<View className="gap-3 bg-background p-4">
<Checkbox
checked={parentChecked}
onCheckedChange={handleToggleAll}
>
Check all
</Checkbox>
<CheckboxGroup
className="pl-6"
value={groupValue}
onChange={setGroupValue}
>
{FRUIT_ITEMS.map(item => (
<Checkbox
key={item.value}
name={item.value}
onCheckedChange={checked => setLastChanged(`${item.label} → ${checked}`)}
>
{item.label}
</Checkbox>
))}
</CheckboxGroup>
<Text className="text-sm text-muted-foreground">Selected: {groupValue.join(', ') || 'none'}</Text>
<Text className="text-sm text-muted-foreground">Last changed: {lastChanged}</Text>
</View>
);
};
export { CheckboxGroupBasic };「全选 / 半选」不是内置能力:上面的示例用一个独立 Checkbox 承担父级角色,选中态由子集数量推导成 true / false / 'indeterminate'。
数量上限
max 限制最多可选数量,达到上限后未选中项点击无效——不仅是视觉上的阻止,onCheckedChange 也不会触发,外部不会收到一个并未发生的变更。max 为 undefined 或小于等于 0 时视为不限制。
import { Checkbox, CheckboxGroup, Text } from '@skyroc/native-ui';
import { useState } from 'react';
import { View } from 'react-native';
const FRUIT_ITEMS = [
{ label: 'Apple', value: 'apple' },
{ label: 'Orange', value: 'orange' },
{ label: 'Banana', value: 'banana' },
{ label: 'Grape', value: 'grape' }
];
const CheckboxMax = () => {
const [maxValue, setMaxValue] = useState<string[]>([]);
return (
<View className="gap-3 bg-background p-4">
<CheckboxGroup
direction="horizontal"
max={2}
value={maxValue}
onChange={setMaxValue}
>
{FRUIT_ITEMS.map(item => (
<Checkbox
key={item.value}
name={item.value}
>
{item.label}
</Checkbox>
))}
</CheckboxGroup>
<Text className="text-sm text-muted-foreground">Selected: {maxValue.join(', ') || 'none'}</Text>
</View>
);
};
export { CheckboxMax };横向分组
direction="horizontal" 让分组横向排列并自动换行(flex-row flex-wrap),横纵间距随 size 变化。
import { Checkbox, CheckboxGroup } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxHorizontalGroup = () => {
return (
<View className="bg-background p-4">
<CheckboxGroup
defaultValue={['a']}
direction="horizontal"
>
<Checkbox name="a">A</Checkbox>
<Checkbox name="b">B</Checkbox>
<Checkbox name="c">C</Checkbox>
<Checkbox name="d">D</Checkbox>
</CheckboxGroup>
</View>
);
};
export { CheckboxHorizontalGroup };分组样式下发
color / size / shape / labelPosition / iconSize / checkedIcon / indeterminateIcon 都可以在组上统一设置,优先级是 子项 prop > 组配置 > 默认值。
import { Checkbox, CheckboxGroup } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxSquareGroup = () => {
return (
<View className="bg-background p-4">
<CheckboxGroup
color="warning"
defaultValue={['x']}
shape="square"
>
<Checkbox name="x">X</Checkbox>
<Checkbox name="y">Y</Checkbox>
<Checkbox name="z">Z</Checkbox>
</CheckboxGroup>
</View>
);
};
export { CheckboxSquareGroup };自定义图标
checkedIcon 替换选中态的勾,indeterminateIcon 替换半选态的横线。两者都是完整替换控件内部的节点,外框(背景、边框、圆角)仍由 shape 与 color 决定,图标颜色需要自己传。
import Feather from '@expo/vector-icons/Feather';
import { Checkbox } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxCustomIcon = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox
defaultChecked
shape="square"
checkedIcon={
<Feather
color="#fff"
name="star"
size={12}
/>
}
>
Custom checked icon
</Checkbox>
<Checkbox
checked="indeterminate"
shape="square"
indeterminateIcon={
<Feather
color="#fff"
name="more-horizontal"
size={12}
/>
}
>
Custom indeterminate icon
</Checkbox>
</View>
);
};
export { CheckboxCustomIcon };半选态在分组内不存在,因此 indeterminateIcon 只在独立使用的 Checkbox / CheckboxCard 上生效。
样式覆盖
className 追加到根容器,classNames 按 slot 细粒度覆盖,两者都与内置变体合并,冲突时以传入的类名为准(className 排在最后,优先级最高)。
Checkbox 的 slot:
| slot | 作用位置 |
|---|---|
root | 根容器 View,控制排列方向与间距 |
control | 指示器外层的可点 Pressable(含热区与 active:opacity-70) |
indicator | 指示器本体,背景 / 边框 / 圆角所在的节点 |
indicatorIcon | 内置勾 / 横线图标的 colorClassName,只接受 accent-* 颜色类 |
labelWrapper | 标签外层的可点 Pressable |
label | 标签文字,仅在 children 为字符串 / 数字时生效 |
CheckboxCard 的 slot:
| slot | 作用位置 |
|---|---|
root | 卡片容器 Pressable |
indicator | 指示器本体 |
indicatorIcon | 内置勾 / 横线图标的 colorClassName,只接受 accent-* 颜色类 |
content | 指示器之外的内容区(图标 + 文字块) |
icon | icon 的包裹节点 |
texts | 标题与描述的文字块 |
label | 标题文字,仅在 label 为字符串 / 数字时生效 |
description | 描述文字,仅在 description 为字符串 / 数字时生效 |
import { Checkbox, CheckboxCard } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxStyles = () => {
return (
<View className="gap-3 bg-background p-4">
<Checkbox
className="rounded-lg bg-muted p-3"
defaultChecked
>
className 作用于根容器
</Checkbox>
<Checkbox
defaultChecked
shape="square"
classNames={{
indicator: 'border-2 border-primary',
indicatorIcon: 'accent-warning',
label: 'font-semibold text-primary',
root: 'rounded-lg border border-primary p-3'
}}
>
classNames 按 slot 覆盖
</Checkbox>
<CheckboxCard
defaultChecked
description="卡片的 slot 同样可以逐个覆盖"
label="CheckboxCard"
classNames={{
description: 'text-primary/70',
label: 'text-base text-primary',
root: 'border-primary bg-primary/5'
}}
/>
</View>
);
};
export { CheckboxStyles };卡片
CheckboxCard 把图标、标题、描述组成一整块可点区域,整张卡片都是热区。checkboxPosition 决定指示器在内容左侧(默认)还是右侧。
import Feather from '@expo/vector-icons/Feather';
import { CheckboxCard } from '@skyroc/native-ui';
import { View } from 'react-native';
const CheckboxCardBasic = () => {
return (
<View className="gap-3 bg-background p-4">
<CheckboxCard
color="primary"
defaultChecked
description="Fast and reliable"
icon={
<Feather
color="#3b82f6"
name="wifi"
size={20}
/>
}
label="Wi-Fi"
/>
<CheckboxCard
checkboxPosition="right"
color="warning"
description="Mobile data connection"
icon={
<Feather
color="#22c55e"
name="smartphone"
size={20}
/>
}
label="Cellular"
shape="square"
/>
<CheckboxCard
color="success"
description="Direct device connection"
disabled
icon={
<Feather
color="#8b5cf6"
name="bluetooth"
size={20}
/>
}
label="Bluetooth"
/>
</View>
);
};
export { CheckboxCardBasic };卡片没有 labelPosition——文字块的排列由 checkboxPosition 决定;label 与 description 为字符串时自动包 Text,传节点则原样渲染。
卡片入组
CheckboxCard 与 Checkbox 共用同一套选中逻辑,可以直接放进 CheckboxGroup,max、去重、禁用下发全部照常生效。
import Feather from '@expo/vector-icons/Feather';
import { CheckboxCard, CheckboxGroup } from '@skyroc/native-ui';
import { View } from 'react-native';
const CARD_ITEMS = [
{
description: 'Fast and reliable',
icon: (
<Feather
color="#3b82f6"
name="wifi"
size={20}
/>
),
label: 'Wi-Fi',
value: 'wifi'
},
{
description: 'Mobile data connection',
icon: (
<Feather
color="#22c55e"
name="smartphone"
size={20}
/>
),
label: 'Cellular',
value: 'cellular'
},
{
description: 'Direct device connection',
icon: (
<Feather
color="#8b5cf6"
name="bluetooth"
size={20}
/>
),
label: 'Bluetooth',
value: 'bluetooth'
}
];
const CheckboxCardInGroup = () => {
return (
<View className="gap-3 bg-background p-4">
<CheckboxGroup
color="info"
defaultValue={['wifi']}
max={2}
>
{CARD_ITEMS.map(item => (
<CheckboxCard
key={item.value}
description={item.description}
icon={item.icon}
label={item.label}
name={item.value}
/>
))}
</CheckboxGroup>
</View>
);
};
export { CheckboxCardInGroup };卡片组
CheckboxGroupCard 是 CheckboxGroup + CheckboxCard 的数据驱动封装:用 items 一次声明整组,内部渲染卡片,因此卡片的 slot 覆盖只能走 itemClassNames。
import Feather from '@expo/vector-icons/Feather';
import { CheckboxGroupCard, Text } from '@skyroc/native-ui';
import { useState } from 'react';
import { View } from 'react-native';
const CARD_ITEMS = [
{
description: 'Fast and reliable',
icon: (
<Feather
color="#3b82f6"
name="wifi"
size={20}
/>
),
label: 'Wi-Fi',
value: 'wifi'
},
{
description: 'Mobile data connection',
icon: (
<Feather
color="#22c55e"
name="smartphone"
size={20}
/>
),
label: 'Cellular',
value: 'cellular'
},
{
description: 'Direct device connection',
icon: (
<Feather
color="#8b5cf6"
name="bluetooth"
size={20}
/>
),
label: 'Bluetooth',
value: 'bluetooth'
}
];
const CheckboxCardGroup = () => {
const [cardGroupValue, setCardGroupValue] = useState<string[]>(['wifi']);
return (
<View className="gap-3 bg-background p-4">
<CheckboxGroupCard
checkboxPosition="right"
color="info"
items={CARD_ITEMS}
value={cardGroupValue}
onChange={setCardGroupValue}
/>
<Text className="text-sm text-muted-foreground">Selected: {cardGroupValue.join(', ') || 'none'}</Text>
</View>
);
};
export { CheckboxCardGroup };热区与无障碍
指示器的可点区域按 size 撑到「控件行高 × 指示器边长」,再叠加 hitSlop={4};标签整块是第二个可点区域,小尺寸下不需要业务侧再包一层 Pressable。CheckboxCard 整张卡片即热区。
组件目前没有设置 accessibilityRole / accessibilityState,也不透传 RN 的无障碍属性,读屏器只会朗读标签文本、不播报选中状态。需要完整读屏语义时,暂时只能在外层自行包裹带 accessibilityRole="checkbox" 的容器。
API
Checkbox
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| checked | 受控选中态,'indeterminate' 为半选;位于 CheckboxGroup 内且传了 name 时被忽略 | boolean | 'indeterminate' | - |
| defaultChecked | 非受控初始选中态 | boolean | false |
| onCheckedChange | 选中态变化回调,分组内同样触发;命中组 max 上限而未生效时不触发 | (checked: boolean) => void | - |
| name | 分组内的唯一标识,位于 CheckboxGroup 内时必填,缺失会在开发环境告警 | string | number | - |
| color | 主题色,缺省时取组配置,再缺省为 primary | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'accent' | 'carbon' | 'secondary' | 'primary' |
| size | 尺寸预设,同时决定指示器边长、内部图标、标签字号与间距;缺省时取组配置 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| shape | 指示器形状,缺省时取组配置 | 'round' | 'square' | 'round' |
| iconSize | 指示器边长(px),传入后内部图标按 0.7 倍等比缩放;缺省时取组配置 | number | - |
| labelPosition | 标签相对指示器的位置,缺省时取组配置 | 'left' | 'right' | 'right' |
| labelDisabled | 只有指示器可点,标签点击不触发切换 | boolean | false |
| disabled | 禁用,与组级 disabled 取并集 | boolean | false |
| children | 标签内容,string / number 会被自动包裹为 Text | ReactNode | - |
| checkedIcon | 选中态自定义图标,替换控件内的默认勾 | ReactNode | - |
| indeterminateIcon | 半选态自定义图标,替换控件内的默认横线;分组内无效 | ReactNode | - |
| className | 根容器类名,合并到变体样式之后 | string | - |
| classNames | 各 slot 的类名覆盖 | SlotClassNames<CheckboxSlots> | - |
| testID | 测试标识,挂在根容器上 | string | - |
| ref | 根容器 View 的 ref,用于 measure / 滚动定位 | Ref<View> | - |
CheckboxGroup
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| children* | 子项,通常为 Checkbox 或 CheckboxCard | ReactNode | - |
| value | 受控选中值数组 | (string | number)[] | - |
| defaultValue | 非受控初始选中值数组 | (string | number)[] | [] |
| onChange | 选中值变化回调 | (value: (string | number)[]) => void | - |
| max | 最多可选数量,undefined 或 ≤ 0 表示不限制 | number | - |
| direction | 排列方向,horizontal 会自动换行 | 'vertical' | 'horizontal' | 'vertical' |
| disabled | 禁用整组,子项无法反选为可用 | boolean | false |
| color | 下发给所有子项的主题色 | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'accent' | 'carbon' | 'secondary' | - |
| size | 下发给所有子项的尺寸,同时决定分组的横纵间距 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| shape | 下发给所有子项的指示器形状 | 'round' | 'square' | - |
| iconSize | 下发给所有子项的指示器边长(px) | number | - |
| labelPosition | 下发给所有子项的标签位置 | 'left' | 'right' | - |
| checkedIcon | 下发给所有子项的选中态图标 | ReactNode | - |
| indeterminateIcon | 下发给所有子项的半选态图标 | ReactNode | - |
| className | 分组容器类名 | string | - |
| testID | 测试标识,挂在分组容器上 | string | - |
| ref | 分组容器 View 的 ref | Ref<View> | - |
CheckboxCard
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label | 标题,string / number 会被自动包裹为 Text | ReactNode | - |
| description | 描述,显示在标题下方 | ReactNode | - |
| icon | 卡片图标,显示在文字块之前 | ReactNode | - |
| checkboxPosition | 指示器相对内容的位置 | 'left' | 'right' | 'left' |
| checked | 受控选中态,'indeterminate' 为半选;位于 CheckboxGroup 内且传了 name 时被忽略 | boolean | 'indeterminate' | - |
| defaultChecked | 非受控初始选中态 | boolean | false |
| onCheckedChange | 选中态变化回调,分组内同样触发;命中组 max 上限而未生效时不触发 | (checked: boolean) => void | - |
| name | 分组内的唯一标识,位于 CheckboxGroup 内时必填,缺失会在开发环境告警 | string | number | - |
| color | 主题色,缺省时取组配置,再缺省为 primary | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'accent' | 'carbon' | 'secondary' | 'primary' |
| size | 尺寸预设,决定指示器边长与内部图标;卡片文字字号固定,不随 size 变化 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| shape | 指示器形状,缺省时取组配置 | 'round' | 'square' | 'round' |
| iconSize | 指示器边长(px),内部图标按 0.7 倍等比缩放 | number | - |
| checkedIcon | 选中态自定义图标 | ReactNode | - |
| indeterminateIcon | 半选态自定义图标,分组内无效 | ReactNode | - |
| disabled | 禁用,与组级 disabled 取并集 | boolean | false |
| className | 卡片容器类名 | string | - |
| classNames | 各 slot 的类名覆盖 | SlotClassNames<CheckboxCardSlots> | - |
| testID | 测试标识,挂在卡片容器上 | string | - |
| ref | 卡片根节点的 ref,根节点是 Pressable,实例类型同为 View | Ref<View> | - |
CheckboxGroupCard
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items* | 卡片数据源 | CheckboxGroupCardItem[] | - |
| value | 受控选中值数组 | (string | number)[] | - |
| defaultValue | 非受控初始选中值数组 | (string | number)[] | - |
| onChange | 选中值变化回调 | (value: (string | number)[]) => void | - |
| max | 最多可选数量,undefined 或 ≤ 0 表示不限制 | number | - |
| checkboxPosition | 指示器相对内容的位置,下发给所有卡片 | 'left' | 'right' | 'left' |
| direction | 排列方向 | 'vertical' | 'horizontal' | 'vertical' |
| disabled | 禁用整组 | boolean | false |
| color | 下发给所有卡片的主题色 | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'accent' | 'carbon' | 'secondary' | - |
| size | 下发给所有卡片的尺寸预设,同时决定分组的横纵间距 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| shape | 下发给所有卡片的指示器形状 | 'round' | 'square' | - |
| iconSize | 下发给所有卡片的指示器边长(px) | number | - |
| checkedIcon | 下发给所有卡片的选中态图标 | ReactNode | - |
| indeterminateIcon | 下发给所有卡片的半选态图标 | ReactNode | - |
| itemClassNames | 覆盖每张卡片各 slot 的类名;卡片由组件内部渲染,只能从这里透传 | SlotClassNames<CheckboxCardSlots> | - |
| className | 分组容器类名 | string | - |
| testID | 测试标识,挂在分组容器上 | string | - |
| ref | 分组容器 View 的 ref | Ref<View> | - |
类型
import type {
CheckboxCardProps,
CheckboxCardSlots,
CheckboxGroupCardItem,
CheckboxGroupCardProps,
CheckboxGroupContextValue,
CheckboxGroupDirection,
CheckboxGroupProps,
CheckboxIndicatorSlots,
CheckboxLabelPosition,
CheckboxPosition,
CheckboxProps,
CheckboxShape,
CheckboxSide,
CheckboxSizes,
CheckboxSlots,
CheckboxValue,
CheckedState
} from '@skyroc/native-ui';CheckedState
选中态取值,'indeterminate' 为半选(纯展示态,点击后进入全选)。
CheckboxValue
分组内 name / value 的取值范围,CheckboxGroup 对它做泛型化以配合 useState<string[]> 的写法。
CheckboxShape
指示器形状,round 为圆形,square 为圆角方形。
CheckboxSide
横向位置,CheckboxLabelPosition 与 CheckboxPosition 都是它的别名。
CheckboxLabelPosition
标签相对指示器的位置,等价于 CheckboxSide。
CheckboxPosition
卡片中指示器相对内容的位置,等价于 CheckboxSide。
CheckboxGroupDirection
CheckboxGroup 的排列方向,horizontal 会自动换行。
CheckboxSlots
Checkbox 可通过 classNames 覆盖的 slot 名称。
CheckboxCardSlots
CheckboxCard 可通过 classNames 覆盖的 slot 名称。
CheckboxIndicatorSlots
指示器相关的 slot 名称,Checkbox 与 CheckboxCard 共用这两个键。
SlotClassNames
classNames 的取值形态:把 slot 名映射到类名,每个 slot 都可选。本页用到的 slot 见 CheckboxSlots / CheckboxCardSlots / CheckboxIndicatorSlots。
CheckboxGroupCardItem
CheckboxGroupCard 的单条数据。
| 字段 | 类型 | 说明 |
|---|---|---|
| value* | string | number | 唯一标识,对应选中值数组里的元素。 |
| label* | ReactNode | 标题。 |
| description | ReactNode | 描述文本。 |
| icon | ReactNode | 卡片图标。 |
| disabled | boolean | 是否禁用该项。 |
CheckboxSizes
由 size / iconSize 解析出的像素尺寸,resolveCheckboxSizes 的返回值。
| 字段 | 类型 | 说明 |
|---|---|---|
| control | number | 指示器边长(px)。 |
| controlRow | number | 控件所在行的高度(px),用于与标签首行对齐。 |
| innerIcon | number | 内部勾 / 横线图标的边长(px)。 |
CheckboxGroupContextValue
CheckboxGroup 下发给子项的上下文,自定义子项复用分组选中逻辑时才需要关心。
| 字段 | 类型 | 说明 |
|---|---|---|
| isChecked | (name: string | number) => boolean | 判断某个 name 是否选中。 |
| toggle | (name: string | number, checked: boolean) => boolean | 切换某项,返回变更是否生效(命中 max 时返回 false)。 |
| isMaxReached | () => boolean | 是否已达选中上限。 |
| disabled | boolean | 整组是否禁用。 |
| color | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'accent' | 'carbon' | 'secondary' | 组级主题色。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 组级尺寸预设。 |
| shape | 'round' | 'square' | 组级指示器形状。 |
| iconSize | number | 组级指示器边长(px)。 |
| labelPosition | 'left' | 'right' | 组级标签位置。 |
| checkedIcon | ReactNode | 组级选中态图标。 |
| indeterminateIcon | ReactNode | 组级半选态图标。 |