Checkbox 多选框

一组备选项中进行多选

基础用法

单独使用可以表示两种状态之间的切换。

要使用 Checkbox 组件，只需要配置 type: 'checkbox'，选中意味着变量的值为 true。默认绑定变量的值会是 Boolean，选中为 true。

[
  {
    type: "checkbox",
    name: "checkbox",
    text: "选项"
  }
]

显示配置

禁用状态

多选框不可用状态。

设置 disabled 属性即可，它接受一个 Boolean，true 为禁用，也可以接受一个返回 Boolean 的函数。

[
  {
    type: "checkbox",
    name: "checkbox",
    text: "选项",
    disabled: () => true
  }
]

显示配置

自定义选中值

通过 activeValue 和 inactiveValue 自定义选中和未选中时的值。

设置 activeValue 为选中时的值，inactiveValue 为未选中时的值。

[
  {
    type: "checkbox",
    name: "checkbox",
    text: "选项",
    activeValue: "yes",
    inactiveValue: "no"
  }
]

显示配置

数值类型

当需要绑定数值类型时，可以使用 filter: 'number' 配合默认的 activeValue/inactiveValue。

配置 filter 为 'number' 时，默认 activeValue 为 1，inactiveValue 为 0。

[
  {
    type: "checkbox",
    name: "checkbox",
    text: "选项",
    filter: "number"
  }
]

显示配置

使用 Label 显示

通过 useLabel 属性控制是否使用 label 作为显示内容。

设置 useLabel 为 true 时，不显示 text 内容，由外部 label 控制显示。

[
  {
    type: "checkbox",
    name: "checkbox",
    text: "选项",
    useLabel: true
  }
]

显示配置

多选框组

适用于多个勾选框绑定到同一个数组的情景，通过是否勾选来表示这一组选项中选中的项。

checkbox-group 元素能把多个 checkbox 管理为一组，绑定值为数组类型。

[
  {
    type: "checkbox-group",
    name: "checkbox",
    text: "选项",
    options: [
      {
        text: "选项1",
        value: 1
      },
      {
        text: "选项2",
        value: 2
      },
      {
        text: "选项3",
        value: 3
      }
    ]
  }
]

显示配置

多选框组禁用选项

在选项中设置 disabled 可禁用单个选项。

在 options 中设置 disabled: true 可禁用该选项。

[
  {
    type: "checkbox-group",
    name: "checkbox",
    text: "选项",
    options: [
      {
        text: "选项1",
        value: 1
      },
      {
        text: "选项2",
        value: 2,
        disabled: true
      },
      {
        text: "选项3",
        value: 3
      }
    ]
  }
]

显示配置

动态选项

options 支持函数形式，可根据表单状态动态生成选项。

{
  type: 'checkbox-group',
  name: 'checkbox',
  text: '选项',
  options: (mForm, { model, formValue }) => {
    // 根据表单值动态返回选项
    return [
      { text: '选项A', value: 'a' },
      { text: '选项B', value: 'b' }
    ];
  }
}

Checkbox Attributes

参数	说明	类型	可选值	默认值
name	绑定值	string	—	—
text	表单标签	string	—	—
disabled	是否禁用	boolean / FilterFunction	—	false
activeValue	选中时的值	string / number	—	true（filter 为 'number' 时默认 1）
inactiveValue	未选中时的值	string / number	—	false（filter 为 'number' 时默认 0）
useLabel	是否使用外部 label 显示	boolean	—	false
filter	值过滤器	'number' / Function	—	—
onChange	值变化时触发的函数	OnChangeHandler	—	—

查看 FilterFunction / OnChangeHandler 及关联类型定义

export type FilterFunction<T = boolean> = (
  mForm: FormState | undefined,
  data: {
    model: FormValue;
    values: FormValue;
    parent?: FormValue;
    formValue: FormValue;
    prop: string;
    config: any;
    index?: number;
    getFormValue: (prop: string) => any;
  },
) => T;

export type OnChangeHandler = (mForm: FormState | undefined, value: any, data: OnChangeHandlerData) => any;

export interface OnChangeHandlerData {
  model: FormValue;
  values?: Readonly<FormValue> | null;
  parent?: FormValue;
  formValue?: FormValue;
  config: Readonly<any>;
  prop: string;
  changeRecords: ChangeRecord[];
  setModel: (prop: string, value: any) => void;
  setFormValue: (prop: string, value: any) => void;
}

export interface ChangeRecord {
  propPath?: string;
  value: any;
}

export type FormValue = Record<string | number, any>;

配置类型

查看 CheckboxConfig / CheckboxGroupConfig 配置类型定义

export interface CheckboxConfig extends FormItem {
  type: 'checkbox';
  activeValue?: number | string;
  inactiveValue?: number | string;
  useLabel?: boolean;
}

export interface CheckboxGroupConfig extends FormItem {
  type: 'checkbox-group' | 'checkboxGroup';
  options: CheckboxGroupOption[] | FilterFunction<CheckboxGroupOption[]>;
}

export interface FormItem {
  /** vnode的key值，默认是遍历数组时的index */
  __key?: string | number;
  /** 表单域标签的的宽度，例如 '50px'。支持 auto。 */
  labelWidth?: string | number;
  /** label 标签的title属性 */
  labelTitle?: string;
  className?: string;
  /** 字段名 */
  name?: string | number;
  /** 额外的提示信息，和 help 类似，当提示文案同时出现时，可以使用这个。 */
  extra?: string | FilterFunction<string>;
  /** 配置提示信息 */
  tooltip?: ToolTipConfigType | FilterFunction<ToolTipConfigType>;
  /** 是否置灰 */
  disabled?: boolean | FilterFunction;
  /** 使用表单中的值作为key，例如配置了text，则使用model.text作为key */
  key?: string;
  /** 是否显示 */
  display?: boolean | 'expand' | FilterFunction<boolean | 'expand'>;
  /** 值发生改变时调用的方法 */
  onChange?: OnChangeHandler;
  /** label 标签的文本 */
  text?: string | FilterFunction<string>;
  /** 右侧感叹号 */
  tip?: string;

  filter?: 'number' | OnChangeHandler;
  /** 是否去除首尾空格 */
  trim?: boolean;
  /** 默认值 */
  defaultValue?: any | DefaultValueFunction;
  /** 表单验证规则 */
  rules?: Rule[];
  extensible?: boolean;
  dynamicKey?: string;
  /** 是否需要显示`展开更多配置` */
  expand?: boolean;
  style?: Record<string, any>;
  fieldStyle?: Record<string, any>;
  labelPosition?: 'top' | 'left' | 'right';
}

CheckboxGroup Attributes

参数	说明	类型	可选值	默认值
name	绑定值	string	—	—
text	表单标签	string	—	—
disabled	是否禁用	boolean / FilterFunction	—	false
options	选项列表	Array / FilterFunction	—	—
onChange	值变化时触发的函数	OnChangeHandler	—	—

options item

参数	说明	类型	可选值	默认值
value	选项的值	any	—	—
text	选项的标签	string	—	—
disabled	是否禁用该选项	boolean	—	false