选择组 Selector

在一组选项中选择一个或多个。

安装

npm install antd-mobile@5.43.0

antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 unstableSetRender 注册 createRoot，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 <html data-prefers-color-scheme="dark"> 切换。

示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 DemoBlock 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。

在一组选项中选择一个或多个。

何时使用

提供多个选项供用户选择，一般在筛选和表单中使用。

示例

Selector

属性

属性	说明	类型	默认值
columns	列数（注意 `grid` 布局在 IOS 9 下不支持）	`number`	-
defaultValue	默认项	`SelectorValue[]`	`[]`
disabled	是否全部禁止选中	`boolean`	`false`
fieldNames	自定义 options 中 label value disabled 的字段	`{ label: string, value: string, disabled: string }`	`{ label: 'label', value: 'value',disabled:'disabled' }`
multiple	是否允许多选	`boolean`	`false`
onChange	选项改变时触发	`(value: SelectorValue[], extend: { items: SelectorOption[] }) => void`	-
options	可选项	`SelectorOption[]`	-
showCheckMark	是否显示对勾角标	`boolean`	`true`
value	选中项	`SelectorValue[]`	-

CSS 变量

属性	说明	默认值
--border	边框样式	`none`
--border-radius	选项的圆角	`2px`
--checked-border	选中时的边框样式	`none`
--checked-color	选中时的背景色	`var(--adm-color-wathet)`
--checked-text-color	选中时的文字颜色	`var(--adm-color-primary)`
--color	背景色	`#f5f5f5`
--padding	选项的 padding	`8px 16px`
--text-color	文字颜色	`var(--adm-color-text)`
--gap	间距大小，仅在 `columns` 存在时生效	`8px`
--gap-horizontal	水平方向的间距大小，仅在 `columns` 存在时生效	`var(--gap)`
--gap-vertical	垂直方向的间距大小，仅在 `columns` 存在时生效	`var(--gap)`

类型定义

SelectorValue

type SelectorValue = string | number

SelectorOption

属性	说明	类型	默认值
description	描述	`ReactNode`	-
disabled	是否禁用	`boolean`	`false`
label	文字	`ReactNode`	-
value	选项的值	`SelectorValue`	-

泛型

Selector 支持泛型，你可以通过下面的这种方式手动控制 value onChange 等属性的类型：

<Selector<'a' | 'b' | number>
  options={options}
  defaultValue={['a']}
  onChange={arr => console.log(arr)}
/>