复选框 Checkbox

这是多选题。

基础使用

复选框 Checkbox，传入 modelValue 进入受控模式。不传或者为 undefined 则为非受控模式，此时可以传入 defaultValue 属性作为默认值。

复选框 Checkbox 有两种样式变体，普通模式（normal，默认）和经典模式（retro）。经典模式的样式为致敬早期的游戏 UI 而设置。

<template>
	<px-space>
		<px-checkbox v-model="checked">Basic Checkbox</px-checkbox>
		<px-checkbox :default-value="true">Uncontrolled</px-checkbox>
		<px-checkbox label="Set Label By Prop"></px-checkbox>
		<px-checkbox variant="retro">Retro Style</px-checkbox>
		<px-checkbox variant="retro" :default-value="true">Retro Style Checked</px-checkbox>
	</px-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const checked = ref(false)
</script>

禁用、只读状态

复选框 Checkbox，readonly 设置只读，disabled 设置禁用。此时内部 <input> 都会被设置 disabled，它们之间几乎只有样式不一样。

<template>
	<px-space direction="vertical">
		<px-space>
			<px-checkbox disabled :default-value="true">Checked</px-checkbox>
			<px-checkbox disabled>Unchecked</px-checkbox>
			<px-checkbox readonly :default-value="true">Checked Readonly</px-checkbox>
			<px-checkbox readonly>Unchecked Readonly</px-checkbox>
		</px-space>
		<px-space>
			<px-checkbox variant="retro" disabled :default-value="true">Checked</px-checkbox>
			<px-checkbox variant="retro" disabled>Unchecked</px-checkbox>
			<px-checkbox variant="retro" readonly :default-value="true">Checked Readonly</px-checkbox>
			<px-checkbox variant="retro" readonly>Unchecked Readonly</px-checkbox>
		</px-space>
	</px-space>
</template>

复选组

可以通过组合 CheckboxGroup 和 Checkbox 来形成一个复选组。

CheckboxGroup 的值为选中的 Checkbox 复选框组件的 value 组成的数组。

同样地，CheckboxGroup 传入 modelValue 进入受控模式。不传或者为 undefined 则为非受控模式，此时可以传入 defaultValue 属性作为默认值。

<template>
	<px-space direction="vertical">
		<px-checkbox-group v-model="group">
			<px-checkbox value="Abigail">Abigail</px-checkbox>
			<px-checkbox value="Harvey">Harvey</px-checkbox>
			<px-checkbox value="Leah">Leah</px-checkbox>
			<px-checkbox value="Maru">Maru</px-checkbox>
		</px-checkbox-group>
		<px-checkbox-group :default-value="['Elliott']">
			<px-checkbox value="Elliott">Elliott</px-checkbox>
			<px-checkbox value="Haley">Haley</px-checkbox>
			<px-checkbox value="Penny">Penny</px-checkbox>
			<px-checkbox value="Sebastian">Sebastian</px-checkbox>
		</px-checkbox-group>
		<h4>Retro Style</h4>
		<px-checkbox-group :default-value="['Dwarf']" variant="retro">
			<px-checkbox value="Dwarf">Dwarf</px-checkbox>
			<px-checkbox value="Krobus">Krobus</px-checkbox>
		</px-checkbox-group>
		<h4>Readonly</h4>
		<px-checkbox-group :default-value="['Sam']" readonly>
			<px-checkbox value="Sam">Sam</px-checkbox>
			<px-checkbox value="Shane">Shane</px-checkbox>
		</px-checkbox-group>
		<h4>Disabled</h4>
		<px-checkbox-group :default-value="['Alex']" disabled>
			<px-checkbox value="Alex">Alex</px-checkbox>
			<px-checkbox value="Clint">Clint</px-checkbox>
		</px-checkbox-group>
	</px-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const group = ref<string[]>([])
</script>

半选中

Checkbox 的 indeterminate 为 true 可以把复选框置为半选中状态，这个属性仅控制样式，和当前复选框的值无关。

<template>
	<px-switch v-model="retro" active-label="Retro" inactive-label="Normal"></px-switch>
	<br />
	<br />
	<px-checkbox
		:variant="retro ? 'retro' : 'normal'"
		v-model="all"
		@change="selectAllChangeHandler"
		:indeterminate="group.length > 0 && group.length < options.length"
		>Select All</px-checkbox
	>
	<br />
	<br />
	<px-checkbox-group
		v-model="group"
		@change="groupChangeHandler"
		:variant="retro ? 'retro' : 'normal'"
	>
		<px-checkbox v-for="option in options" :key="option" :value="option">
			{{ option }}
		</px-checkbox>
	</px-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const group = ref<string[]>([])
const all = ref(false)

const options = ['Blue Jazz', 'Carrot', 'Coffee Bean', 'Parsnip']

const selectAllChangeHandler = (value: boolean) => {
	if (value) {
		group.value = [...options]
	} else {
		group.value = []
	}
}

const groupChangeHandler = (value: string[]) => {
	if (value.length === options.length) {
		all.value = true
	} else {
		all.value = false
	}
}

const retro = ref(false)
</script>

垂直排列

CheckboxGroup 的 direction 属性用于设置子复选框的排列方向。

<template>
	<px-space>
		<px-switch
			v-model="vertical"
			active-label="Vertical"
			inactive-label="Horizontal"
		></px-switch>
		<px-switch v-model="retro" active-label="Retro" inactive-label="Normal"></px-switch>
	</px-space>
	<br />
	<br />
	<px-checkbox-group
		:direction="vertical ? 'vertical' : 'horizontal'"
		:variant="retro ? 'retro' : 'normal'"
	>
		<px-checkbox value="Anchovy">Anchovy</px-checkbox>
		<px-checkbox value="Tuna">Tuna</px-checkbox>
		<px-checkbox value="Sardine">Sardine</px-checkbox>
		<px-checkbox value="Bream">Bream</px-checkbox>
	</px-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const vertical = ref(false)
const retro = ref(false)
</script>

复选框尺寸

Checkbox 和 CheckboxGroup 的 size 属性都可以用于设置复选框的尺寸。

<template>
	<px-space direction="vertical">
		<h4>Single Checkbox</h4>
		<px-space>
			<px-checkbox size="small">Small</px-checkbox>
			<px-checkbox>Medium</px-checkbox>
			<px-checkbox size="large">Large</px-checkbox>
		</px-space>
		<px-space>
			<px-checkbox variant="retro" size="small">Small & Retro</px-checkbox>
			<px-checkbox variant="retro">Medium & Retro</px-checkbox>
			<px-checkbox variant="retro" size="large">Large & Retro</px-checkbox>
		</px-space>
		<h4>Group</h4>
		<px-checkbox-group :options="options" size="small"></px-checkbox-group>
		<px-checkbox-group :options="options"></px-checkbox-group>
		<px-checkbox-group :options="options" size="large"></px-checkbox-group>
	</px-space>
</template>

<script setup lang="ts">
const options = ['A', 'B', 'C', 'D']
</script>

选项属性

CheckboxGroup 的 options 属性用于直接传入选项，可以用于简单复选组的快速创建。

<template>
	<px-switch v-model="retro" active-label="Retro" inactive-label="Normal"></px-switch>
	<br />
	<br />
	<px-checkbox-group :options="options" :variant="retro ? 'retro' : 'normal'">
	</px-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const options = [
	'Lava Eel',
	'Ice Pip',
	{
		value: 'Midnight Carp',
		label: 'Midnight Carp',
		disabled: true
	},
	'Slimejack'
]

const retro = ref(false)
</script>

API

CheckboxProps

属性	类型	可选	默认值	描述	版本
modelValue	`boolean \| null`	是		复选框组件 Checkbox 的值（受控模式）。	0.0.3
defaultValue	`boolean \| null`	是		复选框组件 Checkbox 的默认值（非受控模式）。	0.0.3
indeterminate	`boolean`	是	`false`	半选中状态。	0.0.3
disabled	`boolean`	是	`false`	禁用状态。	0.0.3
readonly	`boolean`	是	`false`	只读状态。	0.0.3
variant	`'normal' \| 'retro'`	是	`'normal'`	复选框的样式变体。	0.0.3
label	`string`	是		复选框的文本。	0.0.3
value	`any`	是		复选框的原生 `value` 属性。	0.0.3
size	`'medium' \| 'large' \| 'small'`	是	`'medium'`	复选框的大小。	0.0.3

CheckboxEvents

事件	参数	描述	版本
update:modelValue	`value: boolean`	更新 `modelValue` 的回调。	0.0.3
input	`value: boolean, event: InputEvent`	选中/取消选择复选框的回调。	0.0.3
change	`value: boolean, event: Event`	复选框选中状态改变的回调。	0.0.3
focus	`event: FocusEvent`	复选框聚焦的回调。	0.0.3
blur	`event: FocusEvent`	复选框失去焦点的回调。	0.0.3

CheckboxSlots

插槽	参数	描述	版本
default		复选框的文本。	0.0.3

CheckboxGroupProps

属性	类型	可选	默认值	描述	版本
modelValue	`any[] \| null`	是		复选组组件 CheckboxGroup 的值（受控模式）。	0.0.3
defaultValue	`any[] \| null`	是		复选组组件 CheckboxGroup 的默认值（非受控模式）。	0.0.3
disabled	`boolean`	是	`false`	禁用状态。	0.0.3
readonly	`boolean`	是	`false`	只读状态。	0.0.3
variant	`'normal' \| 'retro'`	是		后代的单选框组件的样式变体，如果设置，优先于后代的单选框组件自身的 `variant`。	0.0.3
direction	`'horizontal' \| 'vertical'`	是	`'horizontal'`	复选框子组件排列方向。	0.0.3
options	`(CheckboxGroupOption \| string)[]`	是		复选组选项。	0.0.3
size	`'medium' \| 'large' \| 'small'`	是	`'medium'`	后代的复选框组件的尺寸大小，如果设置，优先于后代的复选框组件自身的 `size`。	0.0.3

CheckboxGroupEvents

事件	参数	描述	版本
update:modelValue	`value: any[]`	更新 `modelValue` 的回调。	0.0.3
change	`value: any[]`	复选组选中内容改变的回调。	0.0.3

CheckboxGroupSlots

插槽	参数	描述	版本
default		复选框子组件。	0.0.3

CheckboxGroupOption

export interface Option<T = any> {
	value: T
	label: string
}

export interface CheckboxGroupOption<T = any> extends Option<T> {
	disabled?: boolean
	key?: string | number | symbol
}

复选框 Checkbox ​

基础使用 ​

禁用、只读状态 ​

复选组 ​

Retro Style

Readonly

Disabled

半选中 ​

垂直排列 ​

复选框尺寸 ​

Single Checkbox

Group

选项属性 ​

API ​

CheckboxProps ​

CheckboxEvents ​

CheckboxSlots ​

CheckboxGroupProps ​

CheckboxGroupEvents ​

CheckboxGroupSlots ​

CheckboxGroupOption ​