FormCheck

基础表单

基于 Bootstrap 5 的复选与单选组件，为原生 checkbox、radio 输入框提供统一的自定义外观，包含 FormCheck 容器、FormCheckInput 输入框与 FormCheckLabel 标签，支持不确定状态、禁用、开关、行内/反向布局及有效/无效校验状态

Component Demo

Basic usage and examples of the FormCheck component

基础用法

默认复选框

已选中的复选框

不确定状态

不确定状态的复选框

通过 indeterminate 属性设置原生 indeterminate 状态，常用于「全选」场景的部分选中状态

禁用状态

禁用的复选框

禁用且已选中的复选框

添加 disabled 属性后，关联的标签会自动呈现较浅的颜色以提示输入框状态

单选按钮

默认单选按钮

默认选中的单选按钮

相同 name 的单选按钮互斥，同一时刻只能选中一个

禁用单选按钮

禁用的单选按钮

禁用且选中的单选按钮

开关

默认开关

已选中的开关

禁用的开关

禁用且选中的开关

将 FormCheck 的 type 设置为 switch 即可渲染开关样式，建议为输入框添加 role="switch" 以向辅助技术更准确地传达控件性质

反向布局

反向复选框

禁用的反向复选框

反向开关

通过 reverse 属性应用 form-check-reverse 类，将输入框放到标签的另一侧

无标签

没有标签文本时可省略 FormCheck 容器，但仍需通过 aria-label 等方式提供可访问名称

校验状态

有效的复选框

看起来不错！

无效的复选框

必须勾选此复选框。

通过 isValid / isInvalid 属性应用 is-valid / is-invalid 校验样式，配合 FormFeedback 提供有效/无效反馈文本

交互演示

复选框（已选中）

开关（关）

选项 1

选项 2

API Documentation

Complete API reference for the FormCheck component

Props

Common Props

属性名	类型	默认值	描述
`children`	`ReactNode`	-	子元素，通常为 FormCheckInput 与 FormCheckLabel 的组合
`className`	`string`	-	自定义类名
`inline`	`boolean`	`false`	是否应用行内布局（`form-check-inline`），使多个复选或单选控件水平排列
`reverse`	`boolean`	`false`	是否应用反向布局（`form-check-reverse`），将输入框与标签位置互换
`type`	`FormCheckType`	-	控件类型，可选 `checkbox`、`radio`、`switch`；为 `switch` 时附加 `form-switch` 类以渲染开关样式
`...rest`	`HTMLAttributes<HTMLDivElement>`	-	根元素的所有原生属性（如 `onClick`、`aria-*` 等）

FormCheckInput

属性名	类型	默认值	描述
`checked`	`boolean`	-	原生 `checked` 属性，受控选中状态
`className`	`string`	-	自定义类名
`defaultChecked`	`boolean`	-	原生 `defaultChecked` 属性，非受控的默认选中状态
`disabled`	`boolean`	-	是否禁用输入框，关联的标签会自动呈现较浅的颜色
`id`	`string`	-	原生 `id` 属性，用于与 `label` 的 `htmlFor` 关联
`indeterminate`	`boolean`	`false`	是否设置不确定（半选中）状态，通过回调 ref 设置原生 `indeterminate` 属性实现
`isInvalid`	`boolean`	`false`	是否应用无效状态样式（`is-invalid`），通常配合校验反馈使用
`isValid`	`boolean`	`false`	是否应用有效状态样式（`is-valid`）
`name`	`string`	-	原生 `name` 属性，同名的单选按钮互斥
`type`	`'checkbox' \| 'radio'`	`'checkbox'`	输入框类型，可选 `checkbox`、`radio`
`value`	`string`	-	原生 `value` 属性
`...rest`	`InputHTMLAttributes<HTMLInputElement>`	-	根元素的所有原生属性（如 `onChange`、`role`、`required` 等）

FormCheckLabel

属性名	类型	默认值	描述
`children`	`ReactNode`	-	标签内容
`className`	`string`	-	自定义类名
`htmlFor`	`string`	-	原生 `for` 属性，关联对应输入框的 `id`
`...rest`	`LabelHTMLAttributes<HTMLLabelElement>`	-	根元素的所有原生属性（如 `onClick`、`aria-*` 等）

Type Definitions

FormCheckInputProps

复选/单选输入框组件属性接口

export interface FormCheckInputProps extends Omit<
  InputHTMLAttributes<HTMLInputElement>,
  'size' | 'type'
> {
  indeterminate?: boolean;
  isInvalid?: boolean;
  isValid?: boolean;
  type?: 'checkbox' | 'radio';
}

FormCheckLabelProps

复选/单选标签组件属性接口

export interface FormCheckLabelProps extends LabelHTMLAttributes<HTMLLabelElement> {}

FormCheckProps

复选/单选容器组件属性接口

export interface FormCheckProps extends HTMLAttributes<HTMLDivElement> {
  inline?: boolean;
  reverse?: boolean;
  type?: FormCheckType;
}

FormCheckType

复选/单选控件类型

export type FormCheckType = 'checkbox' | 'radio' | 'switch';