From d1e615eca7f23989fc26a7cd0695fdca05cd72f2 Mon Sep 17 00:00:00 2001
From: Xc <124118265@qq.com>
Date: Wed, 9 Nov 2022 23:57:22 +0800
Subject: [PATCH] docs(components): [input] (#10513)
* docs(components): [input]
* Update input doc
* Add description for input props
* Add exposes attribute to doc
* Add a11y tag
* docs(components): [input]
---
docs/en-US/component/input.md | 106 +++++++++++++------------
packages/components/input/src/input.ts | 69 ++++++++++++++++
2 files changed, 126 insertions(+), 49 deletions(-)
diff --git a/docs/en-US/component/input.md b/docs/en-US/component/input.md
index 110383c906..3d70497e27 100644
--- a/docs/en-US/component/input.md
+++ b/docs/en-US/component/input.md
@@ -115,41 +115,53 @@ input/length-limiting
:::
-## Input Attributes
+## API
-| Name | Description | Type | Accepted Values | Default |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| type | type of input | string | text, textarea and other [native input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types) | text |
-| modelValue / v-model | binding value | string / number | — | — |
-| maxlength | the max length | string / number | — | — |
-| minlength | same as `minlength` in native input | number | — | — |
-| show-word-limit | whether show word count, only works when `type` is 'text' or 'textarea' | boolean | — | false |
-| placeholder | placeholder of Input | string | — | — |
-| clearable | whether to show clear button | boolean | — | false |
-| formatter | specifies the format of the value presented input.(only works when `type` is 'text') | `(value: string \| number) => string` | — | — |
-| parser | specifies the value extracted from formatter input.(only works when `type` is 'text') | `(string) => string` | — | — |
-| show-password | whether to show toggleable password input | boolean | — | false |
-| disabled | whether Input is disabled | boolean | — | false |
-| size | size of Input, works when `type` is not 'textarea' | string | large / default / small | — |
-| prefix-icon | prefix icon component | `string \| Component` | — | — |
-| suffix-icon | suffix icon component | `string \| Component` | — | — |
-| rows | number of rows of textarea, only works when `type` is 'textarea' | number | — | 2 |
-| autosize | whether textarea has an adaptive height, only works when `type` is 'textarea'. Can accept an object, e.g. `{ minRows: 2, maxRows: 6 }` | boolean / object | — | false |
-| autocomplete | same as `autocomplete` in native input | string | — | off |
-| name | same as `name` in native input | string | — | — |
-| readonly | same as `readonly` in native input | boolean | — | false |
-| max | same as `max` in native input | — | — | — |
-| min | same as `min` in native input | — | — | — |
-| step | same as `step` in native input | — | — | — |
-| resize | control the resizability | string | none / both / horizontal / vertical | — |
-| autofocus | same as `autofocus` in native input | boolean | — | false |
-| form | same as `form` in native input | string | — | — |
-| label | label text | string | — | — |
-| tabindex | input tabindex | string / number | - | - |
-| validate-event | whether to trigger form validation | boolean | - | true |
-| input-style | the style of the input element or textarea element | object | - | {} |
+### Attributes
-## Input Slots
+| Name | Description | Type | Default |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| type | type of input | ^[string]`'text' \| 'textarea' \| ...` [native input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types) | text |
+| model-value / v-model | binding value | ^[string] \| ^[number] | — |
+| maxlength | the max length | ^[string] \| ^[number] | — |
+| minlength | same as `minlength` in native input | ^[number] | — |
+| show-word-limit | whether show word count, only works when `type` is 'text' or 'textarea' | ^[boolean] | false |
+| placeholder | placeholder of Input | ^[string] | — |
+| clearable | whether to show clear button | ^[boolean] | false |
+| formatter | specifies the format of the value presented input.(only works when `type` is 'text') | ^[Function]`(value: string \| number) => string` | — |
+| parser | specifies the value extracted from formatter input.(only works when `type` is 'text') | ^[Function]`(value: string) => string` | — |
+| show-password | whether to show toggleable password input | ^[boolean] | false |
+| disabled | whether Input is disabled | ^[boolean] | false |
+| size | size of Input, works when `type` is not 'textarea' | ^[enum]`'large' \| 'default' \| 'small'` | — |
+| prefix-icon | prefix icon component | ^[string] \| ^[Component] | — |
+| suffix-icon | suffix icon component | ^[string] \| ^[Component] | — |
+| rows | number of rows of textarea, only works when `type` is 'textarea' | ^[number] | 2 |
+| autosize | whether textarea has an adaptive height, only works when `type` is 'textarea'. Can accept an object, e.g. `{ minRows: 2, maxRows: 6 }` | ^[boolean] \| ^[object]`{ minRows?: number, maxRows?: number }` | false |
+| autocomplete | same as `autocomplete` in native input | ^[string] | off |
+| name | same as `name` in native input | ^[string] | — |
+| readonly | same as `readonly` in native input | ^[boolean] | false |
+| max | same as `max` in native input | — | — |
+| min | same as `min` in native input | — | — |
+| step | same as `step` in native input | — | — |
+| resize | control the resizability | ^[enum]`'none' \| 'both' \| 'horizontal' \| 'vertical'` | — |
+| autofocus | same as `autofocus` in native input | ^[boolean] | false |
+| form | same as `form` in native input | `string` | — |
+| label | same as `aira-label` in native input | ^[string] | — |
+| tabindex | input tabindex | ^[string] \| ^[number] | — |
+| validate-event | whether to trigger form validation | ^[boolean] | true |
+| input-style | the style of the input element or textarea element | ^[string] \| ^[object]`CSSProperties \| CSSProperties[] \| string[]` | {} |
+
+### Events
+
+| Name | Description | Parameters |
+| ------ | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| blur | triggers when Input blurs | ^[Function]`(event: FocusEvent) => void` |
+| focus | triggers when Input focuses | ^[Function]`(event: FocusEvent) => void` |
+| change | triggers when the input box loses focus or the user presses Enter, only if the modelValue has changed | ^[Function]`(value: string \| number) => void` |
+| input | triggers when the Input value change | ^[Function]`(value: string \| number) => void` |
+| clear | triggers when the Input is cleared by clicking the clear button | ^[Function]`() => void` |
+
+### Slots
| Name | Description |
| ------- | ------------------------------------------------------------------------- |
@@ -158,20 +170,16 @@ input/length-limiting
| prepend | content to prepend before Input, only works when `type` is not 'textarea' |
| append | content to append after Input, only works when `type` is not 'textarea' |
-## Input Events
+### Exposes
-| Name | Description | Parameters |
-| ------ | ----------------------------------------------------------------------------------------------------- | ------------------------- |
-| blur | triggers when Input blurs | (event: FocusEvent) |
-| focus | triggers when Input focuses | (event: FocusEvent) |
-| change | triggers when the input box loses focus or the user presses Enter, only if the modelValue has changed | (value: string \| number) |
-| input | triggers when the Input value change | (value: string \| number) |
-| clear | triggers when the Input is cleared by clicking the clear button | — |
-
-## Input Methods
-
-| Method | Description | Parameters |
-| ------ | -------------------------------- | ---------- |
-| focus | focus the input element | — |
-| blur | blur the input element | — |
-| select | select the text in input element | — |
+| Name | Description | Type |
+| -------------- | -------------------------------- | ------------------------------------------------------- |
+| blur | blur the input element | ^[Function]`() => void` |
+| clear | clear input value | ^[Function]`() => void` |
+| focus | focus the input element | ^[Function]`() => void` |
+| input | HTML input element | ^[Object]`Ref` |
+| ref | HTML element, input or textarea | ^[Object]`Ref` |
+| resizeTextarea | resize textarea | ^[Function]`() => void` |
+| select | select the text in input element | ^[Function]`() => void` |
+| textarea | HTML textarea element | ^[Object]`Ref` |
+| textareaStyle | style of textarea | ^[Object]`Ref` |
diff --git a/packages/components/input/src/input.ts b/packages/components/input/src/input.ts
index b02412798b..288260926a 100644
--- a/packages/components/input/src/input.ts
+++ b/packages/components/input/src/input.ts
@@ -13,12 +13,24 @@ import type { ExtractPropTypes, StyleValue } from 'vue'
export type InputAutoSize = { minRows?: number; maxRows?: number } | boolean
export const inputProps = buildProps({
+ /**
+ * @description native input id
+ */
id: {
type: String,
default: undefined,
},
+ /**
+ * @description input box size
+ */
size: useSizeProp,
+ /**
+ * @description whether to disable
+ */
disabled: Boolean,
+ /**
+ * @description binding value
+ */
modelValue: {
type: definePropType([
String,
@@ -27,72 +39,129 @@ export const inputProps = buildProps({
]),
default: '',
},
+ /**
+ * @description type of input
+ */
type: {
type: String,
default: 'text',
},
+ /**
+ * @description control the resizability
+ */
resize: {
type: String,
values: ['none', 'both', 'horizontal', 'vertical'],
},
+ /**
+ * @description whether textarea has an adaptive height
+ */
autosize: {
type: definePropType([Boolean, Object]),
default: false,
},
+ /**
+ * @description native input autocomplete
+ */
autocomplete: {
type: String,
default: 'off',
},
+ /**
+ * @description format content
+ */
formatter: {
type: Function,
},
+ /**
+ * @description parse content
+ */
parser: {
type: Function,
},
+ /**
+ * @description placeholder
+ */
placeholder: {
type: String,
},
+ /**
+ * @description native input form
+ */
form: {
type: String,
},
+ /**
+ * @description native input readonly
+ */
readonly: {
type: Boolean,
default: false,
},
+ /**
+ * @description native input readonly
+ */
clearable: {
type: Boolean,
default: false,
},
+ /**
+ * @description toggleable password input
+ */
showPassword: {
type: Boolean,
default: false,
},
+ /**
+ * @description word count
+ */
showWordLimit: {
type: Boolean,
default: false,
},
+ /**
+ * @description suffix icon
+ */
suffixIcon: {
type: iconPropType,
},
+ /**
+ * @description prefix icon
+ */
prefixIcon: {
type: iconPropType,
},
+ /**
+ * @description container role, internal properties provided for use by the picker component
+ */
containerRole: {
type: String,
default: undefined,
},
+ /**
+ * @description native input aira-label
+ */
label: {
type: String,
default: undefined,
},
+ /**
+ * @description input tabindex
+ */
tabindex: {
type: [String, Number],
default: 0,
},
+ /**
+ * @description whether to trigger form validation
+ */
validateEvent: {
type: Boolean,
default: true,
},
+ /**
+ * @description input or texearea element style
+ */
inputStyle: {
type: definePropType([Object, Array, String]),
default: () => mutable({} as const),