mirror of
https://github.com/element-plus/element-plus.git
synced 2024-11-21 01:02:59 +08:00
docs(components): [checkbox] (#10888)
* docs(components): [checkbox] * Adjust API style * classname
This commit is contained in:
Xc
GitHub
parent
d3518f8694
commit
15d146949f
@ -75,73 +75,83 @@ checkbox/with-border
|
||||
|
||||
:::
|
||||
|
||||
## Checkbox Attributes
|
||||
## Checkbox API
|
||||
|
||||
| Name | Description | Type | Accepted Values | Default |
|
||||
| --------------------- | --------------------------------------------------------- | ---------------------------------- | ---------------------- | ------- |
|
||||
| model-value / v-model | binding value | string / number / boolean | — | — |
|
||||
| label | value of the Checkbox when used inside a `checkbox-group` | string / number / boolean / object | — | — |
|
||||
| true-label | value of the Checkbox if it's checked | string / number | — | — |
|
||||
| false-label | value of the Checkbox if it's not checked | string / number | — | — |
|
||||
| disabled | whether the Checkbox is disabled | boolean | — | false |
|
||||
| border | whether to add a border around Checkbox | boolean | — | false |
|
||||
| size | size of the Checkbox | string | large / default /small | — |
|
||||
| name | native 'name' attribute | string | — | — |
|
||||
| checked | if the Checkbox is checked | boolean | — | false |
|
||||
| indeterminate | same as `indeterminate` in native checkbox | boolean | — | false |
|
||||
| validate-event | whether to trigger form validation | boolean | - | true |
|
||||
### Checkbox Attributes
|
||||
|
||||
## Checkbox Events
|
||||
| Name | Description | Type | Default |
|
||||
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------- |
|
||||
| model-value / v-model | binding value | ^[string] / ^[number] / ^[boolean] | — |
|
||||
| label | value of the Checkbox when used inside a `checkbox-group` | ^[string] / ^[number] / ^[boolean] / ^[object] | — |
|
||||
| true-label | value of the Checkbox if it's checked | ^[string] / ^[number] | — |
|
||||
| false-label | value of the Checkbox if it's not checked | ^[string] / ^[number] | — |
|
||||
| disabled | whether the Checkbox is disabled | ^[boolean] | false |
|
||||
| border | whether to add a border around Checkbox | ^[boolean] | false |
|
||||
| size | size of the Checkbox | ^[enum]`'large' \| 'default' \| 'small'` | — |
|
||||
| name | native 'name' attribute | ^[string] | — |
|
||||
| checked | if the Checkbox is checked | ^[boolean] | false |
|
||||
| indeterminate | Set indeterminate state, only responsible for style control | ^[boolean] | false |
|
||||
| validate-event | whether to trigger form validation | ^[boolean] | true |
|
||||
| tabindex | input tabindex | ^[string] / ^[number] | — |
|
||||
| id | input id | ^[string] | — |
|
||||
| controls <A11yTag /> | same as [aria-controls](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls), takes effect when `indeterminate` is `true` | ^[boolean] | — |
|
||||
|
||||
| Name | Description | Parameters |
|
||||
| ------ | --------------------------------------- | ----------------- |
|
||||
| change | triggers when the binding value changes | the updated value |
|
||||
### Checkbox Events
|
||||
|
||||
## Checkbox Slots
|
||||
| Name | Description | Type |
|
||||
| ------ | --------------------------------------- | --------------------------------------------------------- |
|
||||
| change | triggers when the binding value changes | ^[Function]`(value: string \| number \| boolean) => void` |
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ------------------------- |
|
||||
| — | customize default content |
|
||||
### Checkbox Slots
|
||||
|
||||
## Checkbox-group Attributes
|
||||
| Name | Description |
|
||||
| ------- | ------------------------- |
|
||||
| default | customize default content |
|
||||
|
||||
| Name | Description | Type | Accepted Values | Default |
|
||||
| --------------------- | ------------------------------------------------- | ------- | ---------------------- | ------- |
|
||||
| model-value / v-model | binding value | array | — | [] |
|
||||
| size | size of checkbox | string | large / default /small | — |
|
||||
| disabled | whether the nesting checkboxes are disabled | boolean | — | false |
|
||||
| min | minimum number of checkbox checked | number | — | — |
|
||||
| max | maximum number of checkbox checked | number | — | — |
|
||||
| label | label for screen reader | string | — | — |
|
||||
| text-color | font color when button is active | string | — | #ffffff |
|
||||
| fill | border and background color when button is active | string | — | #409EFF |
|
||||
| validate-event | whether to trigger form validation | boolean | - | true |
|
||||
## CheckboxGroup API
|
||||
|
||||
## Checkbox-group Events
|
||||
### CheckboxGroup Attributes
|
||||
|
||||
| Name | Description | Parameters |
|
||||
| ------ | --------------------------------------- | ----------------- |
|
||||
| change | triggers when the binding value changes | the updated value |
|
||||
| Name | Description | Type | Default |
|
||||
| --------------------- | ------------------------------------------------- | ---------------------------------------- | ------- |
|
||||
| model-value / v-model | binding value | ^[object]`string[] \| number[]` | [] |
|
||||
| size | size of checkbox | ^[enum]`'large' \| 'default' \| 'small'` | — |
|
||||
| disabled | whether the nesting checkboxes are disabled | ^[boolean] | false |
|
||||
| min | minimum number of checkbox checked | ^[number] | — |
|
||||
| max | maximum number of checkbox checked | ^[number] | — |
|
||||
| label | label for screen reader | ^[string] | — |
|
||||
| text-color | font color when button is active | ^[string] | #ffffff |
|
||||
| fill | border and background color when button is active | ^[string] | #409EFF |
|
||||
| tag | element tag of the checkbox group | ^[string] | div |
|
||||
| validate-event | whether to trigger form validation | ^[boolean] | true |
|
||||
|
||||
## Checkbox-group Slots
|
||||
### CheckboxGroup Events
|
||||
|
||||
| Name | Description | Subtags |
|
||||
| ---- | ------------------------- | -------------------------- |
|
||||
| - | customize default content | Checkbox / Checkbox-button |
|
||||
| Name | Description | Type |
|
||||
| ------ | --------------------------------------- | -------------------------------------------------- |
|
||||
| change | triggers when the binding value changes | ^[Function]`(value: string[] \| number[]) => void` |
|
||||
|
||||
## Checkbox-button Attributes
|
||||
### CheckboxGroup Slots
|
||||
|
||||
| Name | Description | Type | Accepted Values | Default |
|
||||
| ----------- | --------------------------------------------------------- | ---------------------------------- | --------------- | ------- |
|
||||
| label | value of the checkbox when used inside a `checkbox-group` | string / number / boolean / object | — | — |
|
||||
| true-label | value of the checkbox if it's checked | string / number | — | — |
|
||||
| false-label | value of the checkbox if it's not checked | string / number | — | — |
|
||||
| disabled | whether the checkbox is disabled | boolean | — | false |
|
||||
| name | native 'name' attribute | string | — | — |
|
||||
| checked | if the checkbox is checked | boolean | — | false |
|
||||
| Name | Description | Subtags |
|
||||
| ------- | ------------------------- | -------------------------- |
|
||||
| default | customize default content | Checkbox / Checkbox-button |
|
||||
|
||||
## Checkbox-button Slots
|
||||
## CheckboxButton API
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ------------------------- |
|
||||
| — | customize default content |
|
||||
### CheckboxButton Attributes
|
||||
|
||||
| Name | Description | Type | Default |
|
||||
| ----------- | --------------------------------------------------------- | ---------------------------------------------- | ------- |
|
||||
| label | value of the checkbox when used inside a `checkbox-group` | ^[string] / ^[number] / ^[boolean] / ^[object] | — |
|
||||
| true-label | value of the checkbox if it's checked | ^[string] / ^[number] | — |
|
||||
| false-label | value of the checkbox if it's not checked | ^[string] / ^[number] | — |
|
||||
| disabled | whether the checkbox is disabled | ^[boolean] | false |
|
||||
| name | native 'name' attribute | ^[string] | — |
|
||||
| checked | if the checkbox is checked | ^[boolean] | false |
|
||||
|
||||
### CheckboxButton Slots
|
||||
|
||||
| Name | Description |
|
||||
| ------- | ------------------------- |
|
||||
| default | customize default content |
|
||||
|
||||
@ -1,13 +1,5 @@
|
||||
<template>
|
||||
<label
|
||||
:class="[
|
||||
ns.b('button'),
|
||||
ns.bm('button', checkboxButtonSize),
|
||||
ns.is('disabled', isDisabled),
|
||||
ns.is('checked', isChecked),
|
||||
ns.is('focus', isFocused),
|
||||
]"
|
||||
>
|
||||
<label :class="lableKls">
|
||||
<input
|
||||
v-if="trueLabel || falseLabel"
|
||||
v-model="model"
|
||||
@ -83,4 +75,14 @@ const activeStyle = computed<CSSProperties>(() => {
|
||||
boxShadow: fillValue ? `-1px 0 0 0 ${fillValue}` : undefined,
|
||||
}
|
||||
})
|
||||
|
||||
const lableKls = computed(() => {
|
||||
return [
|
||||
ns.b('button'),
|
||||
ns.bm('button', checkboxButtonSize.value),
|
||||
ns.is('disabled', isDisabled.value),
|
||||
ns.is('checked', isChecked.value),
|
||||
ns.is('focus', isFocused.value),
|
||||
]
|
||||
})
|
||||
</script>
|
||||
|
||||
@ -6,22 +6,54 @@ import type { ExtractPropTypes } from 'vue'
|
||||
import type checkboxGroup from './checkbox-group.vue'
|
||||
import type { CheckboxValueType } from './checkbox'
|
||||
|
||||
export type CheckboxGroupValueType = Exclude<CheckboxValueType, boolean>[]
|
||||
|
||||
export const checkboxGroupProps = buildProps({
|
||||
/**
|
||||
* @description binding value
|
||||
*/
|
||||
modelValue: {
|
||||
type: definePropType<Array<string | number>>(Array),
|
||||
type: definePropType<CheckboxGroupValueType>(Array),
|
||||
default: () => [],
|
||||
},
|
||||
/**
|
||||
* @description whether the nesting checkboxes are disabled
|
||||
*/
|
||||
disabled: Boolean,
|
||||
/**
|
||||
* @description minimum number of checkbox checked
|
||||
*/
|
||||
min: Number,
|
||||
/**
|
||||
* @description maximum number of checkbox checked
|
||||
*/
|
||||
max: Number,
|
||||
/**
|
||||
* @description size of checkbox
|
||||
*/
|
||||
size: useSizeProp,
|
||||
/**
|
||||
* @description label for screen reader
|
||||
*/
|
||||
label: String,
|
||||
/**
|
||||
* @description border and background color when button is active
|
||||
*/
|
||||
fill: String,
|
||||
/**
|
||||
* @description font color when button is active
|
||||
*/
|
||||
textColor: String,
|
||||
/**
|
||||
* @description element tag of the checkbox group
|
||||
*/
|
||||
tag: {
|
||||
type: String,
|
||||
default: 'div',
|
||||
},
|
||||
/**
|
||||
* @description whether to trigger form validation
|
||||
*/
|
||||
validateEvent: {
|
||||
type: Boolean,
|
||||
default: true,
|
||||
@ -29,7 +61,7 @@ export const checkboxGroupProps = buildProps({
|
||||
} as const)
|
||||
|
||||
export const checkboxGroupEmits = {
|
||||
[UPDATE_MODEL_EVENT]: (val: CheckboxValueType[]) => isArray(val),
|
||||
[UPDATE_MODEL_EVENT]: (val: CheckboxGroupValueType) => isArray(val),
|
||||
change: (val: CheckboxValueType[]) => isArray(val),
|
||||
}
|
||||
|
||||
|
||||
@ -23,8 +23,7 @@ import {
|
||||
} from '@element-plus/hooks'
|
||||
import { checkboxGroupContextKey } from '@element-plus/tokens'
|
||||
import { checkboxGroupEmits, checkboxGroupProps } from './checkbox-group'
|
||||
|
||||
import type { CheckboxValueType } from './checkbox'
|
||||
import type { CheckboxGroupValueType } from './checkbox-group'
|
||||
|
||||
defineOptions({
|
||||
name: 'ElCheckboxGroup',
|
||||
@ -39,7 +38,7 @@ const { inputId: groupId, isLabeledByFormItem } = useFormItemInputId(props, {
|
||||
formItemContext: formItem,
|
||||
})
|
||||
|
||||
const changeEvent = async (value: CheckboxValueType[]) => {
|
||||
const changeEvent = async (value: CheckboxGroupValueType) => {
|
||||
emit(UPDATE_MODEL_EVENT, value)
|
||||
await nextTick()
|
||||
emit('change', value)
|
||||
@ -49,7 +48,7 @@ const modelValue = computed({
|
||||
get() {
|
||||
return props.modelValue
|
||||
},
|
||||
set(val: CheckboxValueType[]) {
|
||||
set(val: CheckboxGroupValueType) {
|
||||
changeEvent(val)
|
||||
},
|
||||
})
|
||||
|
||||
@ -8,39 +8,81 @@ import type Checkbox from './checkbox.vue'
|
||||
export type CheckboxValueType = string | number | boolean
|
||||
|
||||
export const checkboxProps = {
|
||||
/**
|
||||
* @description binding value
|
||||
*/
|
||||
modelValue: {
|
||||
type: [Number, String, Boolean],
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description value of the Checkbox when used inside a `checkbox-group`
|
||||
*/
|
||||
label: {
|
||||
type: [String, Boolean, Number, Object],
|
||||
},
|
||||
/**
|
||||
* @description Set indeterminate state, only responsible for style control
|
||||
*/
|
||||
indeterminate: Boolean,
|
||||
/**
|
||||
* @description whether the Checkbox is disabled
|
||||
*/
|
||||
disabled: Boolean,
|
||||
/**
|
||||
* @description if the Checkbox is checked
|
||||
*/
|
||||
checked: Boolean,
|
||||
/**
|
||||
* @description native 'name' attribute
|
||||
*/
|
||||
name: {
|
||||
type: String,
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description value of the Checkbox if it's checked
|
||||
*/
|
||||
trueLabel: {
|
||||
type: [String, Number],
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description value of the Checkbox if it's not checked
|
||||
*/
|
||||
falseLabel: {
|
||||
type: [String, Number],
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description input id
|
||||
*/
|
||||
id: {
|
||||
type: String,
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description same as [aria-controls](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls), takes effect when `indeterminate` is `true`
|
||||
*/
|
||||
controls: {
|
||||
type: String,
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description whether to add a border around Checkbox
|
||||
*/
|
||||
border: Boolean,
|
||||
/**
|
||||
* @description size of the Checkbox
|
||||
*/
|
||||
size: useSizeProp,
|
||||
/**
|
||||
* @description input tabindex
|
||||
*/
|
||||
tabindex: [String, Number],
|
||||
/**
|
||||
* @description whether to trigger form validation
|
||||
*/
|
||||
validateEvent: {
|
||||
type: Boolean,
|
||||
default: true,
|
||||
|
||||
@ -1,24 +1,12 @@
|
||||
<template>
|
||||
<component
|
||||
:is="!hasOwnLabel && isLabeledByFormItem ? 'span' : 'label'"
|
||||
:class="[
|
||||
ns.b(),
|
||||
ns.m(checkboxSize),
|
||||
ns.is('disabled', isDisabled),
|
||||
ns.is('bordered', border),
|
||||
ns.is('checked', isChecked),
|
||||
]"
|
||||
:class="compKls"
|
||||
:aria-controls="indeterminate ? controls : null"
|
||||
@click="onClickRoot"
|
||||
>
|
||||
<span
|
||||
:class="[
|
||||
ns.e('input'),
|
||||
ns.is('disabled', isDisabled),
|
||||
ns.is('checked', isChecked),
|
||||
ns.is('indeterminate', indeterminate),
|
||||
ns.is('focus', isFocused),
|
||||
]"
|
||||
:class="spanKls"
|
||||
:tabindex="indeterminate ? 0 : undefined"
|
||||
:role="indeterminate ? 'checkbox' : undefined"
|
||||
:aria-checked="indeterminate ? 'mixed' : undefined"
|
||||
@ -64,7 +52,7 @@
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
import { useSlots } from 'vue'
|
||||
import { computed, useSlots } from 'vue'
|
||||
import { useNamespace } from '@element-plus/hooks'
|
||||
import { checkboxEmits, checkboxProps } from './checkbox'
|
||||
import { useCheckbox } from './composables'
|
||||
@ -91,4 +79,24 @@ const {
|
||||
} = useCheckbox(props, slots)
|
||||
|
||||
const ns = useNamespace('checkbox')
|
||||
|
||||
const compKls = computed(() => {
|
||||
return [
|
||||
ns.b(),
|
||||
ns.m(checkboxSize.value),
|
||||
ns.is('disabled', isDisabled.value),
|
||||
ns.is('bordered', props.border),
|
||||
ns.is('checked', isChecked.value),
|
||||
]
|
||||
})
|
||||
|
||||
const spanKls = computed(() => {
|
||||
return [
|
||||
ns.e('input'),
|
||||
ns.is('disabled', isDisabled.value),
|
||||
ns.is('checked', isChecked.value),
|
||||
ns.is('indeterminate', props.indeterminate),
|
||||
ns.is('focus', isFocused.value),
|
||||
]
|
||||
})
|
||||
</script>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user