---
name: "Textarea"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "Textarea - 文本域输入框"
---

## Textarea

> [VERSION] @ray-js/ray >= 0.5.10

### 描述

文本域，用于多行文本输入与编辑。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `name` | `string` | 否 | - | 表单控件名称，提交表单时作为键名 |
| `value` | `string` | 否 | - | 输入框的内容 |
| `placeholder` | `string` | 否 | - | 输入框为空时占位符 |
| `placeholderStyle` | `string \| any` | 否 | - | 指定 placeholder 的样式，目前仅支持 color、fontSize 和 fontWeight（对象或 CSS 声明字符串） |
| `disabled` | `boolean` | 否 | `false` | 是否禁用 |
| `maxLength` | `number` | 否 | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 |
| `autoHeight` | `boolean` | 否 | `false` | 是否自动增高，设置 autoHeight 时，style.height 不生效 |
| `onInput` | `(event: TextareaInputEvent) => void` | 否 | - | 当键盘输入时触发 |
| `onFocus` | `(event: TextareaFocusEvent) => void` | 否 | - | 输入框聚焦时触发 |
| `onBlur` | `(event: TextareaBlurEvent) => void` | 否 | - | 输入框失去焦点时触发 |
| `onLinechange` | `(event: TextareaLineChangeEvent) => void` | 否 | - | 输入框行数变化时触发，detail 含 height、lineCount 等 |

### 引用对象

##### `interface` TextareaInputEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"input"` | 事件类型 |
| `detail` | `TextareaInputDetail` | 事件数据 |
| `value` | `string` | textarea 当前值 |

##### `interface` TextareaFocusEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"focus"` | 事件类型 |
| `detail` | `TextareaFocusDetail` | 事件数据 |

##### `interface` TextareaBlurEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"blur"` | 事件类型 |
| `detail` | `TextareaValueDetail` | 事件数据 |

##### `interface` TextareaLineChangeEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"linechange"` | 事件类型 |
| `detail` | `TextareaLineChangeDetail` | 事件数据 |

##### `interface` TextareaInputDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `value` | `string` | textarea 内容 |
| `cursor` | `number` | 光标位置 |
| `keyCode` | `number` | 键值 |

##### `interface` BaseEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `string` | 事件类型 |
| `timeStamp` | `number` | 页面打开到触发事件所经过的毫秒数 |
| `target` | `Target` | 触发事件的源组件 |
| `currentTarget` | `Target` | 当前组件的一些属性值集合 |
| `mark` | `any` | 事件标记数据 |

##### `interface` TextareaFocusDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `value` | `string` | 输入框内容 |

##### `interface` TextareaValueDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `value` | `string` | 输入框内容 |

##### `interface` TextareaLineChangeDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `height` | `number` | 输入框高度 |
| `lineCount` | `number` | 行数 |
| `heightRpx` | `number` | 输入框高度，单位 rpx |
| `lineHeight` | `number` | 行高 |

##### `interface` Target

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 事件源组件的id |
| `dataset` | `Record<string, unknown>` | 事件源组件上的 `dataset` 自定义属性组成的集合 |


### 示例代码

#### 基础用法

```tsx
import React from 'react';
import { Textarea, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Textarea placeholder="请输入内容..." />
    </View>
  );
}
```

#### 多行输入

```tsx
import React, { useState } from 'react';
import { Textarea, Button, View, Text } from '@ray-js/ray';

export default function () {
  const [value, setValue] = useState('');

  return (
    <View style={{ padding: '20px' }}>
      <View style={{ marginBottom: '16px' }}>
        <Textarea
          value={value}
          placeholder="请输入..."
          maxLength={200}
          onInput={(e) => setValue(e.value)}
          style={{ marginTop: '8px', minHeight: '80px' }}
        />
        <Text style={{ marginTop: '8px', fontSize: '12px', color: '#999' }}>
          已输入 {value.length} / 200 字符
        </Text>
      </View>
      <View style={{ marginBottom: '16px' }}>
        <Text>自动增高:</Text>
        <Textarea
          autoHeight
          placeholder="输入内容会自动增高..."
          style={{ marginTop: '8px', minHeight: '40px' }}
        />
      </View>
    </View>
  );
}
```

#### 禁用与事件

```tsx
import React from 'react';
import { Textarea, View, Text } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <View style={{ marginBottom: '16px' }}>
        <Text>禁用状态:</Text>
        <Textarea
          disabled
          value="不可编辑的内容"
          placeholderStyle={{ color: '#ccc' }}
          style={{ marginTop: '8px' }}
        />
      </View>
      <View style={{ marginBottom: '16px' }}>
        <Text>事件监听:</Text>
        <Textarea
          name="feedback"
          placeholder="输入反馈内容..."
          onFocus={(e) => console.log('聚焦:', e.detail.value)}
          onBlur={(e) => console.log('失焦:', e.detail.value)}
          onLinechange={(e) => console.log('行数变化:', e.detail.lineCount)}
          style={{ marginTop: '8px', minHeight: '80px' }}
        />
      </View>
    </View>
  );
}
```