feat(Textarea): 增加 ref 属性 (#3229)

xiaoyatong · web-flow · commit c20801d033e5 · 2025-05-23T16:48:43.000+08:00
* feat(Textarea): 增加 ref 属性

* feat: add get functions

* fix: 暴露 nativeElement
diff --git a/src/packages/input/doc.en-US.md b/src/packages/input/doc.en-US.md
@@ -148,6 +148,17 @@ import { Input } from '@nutui/nutui-react'
 | onClear | Triggered when the clear button is clicked | `(value: string) => void` | `-` |
 | onClick | Triggered when the input container is clicked | `(value: MouseEvent<HTMLDivElement>) => void` | `-` |
 
+### Ref
+
+You can get Ref of Input.
+
+| Event | Description | Arguments |
+| --- | --- | --- |
+| clear | clear the value of input | `-` |
+| focus | focus the input | `-` |
+| blur | blur the input | `-` |
+| get | get the input ref | `-` |
+
 ## Theming
 
 ### CSS Variables
diff --git a/src/packages/input/doc.md b/src/packages/input/doc.md
@@ -151,6 +151,17 @@ import { Input } from '@nutui/nutui-react'
 
 此外还支持以下原生属性：`onCompositionStart` `onCompositionEnd`
 
+### Ref
+
+通过 ref 可以获取到 Input 实例并调用实例方法。
+
+| 方法名 | 说明 | 参数 |
+| --- | --- | --- |
+| clear | 清除容器中的数据 | `-` |
+| focus | 使容器获取焦点 | `-` |
+| blur | 使容器失去焦点 | `-` |
+| get | 获取当前容器 | `-` |
+
 ## 主题定制
 
 ### 样式变量
diff --git a/src/packages/input/doc.taro.md b/src/packages/input/doc.taro.md
@@ -151,6 +151,17 @@ import { Input } from '@nutui/nutui-react-taro'
 
 此外还支持 Taro 中的 [Input 属性](https://docs.taro.zone/docs/components/forms/input/)
 
+### Ref
+
+通过 ref 可以获取到 Input 实例并调用实例方法。
+
+| 方法名 | 说明 | 参数 |
+| --- | --- | --- |
+| clear | 清除容器中的数据 | `-` |
+| focus | 使容器获取焦点 | `-` |
+| blur | 使容器失去焦点 | `-` |
+| get | 获取当前容器 | `-` |
+
 ## 主题定制
 
 ### 样式变量
diff --git a/src/packages/input/doc.zh-TW.md b/src/packages/input/doc.zh-TW.md
@@ -148,6 +148,17 @@ import { Input } from '@nutui/nutui-react'
 | onClear | 点击清空按钮时触发 | `(value: string) => void` | `-` |
 | onClick | 点击 input 容器触发 | `(value: MouseEvent<HTMLDivElement>) => void` | `-` |
 
+### Ref
+
+通過 ref 可以獲取到 Input 實例並調用實例方法。
+
+| 方法名 | 說明 | 參數 |
+| --- | --- | --- |
+| clear | 清除容器中的數據 | `-` |
+| focus | 使容器獲取焦點 | `-` |
+| blur | 使容器失去焦點 | `-` |
+| get | 獲取當前容器 | `-` |
+
 ## 主题定制
 
 ### 样式变量
diff --git a/src/packages/input/input.taro.tsx b/src/packages/input/input.taro.tsx
@@ -88,6 +88,7 @@ export const Input = forwardRef((props: Partial<TaroInputProps>, ref) => {
       blur: () => {
         inputRef.current?.blur()
       },
+      get: () => inputRef.current,
       get nativeElement() {
         return inputRef.current
       },
diff --git a/src/packages/input/input.tsx b/src/packages/input/input.tsx
@@ -85,6 +85,7 @@ export const Input = forwardRef(
       clear: () => setValue(''),
       focus: () => inputRef.current?.focus(),
       blur: () => inputRef.current?.blur(),
+      get: () => inputRef.current,
       get nativeElement() {
         return inputRef.current
       },
diff --git a/src/packages/textarea/doc.en-US.md b/src/packages/textarea/doc.en-US.md
@@ -95,6 +95,17 @@ import { TextArea } from '@nutui/nutui-react'
 | onFocus | Triggered when focusing | `(event: FocusEvent<HTMLTextAreaElement>) => void` | `-` |
 | onBlur | Triggered when out of focus | `(event: FocusEvent<HTMLTextAreaElement>) => void` | `-` |
 
+### Ref
+
+You can get Ref of Textarea.
+
+| Event | Description | Arguments |
+| --- | --- | --- |
+| clear | clear the value of textarea | `-` |
+| focus | focus the textarea | `-` |
+| blur | blur the textarea | `-` |
+| nativeElement | get the textarea ref | `-` |
+
 ## Theming
 
 ### CSS Variables
diff --git a/src/packages/textarea/doc.md b/src/packages/textarea/doc.md
@@ -95,6 +95,17 @@ import { TextArea } from '@nutui/nutui-react'
 | onFocus | 聚焦时触发 | `(event: FocusEvent<HTMLTextAreaElement>) => void` | `-` |
 | onBlur | 失焦时触发 | `(event: FocusEvent<HTMLTextAreaElement>) => void` | `-` |
 
+### Ref
+
+通过 ref 可以获取到 Textarea 实例并调用实例方法。
+
+| 方法名 | 说明 | 参数 |
+| --- | --- | --- |
+| clear | 清除容器中的数据 | `-` |
+| focus | 使容器获取焦点 | `-` |
+| blur | 使容器失去焦点 | `-` |
+| nativeElement | 获取当前容器 | `-` |
+
 ## 主题定制
 
 ### 样式变量
diff --git a/src/packages/textarea/doc.taro.md b/src/packages/textarea/doc.taro.md
@@ -95,6 +95,17 @@ import { TextArea } from '@nutui/nutui-react-taro'
 | onFocus | 聚焦时触发 | `(event) => void` | `-` |
 | onBlur | 失焦时触发 | `(event) => void` | `-` |
 
+### Ref
+
+通过 ref 可以获取到 Textarea 实例并调用实例方法。
+
+| 方法名 | 说明 | 参数 |
+| --- | --- | --- |
+| clear | 清除容器中的数据 | `-` |
+| focus | 使容器获取焦点 | `-` |
+| blur | 使容器失去焦点 | `-` |
+| nativeElement | 获取当前容器 | `-` |
+
 ## 主题定制
 
 ### 样式变量
diff --git a/src/packages/textarea/doc.zh-TW.md b/src/packages/textarea/doc.zh-TW.md
@@ -94,6 +94,17 @@ import { TextArea } from '@nutui/nutui-react'
 | onFocus | 聚焦時觸發 | `(event) => void` | `-` |
 | onBlur | 失焦時觸發 | `(event) => void` | `-` |
 
+### Ref
+
+通過 ref 可以獲取到 Textarea 實例並調用實例方法。
+
+| 方法名 | 說明 | 參數 |
+| --- | --- | --- |
+| clear | 清除容器中的數據 | `-` |
+| focus | 使容器獲取焦點 | `-` |
+| blur | 使容器失去焦點 | `-` |
+| nativeElement | 獲取當前容器 | `-` |
+
 ## 主題定制
 
 ### 樣式變量
diff --git a/src/packages/textarea/textarea.taro.tsx b/src/packages/textarea/textarea.taro.tsx
@@ -1,4 +1,4 @@
-import React, { FunctionComponent, useRef } from 'react'
+import React, { forwardRef, useRef, useImperativeHandle } from 'react'
 import classNames from 'classnames'
 import Taro from '@tarojs/taro'
 import { BaseEventOrig, Textarea, View } from '@tarojs/components'
@@ -18,9 +18,7 @@ const defaultProps = {
   plain: false,
   status: 'default',
 } as TaroTextAreaProps
-export const TextArea: FunctionComponent<Partial<TaroTextAreaProps>> = (
-  props
-) => {
+export const TextArea = forwardRef((props: Partial<TaroTextAreaProps>, ref) => {
   const { locale } = useConfig()
   const {
     className,
@@ -53,20 +51,21 @@ export const TextArea: FunctionComponent<Partial<TaroTextAreaProps>> = (
     return value
   }
 
-  const [inputValue, setInputValue] = usePropsValue<string>({
+  const [innerValue, setInnerValue] = usePropsValue<string>({
     value,
     defaultValue,
     finalValue: format(defaultValue),
     onChange,
   })
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
 
   const handleChange = (event: BaseEventOrig) => {
     const text = event?.detail?.value
     if (text) {
       const value = compositionRef.current ? text : format(text)
-      setInputValue(value)
+      setInnerValue(value)
     } else {
-      setInputValue('')
+      setInnerValue('')
     }
   }
 
@@ -82,6 +81,19 @@ export const TextArea: FunctionComponent<Partial<TaroTextAreaProps>> = (
     onBlur?.(event)
   }
 
+  useImperativeHandle(ref, () => {
+    return {
+      clear: () => {
+        setInnerValue('')
+      },
+      focus: () => textareaRef.current?.focus(),
+      blur: () => textareaRef.current?.blur(),
+      get nativeElement() {
+        return textareaRef.current
+      },
+    }
+  })
+
   return (
     <>
       <View
@@ -100,6 +112,7 @@ export const TextArea: FunctionComponent<Partial<TaroTextAreaProps>> = (
       >
         <Textarea
           {...rest}
+          ref={textareaRef}
           nativeProps={{
             style,
             readOnly,
@@ -117,7 +130,7 @@ export const TextArea: FunctionComponent<Partial<TaroTextAreaProps>> = (
           style={Taro.getEnv() === 'WEB' ? undefined : style}
           disabled={Taro.getEnv() === 'WEB' ? disabled : disabled || readOnly}
           // @ts-ignore
-          value={inputValue}
+          value={innerValue}
           onInput={handleChange}
           onBlur={handleBlur}
           onFocus={handleFocus}
@@ -133,12 +146,12 @@ export const TextArea: FunctionComponent<Partial<TaroTextAreaProps>> = (
               [`${classPrefix}-limit-disabled`]: disabled,
             })}
           >
-            {inputValue.length}/{maxLength < 0 ? 0 : maxLength}
+            {innerValue.length}/{maxLength < 0 ? 0 : maxLength}
           </View>
         )}
       </View>
     </>
   )
-}
+})
 
 TextArea.displayName = 'NutTextArea'
diff --git a/src/packages/textarea/textarea.tsx b/src/packages/textarea/textarea.tsx
diff --git a/src/sites/sites-react/doc/docs/react/migrate-from-v2.en-US.md b/src/sites/sites-react/doc/docs/react/migrate-from-v2.en-US.md
diff --git a/src/sites/sites-react/doc/docs/react/migrate-from-v2.md b/src/sites/sites-react/doc/docs/react/migrate-from-v2.md
diff --git a/src/sites/sites-react/doc/docs/taro/migrate-from-v2.en-US.md b/src/sites/sites-react/doc/docs/taro/migrate-from-v2.en-US.md
diff --git a/src/sites/sites-react/doc/docs/taro/migrate-from-v2.md b/src/sites/sites-react/doc/docs/taro/migrate-from-v2.md
