# textarea

> 基础库 1.0.0 开始支持，低版本需做[兼容处理](1003706)。

> __微信 Windows 版__：支持
> 
> __微信 Mac 版__：支持
> 
> __微信 鸿蒙 OS 版__：支持

渲染框架支持情况：Skyline （使用最新 [Nightly](/miniprogram/dev/devtools/nightly.html) 工具调试）、WebView

## 功能描述

多行输入框。该组件是[原生组件](/miniprogram/dev/component/native-component/native-component)，使用时请注意相关限制。

## 通用属性


```json
[
  {
    "属性": "value",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "输入框的内容",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "placeholder",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "输入框为空时占位符",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "placeholder-style",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "指定 placeholder 的样式，目前仅支持color,font-size,font-weight,line-height",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "disabled",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否禁用",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "maxlength",
    "类型": "number",
    "默认值": "140",
    "必填": "否",
    "说明": "最大输入长度，设置为 -1 的时候不限制最大长度",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "auto-focus",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "自动聚焦，拉起键盘。",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "focus",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "获取焦点",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "auto-height",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否自动增高，设置auto-height时，style.height不生效",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "cursor-spacing",
    "类型": "number",
    "默认值": "0",
    "必填": "否",
    "说明": "指定光标与键盘的距离。取\u0000INLINECODE_0\u0000距离底部的距离和\u0000INLINECODE_1\u0000指定的距离的最小值作为光标与键盘的距离",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "cursor",
    "类型": "number",
    "默认值": "-1",
    "必填": "否",
    "说明": "指定focus时的光标位置",
    "最低版本": "[1.5.0](1003706)"
  },
  {
    "属性": "selection-start",
    "类型": "number",
    "默认值": "-1",
    "必填": "否",
    "说明": "光标起始位置，自动聚集时有效，需与\u0000INLINECODE_2\u0000搭配使用",
    "最低版本": "[1.9.0](1003706)"
  },
  {
    "属性": "selection-end",
    "类型": "number",
    "默认值": "-1",
    "必填": "否",
    "说明": "光标结束位置，自动聚集时有效，需与\u0000INLINECODE_3\u0000搭配使用",
    "最低版本": "[1.9.0](1003706)"
  },
  {
    "属性": "adjust-position",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "键盘弹起时，是否自动上推页面",
    "最低版本": "[1.9.90](1003706)"
  },
  {
    "属性": "hold-keyboard",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "focus时，点击页面的时候不收起键盘",
    "最低版本": "[2.8.2](1003706)"
  },
  {
    "属性": "disable-default-padding",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否去掉 iOS 下的默认内边距",
    "最低版本": "[2.10.0](1003706)"
  },
  {
    "属性": "confirm-type",
    "类型": "string",
    "默认值": "return",
    "必填": "否",
    "说明": "设置键盘右下角按钮的文字",
    "最低版本": "[2.13.0](1003706)",
    "子项": [
      {
        "合法值": "send",
        "说明": "右下角按钮为“发送”"
      },
      {
        "合法值": "search",
        "说明": "右下角按钮为“搜索”"
      },
      {
        "合法值": "next",
        "说明": "右下角按钮为“下一个”"
      },
      {
        "合法值": "go",
        "说明": "右下角按钮为“前往”"
      },
      {
        "合法值": "done",
        "说明": "右下角按钮为“完成”"
      },
      {
        "合法值": "return",
        "说明": "右下角按钮为“换行”"
      }
    ]
  },
  {
    "属性": "confirm-hold",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "点击键盘右下角按钮时是否保持键盘不收起",
    "最低版本": "[2.16.0](1003706)"
  },
  {
    "属性": "adjust-keyboard-to",
    "类型": "boolean",
    "默认值": "cursor",
    "必填": "否",
    "说明": "键盘对齐位置。",
    "最低版本": "[2.16.1](1003706)",
    "子项": [
      {
        "合法值": "cursor",
        "说明": "对齐光标位置"
      },
      {
        "合法值": "bottom",
        "说明": "对齐输入框底部"
      }
    ]
  },
  {
    "属性": "bind:focus",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度，在基础库 1.9.90 起支持",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:blur",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入框失去焦点时触发，event.detail = {value, cursor}",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:linechange",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入框行数变化时调用，event.detail = {height: 0, heightRpx: 0, lineCount: 0}",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:input",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "当键盘输入时，触发 input 事件，event.detail = {value, cursor, keyCode}，keyCode 为键值，目前工具还不支持返回keyCode参数。**bind:input 处理函数的返回值并不会反映到 textarea 上**",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:confirm",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "点击完成时， 触发 confirm 事件，event.detail = {value: value}",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:keyboardheightchange",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "键盘高度发生变化的时候触发此事件，event.detail = {height: height, duration: duration}",
    "最低版本": "[2.7.0](1003706)"
  }
]
```

## Skyline 特有属性


```json
[
  {
    "属性": "placeholder-style",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "需传入对象，格式为 \u0000INLINECODE_4\u0000",
    "最低版本": ""
  },
  {
    "属性": "bind:selectionchange",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "选区改变事件, {selectionStart, selectionEnd}",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "bind:keyboardcompositionstart",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入法开始新的输入时触发 （仅当输入法支持时触发）",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "bind:keyboardcompositionupdate",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入法输入字符时触发（仅当输入法支持时触发）",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "bind:keyboardcompositionend",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入法输入结束时触发（仅当输入法支持时触发）",
    "最低版本": "[3.2.0](1003706)"
  }
]
```

## WebView 特有属性


```json
[
  {
    "属性": "placeholder-class",
    "类型": "string",
    "默认值": "textarea-placeholder",
    "必填": "否",
    "说明": "指定 placeholder 的样式类，目前仅支持color,font-size和font-weight",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "fixed",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "如果 textarea 是在一个 \u0000INLINECODE_5\u0000 的区域，需要显示指定属性 fixed 为 true",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "show-confirm-bar",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "是否显示键盘上方带有”完成“按钮那一栏",
    "最低版本": "[1.6.0](1003706)"
  }
]
```

## Bug & Tip

1. `tip`: `textarea` 的 `blur` 事件会晚于页面上的 `tap` 事件，如果需要在 `button` 的点击事件获取 `textarea`，可以使用 `form` 的 `bind:submit`。
1. `tip`: 不建议在多行文本上对用户的输入进行修改，所以 `textarea` 的 `bind:input` 处理函数并不会将返回值反映到 `textarea` 上。
1. `tip` : 键盘高度发生变化，keyboardheightchange事件可能会多次触发，开发者对于相同的height值应该忽略掉
1. `bug`: 微信版本 `6.3.30`，`textarea` 在列表渲染时，新增加的 `textarea` 在自动聚焦时的位置计算错误。

## 示例代码

[在开发者工具中预览效果](https://developers.weixin.qq.com/s/QAwRn6m86tYu)

```html
<view class="section">
  <textarea bind:blur="bindTextAreaBlur" auto-height placeholder="自动变高" />
</view>
<view class="section">
  <textarea placeholder="placeholder颜色是红色的" placeholder-style="color:red;"  />
</view>
<view class="section">
  <textarea placeholder="这是一个可以自动聚焦的textarea" auto-focus />
</view>
<view class="section">
  <textarea placeholder="这个只有在按钮点击的时候才聚焦" focus="{{focus}}" />
  <view class="btn-area">
    <button bind:tap="bindButtonTap">使得输入框获取焦点</button>
  </view>
</view>
<view class="section">
  <form bind:submit="bindFormSubmit">
    <textarea placeholder="form 中的 textarea" name="textarea"/>
    <button form-type="submit"> 提交 </button>
  </form>
</view>
```

```javascript
//textarea.js
Page({
  data: {
    height: 20,
    focus: false
  },
  bindButtonTap: function() {
    this.setData({
      focus: true
    })
  },
  bindTextAreaBlur: function(e) {
    console.log(e.detail.value)
  },
  bindFormSubmit: function(e) {
    console.log(e.detail.value.textarea)
  }
})
```