Skyroc Native UI

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' 半选态。

CheckboxBasic.tsx
Loading…
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 而不是硬编码白色。

颜色选中背景语义
primarybg-primary常规选择(默认)
destructivebg-destructive危险项,如批量删除
successbg-success成功、已完成
warningbg-warning需要注意的选项
infobg-info信息性选项
accentbg-accent强调色
carbonbg-carbon中性深色
secondarybg-secondary次级、弱化选项
CheckboxColor.tsx
Loading…
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 同时决定指示器边长、内部勾的大小、标签字号与指示器到标签的间距:

尺寸指示器内部图标控件行高标签字号指示器与标签间距
xs14916text-xs4
sm161120text-sm6
md201424text-base8
lg241624text-base10
xl281824text-base12
2xl322028text-lg14
CheckboxSize.tsx
Loading…
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)。

CheckboxShape.tsx
Loading…
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 决定。

CheckboxIconSize.tsx
Loading…
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 取并集——组禁用后子项无法把自己反选为可用。

CheckboxDisabled.tsx
Loading…
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 只关掉标签的点击,指示器照常可点。

CheckboxLabelPosition.tsx
Loading…
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 };

childrenstring / number 时会自动包一层 Text 并套用 label slot 的样式;传自定义节点时不做包裹,样式需要自己写。childrennull / undefined / 布尔值时整个标签区不渲染,也不会留下一个撑开 gap 的空节点。

多行标签

标签换行时指示器保持贴首行,不会随文本块整体垂直居中。

CheckboxMultilineLabel.tsx
Loading…
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 依旧会触发。

CheckboxControlled.tsx
Loading…
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 };

分组

CheckboxGroupvalue / defaultValue 维护整组选中值,子项通过 name 参与分组——组内的子项必须传 name,否则开发环境会打印告警,该项会退化成不受组控制的独立复选框(仍继承组的 color / disabled 等配置)。

CheckboxGroupBasic.tsx
Loading…
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 也不会触发,外部不会收到一个并未发生的变更。maxundefined 或小于等于 0 时视为不限制。

CheckboxMax.tsx
Loading…
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 变化。

CheckboxHorizontalGroup.tsx
Loading…
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 > 组配置 > 默认值

CheckboxSquareGroup.tsx
Loading…
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 替换半选态的横线。两者都是完整替换控件内部的节点,外框(背景、边框、圆角)仍由 shapecolor 决定,图标颜色需要自己传。

CheckboxCustomIcon.tsx
Loading…
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指示器之外的内容区(图标 + 文字块)
iconicon 的包裹节点
texts标题与描述的文字块
label标题文字,仅在 label 为字符串 / 数字时生效
description描述文字,仅在 description 为字符串 / 数字时生效
CheckboxStyles.tsx
Loading…
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 决定指示器在内容左侧(默认)还是右侧。

CheckboxCardBasic.tsx
Loading…
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 决定;labeldescription 为字符串时自动包 Text,传节点则原样渲染。

卡片入组

CheckboxCardCheckbox 共用同一套选中逻辑,可以直接放进 CheckboxGroupmax、去重、禁用下发全部照常生效。

CheckboxCardInGroup.tsx
Loading…
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 };

卡片组

CheckboxGroupCardCheckboxGroup + CheckboxCard 的数据驱动封装:用 items 一次声明整组,内部渲染卡片,因此卡片的 slot 覆盖只能走 itemClassNames

CheckboxCardGroup.tsx
Loading…
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};标签整块是第二个可点区域,小尺寸下不需要业务侧再包一层 PressableCheckboxCard 整张卡片即热区。

组件目前没有设置 accessibilityRole / accessibilityState,也不透传 RN 的无障碍属性,读屏器只会朗读标签文本、不播报选中状态。需要完整读屏语义时,暂时只能在外层自行包裹带 accessibilityRole="checkbox" 的容器。

API

Checkbox

属性说明类型默认值
checked受控选中态,'indeterminate' 为半选;位于 CheckboxGroup 内且传了 name 时被忽略boolean | 'indeterminate'-
defaultChecked非受控初始选中态booleanfalse
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只有指示器可点,标签点击不触发切换booleanfalse
disabled禁用,与组级 disabled 取并集booleanfalse
children标签内容,string / number 会被自动包裹为 TextReactNode-
checkedIcon选中态自定义图标,替换控件内的默认勾ReactNode-
indeterminateIcon半选态自定义图标,替换控件内的默认横线;分组内无效ReactNode-
className根容器类名,合并到变体样式之后string-
classNames各 slot 的类名覆盖SlotClassNames<CheckboxSlots>-
testID测试标识,挂在根容器上string-
ref根容器 View 的 ref,用于 measure / 滚动定位Ref<View>-

CheckboxGroup

属性说明类型默认值
children*子项,通常为 Checkbox 或 CheckboxCardReactNode-
value受控选中值数组(string | number)[]-
defaultValue非受控初始选中值数组(string | number)[][]
onChange选中值变化回调(value: (string | number)[]) => void-
max最多可选数量,undefined 或 ≤ 0 表示不限制number-
direction排列方向,horizontal 会自动换行'vertical' | 'horizontal''vertical'
disabled禁用整组,子项无法反选为可用booleanfalse
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 的 refRef<View>-

CheckboxCard

属性说明类型默认值
label标题,string / number 会被自动包裹为 TextReactNode-
description描述,显示在标题下方ReactNode-
icon卡片图标,显示在文字块之前ReactNode-
checkboxPosition指示器相对内容的位置'left' | 'right''left'
checked受控选中态,'indeterminate' 为半选;位于 CheckboxGroup 内且传了 name 时被忽略boolean | 'indeterminate'-
defaultChecked非受控初始选中态booleanfalse
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 取并集booleanfalse
className卡片容器类名string-
classNames各 slot 的类名覆盖SlotClassNames<CheckboxCardSlots>-
testID测试标识,挂在卡片容器上string-
ref卡片根节点的 ref,根节点是 Pressable,实例类型同为 ViewRef<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禁用整组booleanfalse
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 的 refRef<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' 为半选(纯展示态,点击后进入全选)。

boolean | 'indeterminate'

CheckboxValue

分组内 name / value 的取值范围,CheckboxGroup 对它做泛型化以配合 useState<string[]> 的写法。

string | number

CheckboxShape

指示器形状,round 为圆形,square 为圆角方形。

'round' | 'square'

CheckboxSide

横向位置,CheckboxLabelPosition 与 CheckboxPosition 都是它的别名。

'left' | 'right'

CheckboxLabelPosition

标签相对指示器的位置,等价于 CheckboxSide。

'left' | 'right'

CheckboxPosition

卡片中指示器相对内容的位置,等价于 CheckboxSide。

'left' | 'right'

CheckboxGroupDirection

CheckboxGroup 的排列方向,horizontal 会自动换行。

'horizontal' | 'vertical'

CheckboxSlots

Checkbox 可通过 classNames 覆盖的 slot 名称。

'control' | 'indicator' | 'indicatorIcon' | 'label' | 'labelWrapper' | 'root'

CheckboxCardSlots

CheckboxCard 可通过 classNames 覆盖的 slot 名称。

'content' | 'description' | 'icon' | 'indicator' | 'indicatorIcon' | 'label' | 'root' | 'texts'

CheckboxIndicatorSlots

指示器相关的 slot 名称,Checkbox 与 CheckboxCard 共用这两个键。

'indicator' | 'indicatorIcon'

SlotClassNames

classNames 的取值形态:把 slot 名映射到类名,每个 slot 都可选。本页用到的 slot 见 CheckboxSlots / CheckboxCardSlots / CheckboxIndicatorSlots。

Partial<Record<Slots, string>>

CheckboxGroupCardItem

CheckboxGroupCard 的单条数据。

字段类型说明
value*string | number唯一标识,对应选中值数组里的元素。
label*ReactNode标题。
descriptionReactNode描述文本。
iconReactNode卡片图标。
disabledboolean是否禁用该项。

CheckboxSizes

由 size / iconSize 解析出的像素尺寸,resolveCheckboxSizes 的返回值。

字段类型说明
controlnumber指示器边长(px)。
controlRownumber控件所在行的高度(px),用于与标签首行对齐。
innerIconnumber内部勾 / 横线图标的边长(px)。

CheckboxGroupContextValue

CheckboxGroup 下发给子项的上下文,自定义子项复用分组选中逻辑时才需要关心。

字段类型说明
isChecked(name: string | number) => boolean判断某个 name 是否选中。
toggle(name: string | number, checked: boolean) => boolean切换某项,返回变更是否生效(命中 max 时返回 false)。
isMaxReached() => boolean是否已达选中上限。
disabledboolean整组是否禁用。
color'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'accent' | 'carbon' | 'secondary'组级主题色。
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'组级尺寸预设。
shape'round' | 'square'组级指示器形状。
iconSizenumber组级指示器边长(px)。
labelPosition'left' | 'right'组级标签位置。
checkedIconReactNode组级选中态图标。
indeterminateIconReactNode组级半选态图标。