Chameleon 内置 textarea 组件指南:属性、事件与多端模板校验

原创2026-10-07 13:23:201,747 阅读
文章标签:前端构建跨平台前端小程序构建工具Web框架

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 使用要点速查

  1. 属性上:textarea 与 input 的接口几乎一致,唯一新增的是 rows(Number,控制可视行数);注意占位符颜色属性的官方拼写是 placerHolderColor。
  2. 事件上:4 个事件均通过 c-bind: 绑定,仅 inputevent 携带 {value: String} 类型的 eventDetail,blur / focus / confirm 事件无返回参数。
  3. 嵌套上:textarea 不能作为 scroller、list 的子组件,也不能被 text 组件包裹;需要滚动时请将 textarea 置于独立容器中。
  4. 校验上:textarea 在 cml-white-list.js 的合法标签列表中;文档未声明的属性与事件会被 TemplateChecker 在编译前拦截报错。

按照以上约定编写 .cml 模板,即可让多行输入组件在 Web / Weex / 小程序等多端保持一致的行为边界,同时最大程度避免 lint 报错与运行期问题。

登录后查看全文
chameleon