ion-checkbox

阴影

复选框允许从一组选项中选择多个选项。激活时，它们显示为已选中（打勾）。单击复选框将切换 `checked` 属性。也可以通过设置 `checked` 属性以编程方式选中它们。

基本用法

标签位置

开发人员可以使用 `labelPlacement` 属性来控制标签相对于控件的位置。此属性反映了 flexbox `flex-direction` 属性。

对齐方式

开发人员可以使用 `alignment` 属性来控制标签和控件在横轴上的对齐方式。此属性反映了 flexbox `align-items` 属性。

注意

可以使用 `alignment` 属性对齐堆叠的复选框。当标签和控件需要水平居中时，这很有用。

对齐

开发人员可以使用 `justify` 属性来控制标签和控件在一行上的排列方式。此属性反映了 flexbox `justify-content` 属性。

注意

`ion-item` 仅用于演示中，以强调 `justify` 的工作原理。它不是 `justify` 正确运行所必需的。

不确定的复选框

标签内的链接

复选框标签有时会带有链接。这些链接可以提供与复选框相关的更多信息。但是，单击链接不应选中复选框。为了实现这一点，我们可以使用 stopPropagation 来阻止单击事件冒泡。使用这种方法时，标签的其余部分仍然是可单击的。

主题

CSS 自定义属性

接口

CheckboxChangeEventDetail

interface CheckboxChangeEventDetail<T = any> {
  value: T;
  checked: boolean;
}

CheckboxCustomEvent

虽然不是必需的，但此接口可以用于代替 `CustomEvent` 接口，以便更强大地对从该组件发出的 Ionic 事件进行类型化。

interface CheckboxCustomEvent<T = any> extends CustomEvent {
  detail: CheckboxChangeEventDetail<T>;
  target: HTMLIonCheckboxElement;
}

从旧版复选框语法迁移

在 Ionic 7.0 中引入了更简单的复选框语法。这种新语法减少了设置复选框所需的样板代码，解决了可访问性问题，并改善了开发人员体验。

开发人员可以一次迁移一个复选框。虽然开发人员可以继续使用旧版语法，但我们建议尽快迁移。

使用现代语法

使用现代语法涉及删除 `ion-label` 并将标签直接传递到 `ion-checkbox` 中。可以使用 `ion-checkbox` 上的 `labelPlacement` 属性配置标签的位置。可以使用 `ion-checkbox` 上的 `justify` 属性控制标签和控件在一行上的排列方式。

JavaScript

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox>Checkbox Label</ion-checkbox>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="fixed">Checkbox Label</ion-checkbox>
</ion-item>

<!-- Checkbox at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="end">Checkbox Label</ion-checkbox>
</ion-item>

Angular

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox>Checkbox Label</ion-checkbox>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox labelPlacement="fixed">Checkbox Label</ion-checkbox>
</ion-item>

<!-- Checkbox at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox labelPlacement="end">Checkbox Label</ion-checkbox>
</ion-item>

React

{/* Basic */}

{/* Before */}
<IonItem>
  <IonLabel>Checkbox Label</IonLabel>
  <IonCheckbox></IonCheckbox>
</IonItem>

{/* After */}
<IonItem>
  <IonCheckbox>Checkbox Label</IonCheckbox>
</IonItem>

{/* Fixed Labels */}

{/* Before */}
<IonItem>
  <IonLabel position="fixed">Checkbox Label</IonLabel>
  <IonCheckbox></IonCheckbox>
</IonItem>

{/* After */}
<IonItem>
  <IonCheckbox labelPlacement="fixed">Checkbox Label</IonCheckbox>
</IonItem>

{/* Checkbox at the start of line, Label at the end of line */}

{/* Before */}
<IonItem>
  <IonLabel slot="end">Checkbox Label</IonLabel>
  <IonCheckbox></IonCheckbox>
</IonItem>

{/* After */}
<IonItem>
  <IonCheckbox labelPlacement="end">Checkbox Label</IonCheckbox>
</IonItem>

Vue

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox>Checkbox Label</ion-checkbox>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="fixed">Checkbox Label</ion-checkbox>
</ion-item>

<!-- Checkbox at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="end">Checkbox Label</ion-checkbox>
</ion-item>

注意

在 Ionic 的早期版本中，`ion-checkbox` 需要在 `ion-item` 中才能正常运行。从 Ionic 7.0 开始，`ion-checkbox` 仅应在将项目放置在 `ion-list` 中时才用于 `ion-item` 中。此外，`ion-checkbox` 也不再需要在 `ion-item` 中才能正常运行。

使用旧版语法

Ionic 使用启发式方法来检测应用程序是否使用现代复选框语法。在某些情况下，可能更适合继续使用旧版语法。开发人员可以将 `ion-checkbox` 上的 `legacy` 属性设置为 `true`，以强制该复选框实例使用旧版语法。

属性

alignment

描述	如何控制复选框和标签在横轴上的对齐方式。`“start”`：标签和控件将在 LTR 中的横轴左侧出现，在 RTL 中的右侧出现。`“center”`：标签和控件将在 LTR 和 RTL 中的横轴中心出现。设置此属性将更改复选框的 `display` 为 `block`。
属性	alignment
类型	"center" ｜ "start" ｜ undefined
默认	undefined

checked

描述	如果为 `true`，则复选框被选中。
属性	checked
类型	布尔值
默认	false

color

描述	要从应用程序颜色调色板中使用的颜色。默认选项包括：`“primary”`、`“secondary”`、`“tertiary”`、`“success”`、`“warning”`、`“danger”`、`“light”`、`“medium”` 和 `“dark”`。有关颜色的更多信息，请参阅 主题。
属性	color
类型	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
默认	undefined

disabled

描述	如果为 `true`，则用户无法与复选框交互。
属性	disabled
类型	布尔值
默认	false

indeterminate

描述	如果为 `true`，则复选框在视觉上将显示为不确定。
属性	indeterminate
类型	布尔值
默认	false

justify

描述	如何在同一行内排列标签和复选框。"start": 标签和复选框将在 LTR 中显示在左侧，在 RTL 中显示在右侧。"end": 标签和复选框将在 LTR 中显示在右侧，在 RTL 中显示在左侧。"space-between": 标签和复选框将在该行的两端出现，两元素之间留有间距。设置此属性会将复选框的display更改为block。
属性	对齐方式
类型	"end" ｜ "space-between" ｜ "start" ｜ 未定义
默认	undefined

labelPlacement

描述	指定标签相对于复选框的位置。"start": 标签将出现在 LTR 中的复选框左侧，在 RTL 中出现在右侧。"end": 标签将出现在 LTR 中的复选框右侧，在 RTL 中出现在左侧。"fixed": 标签的行为与"start"相同，但它还具有固定宽度。长文本将用省略号 ("...") 截断。"stacked": 标签将出现在复选框的上方，与方向无关。标签的对齐方式可以通过alignment属性来控制。
属性	label-placement
类型	"end" ｜ "fixed" ｜ "stacked" ｜ "start"
默认	'start'

mode

描述	该模式决定使用哪种平台样式。
属性	mode
类型	"ios" ｜ "md"
默认	undefined

name

描述	控件的名称，它将与表单数据一起提交。
属性	name
类型	字符串
默认	this.inputId

value

描述	复选框的值并不代表它是否被选中，请使用checked属性来判断。 复选框的值类似于<input type="checkbox">的值，它只在复选框参与原生<form>时使用。
属性	value
类型	任何
默认	'on'

事件

名称	描述	冒泡
ionBlur	复选框失去焦点时发出。	true
ionChange	当选中属性由于用户操作（如点击）而发生改变时发出。 如果以编程方式设置checked属性，此事件不会发出。	true
ionFocus	复选框获得焦点时发出。	true

方法

此组件没有公共方法可用。

CSS 阴影部分

名称	描述
container	复选框标记的容器。
label	描述复选框的标签文本。
mark	用于指示选中状态的勾号。

CSS 自定义属性

iOS

名称	描述
--border-color	复选框图标的边框颜色
--border-color-checked	复选框图标选中时的边框颜色
--border-radius	复选框图标的边框半径
--border-style	复选框图标的边框样式
--border-width	复选框图标的边框宽度
--checkbox-background	复选框图标的背景
--checkbox-background-checked	复选框图标选中时的背景
--checkmark-color	复选框勾号选中时的颜色
--checkmark-width	复选框勾号的描边宽度
--size	复选框图标的大小
--transition	复选框图标的过渡

MD

名称	描述
--border-color	复选框图标的边框颜色
--border-color-checked	复选框图标选中时的边框颜色
--border-radius	复选框图标的边框半径
--border-style	复选框图标的边框样式
--border-width	复选框图标的边框宽度
--checkbox-background	复选框图标的背景
--checkbox-background-checked	复选框图标选中时的背景
--checkmark-color	复选框勾号选中时的颜色
--checkmark-width	复选框勾号的描边宽度
--size	复选框图标的大小
--transition	复选框图标的过渡

插槽

名称	描述
``	与复选框关联的标签文本。使用 "labelPlacement" 属性来控制标签相对于复选框的位置。