docs(texarea): sync api

Tencent · Nov 15, 2024 · a5ebccc · a5ebccc
1 parent 1ba59bb
commit a5ebccc
Show file tree

Hide file tree

Showing 5 changed files with 41 additions and 32 deletions.
diff --git a/src/textarea/props.ts b/src/textarea/props.ts
@@ -8,10 +8,8 @@ import { TdTextareaProps } from './type';
 import { PropType } from 'vue';
 
 export default {
-  allowInputOverMax: {
-    type: Boolean,
-    default: false,
-  },
+  /** 超出maxlength或maxcharacter之后是否还允许输入 */
+  allowInputOverMax: Boolean,
   /** 自动聚焦，拉起键盘 */
   autofocus: Boolean,
   /** 高度自动撑开。 autosize = true 表示组件高度自动撑开，同时，依旧允许手动拖高度。如果设置了 autosize.maxRows 或者 autosize.minRows 则不允许手动调整高度 */
@@ -30,7 +28,7 @@ export default {
   },
   /** 用户最多可以输入的字符个数 */
   maxlength: {
-    type: [Number, String] as PropType<TdTextareaProps['maxlength']>,
+    type: [String, Number] as PropType<TdTextareaProps['maxlength']>,
   },
   /** 名称，HTML 元素原生属性 */
   name: {
@@ -42,12 +40,17 @@ export default {
     type: String,
     default: undefined,
   },
-  /** 文本框是否只读 */
-  readonly: Boolean,
+  /** 只读状态 */
+  readonly: {
+    type: Boolean,
+    default: undefined,
+  },
   /** 文本框状态 */
   status: {
     type: String as PropType<TdTextareaProps['status']>,
+    default: 'default' as TdTextareaProps['status'],
     validator(val: TdTextareaProps['status']): boolean {
+      if (!val) return true;
       return ['default', 'success', 'warning', 'error'].includes(val);
     },
   },
@@ -58,10 +61,11 @@ export default {
   /** 文本框值 */
   value: {
     type: [String, Number] as PropType<TdTextareaProps['value']>,
+    default: undefined as TdTextareaProps['value'],
   },
-  /** v-model */
   modelValue: {
     type: [String, Number] as PropType<TdTextareaProps['value']>,
+    default: undefined as TdTextareaProps['value'],
   },
   /** 文本框值，非受控属性 */
   defaultValue: {

diff --git a/src/textarea/textarea.en-US.md b/src/textarea/textarea.en-US.md
@@ -1,30 +1,31 @@
 :: BASE_DOC ::
 
 ## API
+
 ### Textarea Props
 
 name | type | default | description | required
 -- | -- | -- | -- | --
 allowInputOverMax | Boolean | false | \- | N
 autofocus | Boolean | false | \- | N
 autosize | Boolean / Object | false | Typescript：`boolean \| { minRows?: number; maxRows?: number }` | N
-disabled | Boolean | false | \- | N
+disabled | Boolean | undefined | \- | N
 maxcharacter | Number | - | \- | N
-maxlength | Number / String | - | \- | N
+maxlength | String / Number | - | Typescript：`string \| number` | N
 name | String | - | \- | N
 placeholder | String | undefined | \- | N
-readonly | Boolean | false | \- | N
-status | String | - | options：default/success/warning/error | N
+readonly | Boolean | undefined | \- | N
+status | String | default | options: default/success/warning/error | N
 tips | String / Slot / Function | - | Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/src/common.ts) | N
-value | String / Number | - | `v-model` and `v-model:value` is supported。Typescript：`TextareaValue` `type TextareaValue = string`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
-defaultValue | String / Number | - | uncontrolled property。Typescript：`TextareaValue` `type TextareaValue = string`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
+value | String / Number | - | `v-model` and `v-model:value` is supported。Typescript：`TextareaValue` `type TextareaValue = string \| number`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
+defaultValue | String / Number | - | uncontrolled property。Typescript：`TextareaValue` `type TextareaValue = string \| number`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
 onBlur | Function |  | Typescript：`(value: TextareaValue, context: { e: FocusEvent }) => void`<br/> | N
 onChange | Function |  | Typescript：`(value: TextareaValue, context?: { e?: InputEvent }) => void`<br/> | N
 onFocus | Function |  | Typescript：`(value: TextareaValue, context : { e: FocusEvent }) => void`<br/> | N
 onKeydown | Function |  | Typescript：`(value: TextareaValue, context: { e: KeyboardEvent }) => void`<br/> | N
 onKeypress | Function |  | Typescript：`(value: TextareaValue, context: { e: KeyboardEvent }) => void`<br/> | N
 onKeyup | Function |  | Typescript：`(value: TextareaValue, context: { e: KeyboardEvent }) => void`<br/> | N
-onValidate | Function |  | Typescript：`(context: { error?: 'exceed-maximum' \| 'below-minimum' }) => void`<br/>trigger on text length being over max length or max character | N
+onValidate | Function |  | Typescript：`(context: { error?: 'exceed-maximum' \| 'below-minimum' }) => void`<br/> | N
 
 ### Textarea Events
 
@@ -36,3 +37,4 @@ focus | `(value: TextareaValue, context : { e: FocusEvent })` | \-
 keydown | `(value: TextareaValue, context: { e: KeyboardEvent })` | \-
 keypress | `(value: TextareaValue, context: { e: KeyboardEvent })` | \-
 keyup | `(value: TextareaValue, context: { e: KeyboardEvent })` | \-
+validate | `(context: { error?: 'exceed-maximum' \| 'below-minimum' })` | \-
diff --git a/src/textarea/textarea.md b/src/textarea/textarea.md
@@ -1,23 +1,24 @@
 :: BASE_DOC ::
 
 ## API
+
 ### Textarea Props
 
-名称 | 类型 | 默认值 | 说明 | 必传
+名称 | 类型 | 默认值 | 描述 | 必传
 -- | -- | -- | -- | --
 allowInputOverMax | Boolean | false | 超出maxlength或maxcharacter之后是否还允许输入 | N
 autofocus | Boolean | false | 自动聚焦，拉起键盘 | N
 autosize | Boolean / Object | false | 高度自动撑开。 autosize = true 表示组件高度自动撑开，同时，依旧允许手动拖高度。如果设置了 autosize.maxRows 或者 autosize.minRows 则不允许手动调整高度。TS 类型：`boolean \| { minRows?: number; maxRows?: number }` | N
-disabled | Boolean | false | 是否禁用文本框 | N
+disabled | Boolean | undefined | 是否禁用文本框 | N
 maxcharacter | Number | - | 用户最多可以输入的字符个数，一个中文汉字表示两个字符长度 | N
-maxlength | Number / String | - | 用户最多可以输入的字符个数 | N
+maxlength | String / Number | - | 用户最多可以输入的字符个数。TS 类型：`string \| number` | N
 name | String | - | 名称，HTML 元素原生属性 | N
 placeholder | String | undefined | 占位符 | N
-readonly | Boolean | false | 只读状态 | N
-status | String | - | 文本框状态。可选项：default/success/warning/error | N
+readonly | Boolean | undefined | 只读状态 | N
+status | String | default | 文本框状态。可选项：default/success/warning/error | N
 tips | String / Slot / Function | - | 输入框下方提示文本，会根据不同的 `status` 呈现不同的样式。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/src/common.ts) | N
-value | String / Number | - | 文本框值。支持语法糖 `v-model` 或 `v-model:value`。TS 类型：`TextareaValue` `type TextareaValue = string`。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
-defaultValue | String / Number | - | 文本框值。非受控属性。TS 类型：`TextareaValue` `type TextareaValue = string`。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
+value | String / Number | - | 文本框值。支持语法糖 `v-model` 或 `v-model:value`。TS 类型：`TextareaValue` `type TextareaValue = string \| number`。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
+defaultValue | String / Number | - | 文本框值。非受控属性。TS 类型：`TextareaValue` `type TextareaValue = string \| number`。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/tree/develop/src/textarea/type.ts) | N
 onBlur | Function |  | TS 类型：`(value: TextareaValue, context: { e: FocusEvent }) => void`<br/>失去焦点时触发 | N
 onChange | Function |  | TS 类型：`(value: TextareaValue, context?: { e?: InputEvent }) => void`<br/>输入内容变化时触发 | N
 onFocus | Function |  | TS 类型：`(value: TextareaValue, context : { e: FocusEvent }) => void`<br/>获得焦点时触发 | N
@@ -36,3 +37,4 @@ focus | `(value: TextareaValue, context : { e: FocusEvent })` | 获得焦点时
 keydown | `(value: TextareaValue, context: { e: KeyboardEvent })` | 键盘按下时触发
 keypress | `(value: TextareaValue, context: { e: KeyboardEvent })` | 按下字符键时触发（keydown -> keypress -> keyup）
 keyup | `(value: TextareaValue, context: { e: KeyboardEvent })` | 释放键盘时触发
+validate | `(context: { error?: 'exceed-maximum' \| 'below-minimum' })` | 字数超出限制时触发
diff --git a/src/textarea/textarea.tsx b/src/textarea/textarea.tsx
@@ -22,6 +22,7 @@ import { getCharacterLength } from '../_common/js/utils/helper';
 // hooks
 import useVModel from '../hooks/useVModel';
 import { useDisabled } from '../hooks/useDisabled';
+import { useReadonly } from '../hooks/useReadonly';
 import { useTNodeJSX } from '../hooks/tnode';
 import { usePrefixClass, useCommonClassName } from '../hooks/useConfig';
 import useLengthLimit from '../input/useLengthLimit';
@@ -53,6 +54,7 @@ export default defineComponent({
     const { value, modelValue } = toRefs(props);
     const [innerValue, setInnerValue] = useVModel(value, modelValue, props.defaultValue, props.onChange);
     const disabled = useDisabled();
+    const isReadonly = useReadonly();
     const textareaStyle = ref<CSSProperties>({});
 
     const refTextareaElem = ref<HTMLTextAreaElement>();
@@ -151,15 +153,15 @@ export default defineComponent({
         name.value,
         {
           [`${prefix.value}-is-disabled`]: disabled.value,
-          [`${prefix.value}-is-readonly`]: props.readonly,
+          [`${prefix.value}-is-readonly`]: isReadonly.value,
         },
       ];
     });
     const inputAttrs = computed<Record<string, any>>(() => {
       return getValidAttrs({
         autofocus: props.autofocus,
         disabled: disabled.value,
-        readonly: props.readonly,
+        readonly: isReadonly.value,
         placeholder: props.placeholder,
         maxlength: (!props.allowInputOverMax && props.maxlength) || undefined,
         name: props.name || undefined,

diff --git a/src/textarea/type.ts b/src/textarea/type.ts
@@ -24,7 +24,6 @@ export interface TdTextareaProps {
   autosize?: boolean | { minRows?: number; maxRows?: number };
   /**
    * 是否禁用文本框
-   * @default false
    */
   disabled?: boolean;
   /**
@@ -34,7 +33,7 @@ export interface TdTextareaProps {
   /**
    * 用户最多可以输入的字符个数
    */
-  maxlength?: number | string;
+  maxlength?: string | number;
   /**
    * 名称，HTML 元素原生属性
    * @default ''
@@ -45,12 +44,12 @@ export interface TdTextareaProps {
    */
   placeholder?: string;
   /**
-   * 文本框是否只读
-   * @default false
+   * 只读状态
    */
   readonly?: boolean;
   /**
    * 文本框状态
+   * @default default
    */
   status?: 'default' | 'success' | 'warning' | 'error';
   /**
@@ -61,14 +60,14 @@ export interface TdTextareaProps {
    * 文本框值
    */
   value?: TextareaValue;
-  /**
-   * 输入框的值
-   */
-  modelValue?: TextareaValue;
   /**
    * 文本框值，非受控属性
    */
   defaultValue?: TextareaValue;
+  /**
+   * 文本框值
+   */
+  modelValue?: TextareaValue;
   /**
    * 失去焦点时触发
    */