mirror of
https://github.com/element-plus/element-plus.git
synced 2025-02-17 11:49:41 +08:00
docs(components): [rate] (#11065)
* docs(components): [rate] * Update rate docs with new syntax.
This commit is contained in:
Xc
GitHub
parent
73a9010e37
commit
69443c52a7
@ -77,38 +77,49 @@ Use `css/scss` language to change the global or local color. We set some global
|
||||
### Default Variables
|
||||
|
||||
| Variable | Default Color |
|
||||
| ----------------------------- | ----------------------------- |
|
||||
|-------------------------------|-------------------------------|
|
||||
| --el-rate-void-color | var(--el-border-color-darker) |
|
||||
| --el-rate-fill-color | #f7ba2a |
|
||||
| --el-rate-disabled-void-color | var(--el-fill-color) |
|
||||
| --el-rate-text-color | var(--el-text-color-primary) |
|
||||
|
||||
## Attributes
|
||||
## API
|
||||
|
||||
| Name | Description | Type | Accepted Values | Default |
|
||||
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ----------------------- | ------------------------------------------------------------------ |
|
||||
| model-value / v-model | binding value | number | — | 0 |
|
||||
| max | max rating score | number | — | 5 |
|
||||
| size | size of Rate | string | large / default / small | default |
|
||||
| disabled | whether Rate is read-only | boolean | — | false |
|
||||
| allow-half | whether picking half start is allowed | boolean | — | false |
|
||||
| low-threshold | threshold value between low and medium level. The value itself will be included in low level | number | — | 2 |
|
||||
| high-threshold | threshold value between medium and high level. The value itself will be included in high level | number | — | 4 |
|
||||
| colors | colors for icons. If array, it should have 3 elements, each of which corresponds with a score level, else if object, the key should be threshold value between two levels, and the value should be corresponding color | array/object | — | ['#F7BA2A', '#F7BA2A', '#F7BA2A'] |
|
||||
| void-color | color of unselected icons | string | — | #C6D1DE |
|
||||
| disabled-void-color | color of unselected read-only icons | string | — | #EFF2F7 |
|
||||
| icons | icon components. If array, it should have 3 elements, each of which corresponds with a score level, else if object, the key should be threshold value between two levels, and the value should be corresponding icon component | array/object | — | [StarFilled, StarFilled, StarFilled] |
|
||||
| void-icon | component of unselected icons | string/Component | — | Star |
|
||||
| disabled-void-icon | component of unselected read-only icons | string/Component | — | StarFilled |
|
||||
| show-text | whether to display texts | boolean | — | false |
|
||||
| show-score | whether to display current score. show-score and show-text cannot be true at the same time | boolean | — | false |
|
||||
| text-color | color of texts | string | — | #1F2D3D |
|
||||
| texts | text array | array | — | ['Extremely bad', 'Disappointed', 'Fair', 'Satisfied', 'Surprise'] |
|
||||
| score-template | score template | string | — | {value} |
|
||||
| clearable | whether value can be reset to `0` | boolean | — | false |
|
||||
### Attributes
|
||||
|
||||
## Events
|
||||
| Name | Description | Type | Default |
|
||||
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------------|
|
||||
| model-value / v-model | binding value | ^[number] | 0 |
|
||||
| max | max rating score | ^[number] | 5 |
|
||||
| size | size of Rate | ^[enum]`'large' \| 'default' \| 'small'` | — |
|
||||
| disabled | whether Rate is read-only | ^[boolean] | false |
|
||||
| allow-half | whether picking half start is allowed | ^[boolean] | false |
|
||||
| low-threshold | threshold value between low and medium level. The value itself will be included in low level | ^[number] | 2 |
|
||||
| high-threshold | threshold value between medium and high level. The value itself will be included in high level | ^[number] | 4 |
|
||||
| colors | colors for icons. If array, it should have 3 elements, each of which corresponds with a score level, else if object, the key should be threshold value between two levels, and the value should be corresponding color | ^[object]`string[] \| Record<number, string>` | ['#F7BA2A', '#F7BA2A', '#F7BA2A'] |
|
||||
| void-color | color of unselected icons | ^[string] | #C6D1DE |
|
||||
| disabled-void-color | color of unselected read-only icons | ^[string] | #EFF2F7 |
|
||||
| icons | icon components. If array, it should have 3 elements, each of which corresponds with a score level, else if object, the key should be threshold value between two levels, and the value should be corresponding icon component | ^[object]`string[] \| Component[] \| Record<number, string \| Component>` | [StarFilled, StarFilled, StarFilled] |
|
||||
| void-icon | component of unselected icons | ^[string] / ^[Component] | Star |
|
||||
| disabled-void-icon | component of unselected read-only icons | ^[string] / ^[Component] | StarFilled |
|
||||
| show-text | whether to display texts | ^[boolean] | false |
|
||||
| show-score | whether to display current score. show-score and show-text cannot be true at the same time | ^[boolean] | false |
|
||||
| text-color | color of texts | ^[string] | #1F2D3D |
|
||||
| texts | text array | ^[array]`string[]` | ['Extremely bad', 'Disappointed', 'Fair', 'Satisfied', 'Surprise'] |
|
||||
| score-template | score template | ^[string] | {value} |
|
||||
| clearable | whether value can be reset to `0` | ^[boolean] | false |
|
||||
| id | native `id` attribute | ^[string] | — |
|
||||
| label<A11yTag /> | same as `aria-label` in Rate | ^[string] | — |
|
||||
|
||||
| Name | Description | Parameters |
|
||||
| ------ | ----------------------------------- | -------------------- |
|
||||
| change | Triggers when rate value is changed | value after changing |
|
||||
### Events
|
||||
|
||||
| Name | Description | Type |
|
||||
|--------|-------------------------------------|--------------------------------------|
|
||||
| change | Triggers when rate value is changed | ^[Function]`(value: number) => void` |
|
||||
|
||||
### Exposes
|
||||
|
||||
| Name | Description | Type |
|
||||
|-------------------|---------------------|--------------------------------------|
|
||||
| setCurrentValue | set current value | ^[Function]`(value: number) => void` |
|
||||
| resetCurrentValue | reset current value | ^[Function]`() => void` |
|
||||
|
||||
@ -5,76 +5,118 @@ import {
|
||||
definePropType,
|
||||
iconPropType,
|
||||
isNumber,
|
||||
isValidComponentSize,
|
||||
mutable,
|
||||
} from '@element-plus/utils'
|
||||
import type { ComponentSize } from '@element-plus/constants'
|
||||
import type { Component, ExtractPropTypes, PropType } from 'vue'
|
||||
import { useSizeProp } from '@element-plus/hooks'
|
||||
import type { Component, ExtractPropTypes } from 'vue'
|
||||
import type Rate from './rate.vue'
|
||||
|
||||
export const rateProps = buildProps({
|
||||
/**
|
||||
* @description binding value
|
||||
*/
|
||||
modelValue: {
|
||||
type: Number,
|
||||
default: 0,
|
||||
},
|
||||
/**
|
||||
* @description native `id` attribute
|
||||
*/
|
||||
id: {
|
||||
type: String,
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description threshold value between low and medium level. The value itself will be included in low level
|
||||
*/
|
||||
lowThreshold: {
|
||||
type: Number,
|
||||
default: 2,
|
||||
},
|
||||
/**
|
||||
* @description threshold value between medium and high level. The value itself will be included in high level
|
||||
*/
|
||||
highThreshold: {
|
||||
type: Number,
|
||||
default: 4,
|
||||
},
|
||||
/**
|
||||
* @description max rating score
|
||||
*/
|
||||
max: {
|
||||
type: Number,
|
||||
default: 5,
|
||||
},
|
||||
/**
|
||||
* @description colors for icons. If array, it should have 3 elements, each of which corresponds with a score level, else if object, the key should be threshold value between two levels, and the value should be corresponding color
|
||||
*/
|
||||
colors: {
|
||||
type: definePropType<string[] | Record<number, string>>([Array, Object]),
|
||||
default: () => mutable(['', '', ''] as const),
|
||||
},
|
||||
/**
|
||||
* @description color of unselected icons
|
||||
*/
|
||||
voidColor: {
|
||||
type: String,
|
||||
default: '',
|
||||
},
|
||||
/**
|
||||
* @description color of unselected read-only icons
|
||||
*/
|
||||
disabledVoidColor: {
|
||||
type: String,
|
||||
default: '',
|
||||
},
|
||||
/**
|
||||
* @description icon components. If array, it should have 3 elements, each of which corresponds with a score level, else if object, the key should be threshold value between two levels, and the value should be corresponding icon component
|
||||
*/
|
||||
icons: {
|
||||
type: definePropType<
|
||||
Array<string | Component> | Record<number, string | Component>
|
||||
>([Array, Object]),
|
||||
default: () => [StarFilled, StarFilled, StarFilled],
|
||||
},
|
||||
/**
|
||||
* @description component of unselected icons
|
||||
*/
|
||||
voidIcon: {
|
||||
type: iconPropType,
|
||||
default: () => Star,
|
||||
},
|
||||
/**
|
||||
* @description component of unselected read-only icons
|
||||
*/
|
||||
disabledVoidIcon: {
|
||||
type: iconPropType,
|
||||
default: () => StarFilled,
|
||||
},
|
||||
disabled: {
|
||||
type: Boolean,
|
||||
},
|
||||
allowHalf: {
|
||||
type: Boolean,
|
||||
},
|
||||
showText: {
|
||||
type: Boolean,
|
||||
},
|
||||
showScore: {
|
||||
type: Boolean,
|
||||
},
|
||||
/**
|
||||
* @description whether Rate is read-only
|
||||
*/
|
||||
disabled: Boolean,
|
||||
/**
|
||||
* @description whether picking half start is allowed
|
||||
*/
|
||||
allowHalf: Boolean,
|
||||
/**
|
||||
* @description whether to display texts
|
||||
*/
|
||||
showText: Boolean,
|
||||
/**
|
||||
* @description whether to display current score. show-score and show-text cannot be true at the same time
|
||||
*/
|
||||
showScore: Boolean,
|
||||
/**
|
||||
* @description color of texts
|
||||
*/
|
||||
textColor: {
|
||||
type: String,
|
||||
default: '',
|
||||
},
|
||||
/**
|
||||
* @description text array
|
||||
*/
|
||||
texts: {
|
||||
type: definePropType<string[]>(Array),
|
||||
default: () =>
|
||||
@ -86,18 +128,27 @@ export const rateProps = buildProps({
|
||||
'Surprise',
|
||||
] as const),
|
||||
},
|
||||
/**
|
||||
* @description score template
|
||||
*/
|
||||
scoreTemplate: {
|
||||
type: String,
|
||||
default: '{value}',
|
||||
},
|
||||
size: {
|
||||
type: String as PropType<ComponentSize>,
|
||||
validator: isValidComponentSize,
|
||||
},
|
||||
/**
|
||||
* @description size of Rate
|
||||
*/
|
||||
size: useSizeProp,
|
||||
/**
|
||||
* @description same as `aria-label` in Rate
|
||||
*/
|
||||
label: {
|
||||
type: String,
|
||||
default: undefined,
|
||||
},
|
||||
/**
|
||||
* @description whether value can be reset to `0`
|
||||
*/
|
||||
clearable: {
|
||||
type: Boolean,
|
||||
default: false,
|
||||
|
||||
@ -248,11 +248,11 @@ function handleKey(e: KeyboardEvent) {
|
||||
return _currentValue
|
||||
}
|
||||
|
||||
function setCurrentValue(value: number, event: MouseEvent) {
|
||||
function setCurrentValue(value: number, event?: MouseEvent) {
|
||||
if (rateDisabled.value) {
|
||||
return
|
||||
}
|
||||
if (props.allowHalf) {
|
||||
if (props.allowHalf && event) {
|
||||
// TODO: use cache via computed https://github.com/element-plus/element-plus/pull/5456#discussion_r786472092
|
||||
let target = event.target as HTMLElement
|
||||
if (hasClass(target, ns.e('item'))) {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user