Chameleon 内置 textarea 组件指南:属性、事件与多端模板校验
Chameleon 内置 textarea 组件指南:属性、事件与多端模板校验
textarea 是 Chameleon(一套代码运行多端的跨端框架)内置的基础表单组件,用于多行文本输入。本文以其官方组件文档 textarea.md 为核心,逐项解析全部属性与事件的类型约定,并结合 chameleon-linter 的白名单、嵌套规则与模板校验源码,讲清楚它在 .cml 模板中的正确用法、各端兼容性限制,以及 lint 如何在编译前拦截非法属性、非法事件与非法嵌套,帮助你写出一次编写、多端可用的多行输入交互。
组件定位:textarea 在 Chameleon 内置组件体系中的角色
在 Chameleon 的 .cml 单文件组件中,模板部分直接使用内置组件标签(如 view、text、input、textarea 等),框架在编译时将其映射到 Web、Weex、微信小程序等不同平台的原生实现。textarea 与 input 同属表单输入类内置组件,二者接口几乎完全一致,核心差异在于 textarea 多出一个 rows 属性,用于控制多行输入的可视行数,这与 PC/移动端"多行文本框"的语义一致。
该组件的接口定义文档存放于 chameleon-linter 的内置组件文档目录 docs/components/buildin/,与 button、checkbox、input、list、page、radio、richtext、scroller、switch、video 等其余 10 个内置组件并列。从源码结构看,config/built-in-components/index.js 会读取当前工作区 node_modules/chameleon-ui-builtin/components 目录下的组件定义,通过 cml-component-parser 解析并生成组件名到接口内容的映射(getCml),供 lint 校验使用——这正是组件接口文档所描述的能力最终落地到校验器的方式。
属性(Props)详解
以下为 textarea 的完整属性表,直接继承自官方文档:
| 属性名 | 类型 | 说明 |
|---|---|---|
| value | String | 输入框的初始内容/受控值 |
| type | String | 输入类型(如文本、数字等,具体取值与 input 组件一致,由各端原生能力决定) |
| placeholder | String | 输入框为空时的占位提示文本 |
| disabled | Boolean | 是否禁用输入框 |
| focus | Boolean | 是否自动获得焦点 |
| maxlength | Number | 最大可输入字符长度 |
| returnKeyType | String | 键盘右下角返回键的类型(如 done、search、send 等,受各端支持范围限制) |
| placerHolderColor | String | 占位提示文本的颜色(注意文档中该字段拼写为 placerHolderColor,使用时需按此拼写) |
| inputStyle | String | 输入框的内联样式字符串 |
| rows | Number | 输入框可视行数,textarea 专属属性,input 组件无此项 |
相比 input 组件文档,textarea 唯一新增的属性即为 rows(Number 类型),其余 9 项属性与 input 完全同构,这说明 Chameleon 将单行输入与多行输入做成了两个独立的内置组件,而非用 type 属性切换。
从类型约定看,全部属性均为文档声明的显式类型(String / Boolean / Number)。在 cml 模板中这些属性同样遵循 Chameleon 的 c- 前缀指令体系,可配合 c-bind、c-model 等指令使用。以下是一个在 .cml 页面中使用 textarea 并双向同步数据的典型写法:
<template>
<view class="page">
<textarea
value="{{content}}"
placeholder="请输入多行内容"
maxlength="500"
rows="4"
disabled="{{disabled}}"
c-model="content"
c-bind:inputevent="onInput"
c-bind:blurevent="onBlur"
c-bind:focusevent="onFocus"
/>
</view>
</template>
<script>
export default {
data: {
content: '',
disabled: false
},
methods: {
onInput(event) {
// event.detail.value 为当前输入内容
console.log('input:', event.detail.value);
},
onBlur() {},
onFocus() {}
}
};
</script>
事件(Events)详解
textarea 共暴露 4 个事件,统一通过 c-bind: 前缀绑定。其中 inputevent 是唯一定义了返回参数的事件,其余三个事件"事件未定义返回参数",即触发时不携带可用的 eventDetail:
| 事件名(绑定写法) | 返回参数 | 说明 |
|---|---|---|
| c-bind:inputevent | eventDetail,类型为 inputEventDetail | 输入内容变化时触发,detail 携带最新输入值 |
| c-bind:blurevent | 无 | 输入框失去焦点时触发 |
| c-bind:focusevent | 无 | 输入框获得焦点时触发 |
| c-bind:confirmevent | 无 | 键盘确认/完成键按下时触发 |
inputEventDetail 的类型定义如下:
inputEventDetail = {
value: String
}
也就是说,在 inputevent 回调中通过 event.detail.value 即可拿到用户当前输入的多行文本。这一事件类型约定在仓库的接口文件中可以得到印证:cml-component-parser/test/docs/built-in-components/input/input.interface 中声明了 type inputEventDetail = { value: String },并为 blur/focus/confirm 定义了空 detail 类型:
type inputEventDetail = {
value: String
}
type blurEventDetail = {}
type focusEventDetail = {}
type confirEventDetail = {}
可见 textarea 与 input 共享同一套事件接口定义:只有输入事件携带 {value: String},其余事件均为空 detail。接口文件同时给出了 Chameleon 区分组件属性与事件的方式——事件以事件名为 key 声明为函数类型(如 inputevent(eventDetail: inputEventDetail): void),属性则声明为普通类型字段,这也是 lint 校验属性与事件合法性的依据。
内置组件白名单:textarea 的标签合法性校验
Chameleon 的模板 lint 会校验模板中出现的标签是否属于 CML 允许的内置标签。白名单定义在 config/white-list/cml-white-list.js,其中 textarea 与 view、text、input、video 等一同出现在 tags 数组中:
module.exports = {
attrs: ['c-if', 'c-else', 'c-else-if', 'c-for', 'c-for-index', 'c-for-item', 'c-model', 'c-text', 'c-show', 'c-bind', 'c-catch', 'c-key', 'c-animation'],
tags: [
'template', 'view', 'text', 'block', 'scroller', 'list', 'cell',
'image', 'switch', 'video', 'input', 'textarea', 'richtext',
'button', 'radio', 'checkbox', 'page', 'router-view', 'cover-view',
'slot', 'aside', 'col', 'container', 'foot', 'head', 'main',
'row', 'carousel', 'carousel-item', 'component'
]
};
白名单统一由 config/white-list/index.js 导出,其中 getAllowedTags() 直接返回 cml 白名单的 tags 数组,而 linters/template.js 会将其注入 cml-htmllinter 的 tag-only-allowed-names 等规则中。也就是说,在 cml 模板中使用 textarea 标签是合法的,但若误写为 textarea2 之类的非白名单标签,编译前 lint 便会直接报错。
嵌套规则:textarea 不能出现在 scroller / list 内部
textarea 除了标签合法性外,还受内置组件嵌套规则约束。规则定义在 config/tag-embed-rules.json:
{
"text": { "required": "", "excludes": "", "includes": ["text"] },
"scroller": { "required": "", "excludes": ["textarea","video"], "includes": "" },
"list": { "required": "", "excludes": ["textarea","video"], "includes": "" },
"video": { "required": "", "excludes": "", "includes": ["text"] }
}
规则含义如下:
- scroller:不能包含
textarea或video子组件; - list:不能包含
textarea或video子组件; - text:只能包含
text子组件(即 text 不能包裹 textarea); - video:若包含子组件,只能是
text。
对应的人工可读说明位于 docs/templates/template-functionalities.md,原文明确写着:"scroller 组件不能包含 textarea 或者 video 组件""list 组件不能包含 textarea 或者 video 组件"。嵌套违规时 lint 会给出如下形式的报错:
'tag "<%= parent %>" can not have "<%= forbiddenTag %>" as it\'s child elements, and element in this list: "<%= elements %>" is forbidden as well'
实战结论:如果你的多行输入区需要放在可滚动区域内,应把 textarea 直接放在页面根级 view 下,或选择不自带滚动能力的容器,避免触发嵌套校验报错。
属性与事件的深层校验:模板检查器如何工作
除了标签与嵌套规则,chameleon-linter 还会对内置/自定义组件上使用的属性(props)与事件(events)做合法性比对。核心实现位于 checkers/template/index.js 的 checkCustomizedComponents() 方法:
- 通过
jsonAstParser.getUsingComponents()从 .cml 的 json 配置块中解析已声明使用的组件及其接口; - 通过
templateAstParser.getParseResults()解析模板中每个组件上实际书写的属性和事件; - 将模板中出现的属性与接口声明的 props 做差集比对,若模板使用了接口中不存在的属性,报错:
The property "<propName>" is not a property of component "<componentName>" which path is: <componentPath>; - 将模板中绑定的事件与接口声明的事件(并集上 config/common-events.json 中的公共事件)做比对,若绑定了未定义的事件,报错:
The event "<eventName>" is not defined in component "<componentName>" which path is: <componentPath>。
同时 checkTemplateAndScript() 会校验模板中 c-bind 绑定的方法是否在 script 的 methods 中定义、模板引用的变量是否在 data 中定义,保证 c-bind:inputevent="onInput" 这类写法不会出现"绑定了但方法不存在"的运行时崩溃。这正是 textarea 文档中"属性表 + 事件表"成为 lint 校验事实依据的原因——文档里没列出的属性或事件,在代码中被使用时就会被拦截。
多端运行限制与平台原生支持
textarea 作为内置组件,最终会被编译为各端原生标签。根据 docs/templates/template-functionalities.md 中列出的平台原生支持标签:
- weex 平台原生支持标签包含
textarea(与input、text、richtext、video等同在列表中); - 微信小程序(wx)平台原生支持标签同样包含
textarea。
也就是说,textarea 在 Weex 端与微信小程序端均有原生对应实现,可在这些端直接使用。对于属性细节(如 type 的取值集合、returnKeyType 的按键类型、placerHolderColor 是否所有端都生效),需要以具体目标平台的实现为准,建议在真机上验证,因为 lint 只能保证语法与接口层面的合法性,无法替平台验证运行时行为。
小结:textarea 使用要点速查
- 属性上:textarea 与 input 的接口几乎一致,唯一新增的是
rows(Number,控制可视行数);注意占位符颜色属性的官方拼写是placerHolderColor。 - 事件上:4 个事件均通过
c-bind:绑定,仅inputevent携带{value: String}类型的 eventDetail,blur / focus / confirm 事件无返回参数。 - 嵌套上:textarea 不能作为 scroller、list 的子组件,也不能被 text 组件包裹;需要滚动时请将 textarea 置于独立容器中。
- 校验上:
textarea在 cml-white-list.js 的合法标签列表中;文档未声明的属性与事件会被 TemplateChecker 在编译前拦截报错。
按照以上约定编写 .cml 模板,即可让多行输入组件在 Web / Weex / 小程序等多端保持一致的行为边界,同时最大程度避免 lint 报错与运行期问题。