From 22da4ccb16aec0e0bd0269276dae4c0783336479 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E5=94=89LEntropy?= <Ai_LEntropy@126.com>
Date: Wed, 1 Jul 2026 20:20:42 +0800
Subject: [PATCH 1/4] feat(textarea): support clearable

---
 .../textarea/__tests__/textarea.test.tsx      | 46 +++++++++++++++
 .../textarea/_example/clearable.vue           | 16 ++++++
 .../components/textarea/_usage/props.json     |  8 ++-
 packages/components/textarea/props.ts         |  4 ++
 .../components/textarea/textarea.en-US.md     | 13 ++++-
 packages/components/textarea/textarea.md      | 13 ++++-
 packages/components/textarea/textarea.tsx     | 56 ++++++++++++++++++-
 packages/components/textarea/type.ts          | 11 +++-
 8 files changed, 158 insertions(+), 9 deletions(-)
 create mode 100644 packages/components/textarea/_example/clearable.vue

diff --git a/packages/components/textarea/__tests__/textarea.test.tsx b/packages/components/textarea/__tests__/textarea.test.tsx
index d13cc3e6c8..2c1171ae4c 100644
--- a/packages/components/textarea/__tests__/textarea.test.tsx
+++ b/packages/components/textarea/__tests__/textarea.test.tsx
@@ -107,6 +107,37 @@ describe('Textarea', () => {
       value.value = '123456';
       expect(textarea.element.value).toBe('12345');
     });
+
+    it(':clearable', async () => {
+      const wrapper = mount(() => <Textarea value="text" clearable />);
+      expect(wrapper.find('.t-textarea__clear').exists()).toBeTruthy();
+      expect(wrapper.find('.t-textarea__clear--visible').exists()).toBeFalsy();
+
+      await wrapper.trigger('mouseenter');
+      expect(wrapper.find('.t-textarea__clear--visible').exists()).toBeTruthy();
+    });
+
+    it(':clearable should show when value is number zero', async () => {
+      const wrapper = mount(() => <Textarea value={0} clearable />);
+
+      await wrapper.trigger('mouseenter');
+
+      expect(wrapper.find('.t-textarea__clear--visible').exists()).toBeTruthy();
+    });
+
+    it(':clearable should not show when empty, disabled or readonly', async () => {
+      const emptyWrapper = mount(() => <Textarea value="" clearable />);
+      await emptyWrapper.trigger('mouseenter');
+      expect(emptyWrapper.find('.t-textarea__clear--visible').exists()).toBeFalsy();
+
+      const disabledWrapper = mount(() => <Textarea value="text" clearable disabled />);
+      await disabledWrapper.trigger('mouseenter');
+      expect(disabledWrapper.find('.t-textarea__clear').exists()).toBeFalsy();
+
+      const readonlyWrapper = mount(() => <Textarea value="text" clearable readonly />);
+      await readonlyWrapper.trigger('mouseenter');
+      expect(readonlyWrapper.find('.t-textarea__clear').exists()).toBeFalsy();
+    });
   });
 
   describe(':events', () => {
@@ -149,5 +180,20 @@ describe('Textarea', () => {
       await textarea.trigger('keyup');
       expect(fn).toBeCalled();
     });
+
+    it(':onClear', async () => {
+      const onClear = vi.fn();
+      const onChange = vi.fn();
+      const wrapper = mount(() => <Textarea defaultValue="text" clearable onClear={onClear} onChange={onChange} />);
+      const textarea = wrapper.find('textarea');
+
+      await wrapper.trigger('mouseenter');
+      await wrapper.find('.t-textarea__clear').trigger('click');
+
+      expect(onClear).toHaveBeenCalledTimes(1);
+      expect(onClear.mock.calls[0][0].e.type).toBe('click');
+      expect(onChange).toHaveBeenCalledWith('', expect.objectContaining({ trigger: 'clear' }));
+      expect(textarea.element.value).toBe('');
+    });
   });
 });
diff --git a/packages/components/textarea/_example/clearable.vue b/packages/components/textarea/_example/clearable.vue
new file mode 100644
index 0000000000..f53e6527df
--- /dev/null
+++ b/packages/components/textarea/_example/clearable.vue
@@ -0,0 +1,16 @@
+<template>
+  <div style="width: 100%; max-width: 500px">
+    <t-textarea v-model="value" clearable placeholder="请输入" @clear="onClear" />
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue';
+import type { TextareaProps } from 'tdesign-vue-next';
+
+const value = ref('Hello TDesign');
+
+const onClear: TextareaProps['onClear'] = () => {
+  console.log('clear');
+};
+</script>
diff --git a/packages/components/textarea/_usage/props.json b/packages/components/textarea/_usage/props.json
index 856b190a74..d1e0f13da3 100644
--- a/packages/components/textarea/_usage/props.json
+++ b/packages/components/textarea/_usage/props.json
@@ -11,6 +11,12 @@
     "defaultValue": false,
     "options": []
   },
+  {
+    "name": "clearable",
+    "type": "Boolean",
+    "defaultValue": false,
+    "options": []
+  },
   {
     "name": "disabled",
     "type": "Boolean",
@@ -23,4 +29,4 @@
     "defaultValue": false,
     "options": []
   }
-]
\ No newline at end of file
+]
diff --git a/packages/components/textarea/props.ts b/packages/components/textarea/props.ts
index 1b8f49e089..2f5503abea 100644
--- a/packages/components/textarea/props.ts
+++ b/packages/components/textarea/props.ts
@@ -17,6 +17,8 @@ export default {
     type: [Boolean, Object] as PropType<TdTextareaProps['autosize']>,
     default: false as TdTextareaProps['autosize'],
   },
+  /** 是否可清空 */
+  clearable: Boolean,
   /** 是否禁用文本框 */
   disabled: {
     type: Boolean,
@@ -75,6 +77,8 @@ export default {
   onBlur: Function as PropType<TdTextareaProps['onBlur']>,
   /** 输入内容变化时触发 */
   onChange: Function as PropType<TdTextareaProps['onChange']>,
+  /** 清空按钮点击时触发 */
+  onClear: Function as PropType<TdTextareaProps['onClear']>,
   /** 获得焦点时触发 */
   onFocus: Function as PropType<TdTextareaProps['onFocus']>,
   /** 键盘按下时触发 */
diff --git a/packages/components/textarea/textarea.en-US.md b/packages/components/textarea/textarea.en-US.md
index b548191428..d0eb27f48d 100644
--- a/packages/components/textarea/textarea.en-US.md
+++ b/packages/components/textarea/textarea.en-US.md
@@ -1,5 +1,11 @@
 :: BASE_DOC ::
 
+### Clearable Textarea
+
+Textarea with a clear operation can quickly clear entered content.
+
+{{ clearable }}
+
 ## API
 
 ### Textarea Props
@@ -19,8 +25,10 @@ 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/packages/components/common.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/blob/develop/packages/components/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/blob/develop/packages/components/textarea/type.ts) | N
+clearable | Boolean | false | Whether the content can be cleared | N
 onBlur | Function |  | Typescript：`(value: TextareaValue, context: { e: FocusEvent }) => void`<br/> | N
-onChange | Function |  | Typescript：`(value: TextareaValue, context?: { e?: InputEvent }) => void`<br/> | N
+onChange | Function |  | Typescript：`(value: TextareaValue, context?: { e?: InputEvent \| MouseEvent; trigger?: 'input' \| 'clear' }) => void`<br/> | N
+onClear | Function |  | Typescript：`(context: { e: MouseEvent }) => 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
@@ -32,7 +40,8 @@ onValidate | Function |  | Typescript：`(context: { error?: 'exceed-maximum' \|
 name | params | description
 -- | -- | --
 blur | `(value: TextareaValue, context: { e: FocusEvent })` | \-
-change | `(value: TextareaValue, context?: { e?: InputEvent })` | \-
+change | `(value: TextareaValue, context?: { e?: InputEvent \| MouseEvent; trigger?: 'input' \| 'clear' })` | \-
+clear | `(context: { e: MouseEvent })` | \-
 focus | `(value: TextareaValue, context : { e: FocusEvent })` | \-
 keydown | `(value: TextareaValue, context: { e: KeyboardEvent })` | \-
 keypress | `(value: TextareaValue, context: { e: KeyboardEvent })` | \-
diff --git a/packages/components/textarea/textarea.md b/packages/components/textarea/textarea.md
index eed8c50352..98aac202b0 100644
--- a/packages/components/textarea/textarea.md
+++ b/packages/components/textarea/textarea.md
@@ -1,5 +1,11 @@
 :: BASE_DOC ::
 
+### 可清空的多行文本框
+
+带清空操作的多行文本框，可快捷清空输入过的内容。
+
+{{ clearable }}
+
 ## API
 
 ### Textarea Props
@@ -19,8 +25,10 @@ status | String | default | 文本框状态。可选项：default/success/warnin
 tips | String / Slot / Function | - | 输入框下方提示文本，会根据不同的 `status` 呈现不同的样式。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
 value | String / Number | - | 文本框值。支持语法糖 `v-model` 或 `v-model:value`。TS 类型：`TextareaValue` `type TextareaValue = string \| number`。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/textarea/type.ts) | N
 defaultValue | String / Number | - | 文本框值。非受控属性。TS 类型：`TextareaValue` `type TextareaValue = string \| number`。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/textarea/type.ts) | N
+clearable | Boolean | false | 是否可清空 | N
 onBlur | Function |  | TS 类型：`(value: TextareaValue, context: { e: FocusEvent }) => void`<br/>失去焦点时触发 | N
-onChange | Function |  | TS 类型：`(value: TextareaValue, context?: { e?: InputEvent }) => void`<br/>输入内容变化时触发 | N
+onChange | Function |  | TS 类型：`(value: TextareaValue, context?: { e?: InputEvent \| MouseEvent; trigger?: 'input' \| 'clear' }) => void`<br/>输入内容变化时触发 | N
+onClear | Function |  | TS 类型：`(context: { e: MouseEvent }) => void`<br/>清空按钮点击时触发 | N
 onFocus | Function |  | TS 类型：`(value: TextareaValue, context : { e: FocusEvent }) => void`<br/>获得焦点时触发 | N
 onKeydown | Function |  | TS 类型：`(value: TextareaValue, context: { e: KeyboardEvent }) => void`<br/>键盘按下时触发 | N
 onKeypress | Function |  | TS 类型：`(value: TextareaValue, context: { e: KeyboardEvent }) => void`<br/>按下字符键时触发（keydown -> keypress -> keyup） | N
@@ -32,7 +40,8 @@ onValidate | Function |  | TS 类型：`(context: { error?: 'exceed-maximum' \|
 名称 | 参数 | 描述
 -- | -- | --
 blur | `(value: TextareaValue, context: { e: FocusEvent })` | 失去焦点时触发
-change | `(value: TextareaValue, context?: { e?: InputEvent })` | 输入内容变化时触发
+change | `(value: TextareaValue, context?: { e?: InputEvent \| MouseEvent; trigger?: 'input' \| 'clear' })` | 输入内容变化时触发
+clear | `(context: { e: MouseEvent })` | 清空按钮点击时触发
 focus | `(value: TextareaValue, context : { e: FocusEvent })` | 获得焦点时触发
 keydown | `(value: TextareaValue, context: { e: KeyboardEvent })` | 键盘按下时触发
 keypress | `(value: TextareaValue, context: { e: KeyboardEvent })` | 按下字符键时触发（keydown -> keypress -> keyup）
diff --git a/packages/components/textarea/textarea.tsx b/packages/components/textarea/textarea.tsx
index dd8574c38e..c19a711ac8 100644
--- a/packages/components/textarea/textarea.tsx
+++ b/packages/components/textarea/textarea.tsx
@@ -10,7 +10,8 @@ import {
   StyleValue,
   CSSProperties,
 } from 'vue';
-import { isObject, merge, omit } from 'lodash-es';
+import { isNil, isObject, merge, omit } from 'lodash-es';
+import { CloseCircleFilledIcon as TdCloseCircleFilledIcon } from 'tdesign-icons-vue-next';
 
 import { FormItemInjectionKey } from '../form/constants';
 import setStyle from '@tdesign/common-js/utils/setStyle';
@@ -24,6 +25,7 @@ import {
   useTNodeJSX,
   usePrefixClass,
   useCommonClassName,
+  useGlobalIcon,
 } from '@tdesign/shared-hooks';
 
 import { useLengthLimit } from '../input/hooks/useLengthLimit';
@@ -42,6 +44,9 @@ export default defineComponent({
     const name = usePrefixClass('textarea');
     const TEXTAREA_TIPS_CLASS = computed(() => `${name.value}__tips`);
     const TEXTAREA_LIMIT = computed(() => `${name.value}__limit`);
+    const { CloseCircleFilledIcon } = useGlobalIcon({
+      CloseCircleFilledIcon: TdCloseCircleFilledIcon,
+    });
 
     const { value, modelValue } = toRefs(props);
     const [innerValue, setInnerValue] = useVModel(value, modelValue, props.defaultValue, props.onChange);
@@ -51,6 +56,7 @@ export default defineComponent({
 
     const refTextareaElem = ref<HTMLTextAreaElement>();
     const focused = ref(false);
+    const isHover = ref(false);
     const isComposing = ref(false);
 
     const focus = () => refTextareaElem.value?.focus();
@@ -95,7 +101,7 @@ export default defineComponent({
           val = typeof stringInfo === 'object' && stringInfo.characters;
         }
       }
-      !isComposing.value && setInnerValue(val, { e });
+      !isComposing.value && setInnerValue(val, { e, trigger: 'input' });
       nextTick(() => setInputValue(val));
       adjustTextareaHeight();
     };
@@ -143,6 +149,23 @@ export default defineComponent({
       formItem?.handleBlur();
     };
 
+    const getClearEvent = (context: MouseEvent | { e: MouseEvent }) => ('e' in context ? context.e : context);
+
+    const emitClear = (context: MouseEvent | { e: MouseEvent }) => {
+      const e = getClearEvent(context);
+      setInnerValue('', { e, trigger: 'clear' });
+      props.onClear?.({ e });
+      nextTick(() => {
+        refTextareaElem.value?.focus();
+        adjustTextareaHeight();
+      });
+    };
+
+    const onClearMouseDown = (context: MouseEvent | { e: MouseEvent }) => {
+      const e = getClearEvent(context);
+      e.preventDefault();
+    };
+
     // computed
     const textareaClasses = computed(() => {
       return [
@@ -150,9 +173,20 @@ export default defineComponent({
         {
           [`${prefix.value}-is-disabled`]: disabled.value,
           [`${prefix.value}-is-readonly`]: isReadonly.value,
+          [`${name.value}--clearable`]: props.clearable,
         },
       ];
     });
+    const showClear = computed(() => {
+      return Boolean(
+        props.clearable &&
+          !isNil(innerValue.value) &&
+          innerValue.value !== '' &&
+          !disabled.value &&
+          !isReadonly.value &&
+          isHover.value,
+      );
+    });
     const inputAttrs = computed<Record<string, any>>(() => {
       return getValidAttrs({
         autofocus: props.autofocus,
@@ -255,7 +289,16 @@ export default defineComponent({
         ));
 
       return (
-        <div class={textareaClasses.value} {...omit(attrs, ['style'])}>
+        <div
+          class={textareaClasses.value}
+          onMouseenter={() => {
+            isHover.value = true;
+          }}
+          onMouseleave={() => {
+            isHover.value = false;
+          }}
+          {...omit(attrs, ['style'])}
+        >
           <textarea
             onInput={handleInput}
             onCompositionstart={onCompositionstart}
@@ -266,6 +309,13 @@ export default defineComponent({
             {...inputEvents}
             {...inputAttrs.value}
           ></textarea>
+          {props.clearable && !disabled.value && !isReadonly.value ? (
+            <CloseCircleFilledIcon
+              class={[`${name.value}__clear`, { [`${name.value}__clear--visible`]: showClear.value }]}
+              onMousedown={onClearMouseDown}
+              onClick={emitClear}
+            />
+          ) : null}
           {textTips || limitText ? (
             <div
               class={[
diff --git a/packages/components/textarea/type.ts b/packages/components/textarea/type.ts
index aabb06bc87..dc35cab8a9 100644
--- a/packages/components/textarea/type.ts
+++ b/packages/components/textarea/type.ts
@@ -22,6 +22,11 @@ export interface TdTextareaProps {
    * @default false
    */
   autosize?: boolean | { minRows?: number; maxRows?: number };
+  /**
+   * 是否可清空
+   * @default false
+   */
+  clearable?: boolean;
   /**
    * 是否禁用文本框
    */
@@ -75,7 +80,11 @@ export interface TdTextareaProps {
   /**
    * 输入内容变化时触发
    */
-  onChange?: (value: TextareaValue, context?: { e?: InputEvent }) => void;
+  onChange?: (value: TextareaValue, context?: { e?: InputEvent | MouseEvent; trigger?: 'input' | 'clear' }) => void;
+  /**
+   * 清空按钮点击时触发
+   */
+  onClear?: (context: { e: MouseEvent }) => void;
   /**
    * 获得焦点时触发
    */

From 5cc7764bca0a276edde1a1765a8516a1a7e1f672 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E5=94=89LEntropy?= <Ai_LEntropy@126.com>
Date: Wed, 29 Jul 2026 15:12:50 +0800
Subject: [PATCH 2/4] fix(textarea): link clearable styles

---
 packages/common | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/common b/packages/common
index 6b9ef7376f..f083285e95 160000
--- a/packages/common
+++ b/packages/common
@@ -1 +1 @@
-Subproject commit 6b9ef7376f97847865cf78b449374d6a9e487351
+Subproject commit f083285e95701c4654e656e6acc140328c0694b2

From 7f06f67c3e30115ae2b53d09418e388ec6a4059f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E5=94=89LEntropy?= <Ai_LEntropy@126.com>
Date: Wed, 29 Jul 2026 15:17:40 +0800
Subject: [PATCH 3/4] revert: unlink unmerged common styles

---
 packages/common | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/common b/packages/common
index f083285e95..6b9ef7376f 160000
--- a/packages/common
+++ b/packages/common
@@ -1 +1 @@
-Subproject commit f083285e95701c4654e656e6acc140328c0694b2
+Subproject commit 6b9ef7376f97847865cf78b449374d6a9e487351

From 6969a74509f206188d174dbd29a650303240d50f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:32:00 +0000
Subject: [PATCH 4/4] chore: update common to PR 2583

---
 packages/common | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/common b/packages/common
index 5aedfdf7ab..ff5ce40ca2 160000
--- a/packages/common
+++ b/packages/common
@@ -1 +1 @@
-Subproject commit 5aedfdf7ab0457141b0a886d2126e22bbdb42cae
+Subproject commit ff5ce40ca26310c598240747ed08f86d49bae2ba