Chameleon 模板内部校验机制解析:白名单标签、黑名单属性与事件变量一致性检查

原创2026-10-07 20:22:221,899 阅读
文章标签:前端构建跨平台前端小程序构建工具Web框架

Chameleon 模板内部校验机制解析:白名单标签、黑名单属性与事件变量一致性检查

导读

在 Chameleon(一套代码运行多端)的工程体系中,.cml 文件中的 <template> 既要支持 cml 与 vue 两套指令语法,又要适配 web / weex / wx 三种平台的标签能力,如何保证模板语法正确、避免运行时才发现"方法未定义"这类低级错误,是静态校验层要解决的核心问题。本文基于 chameleon-linter 的 模板内部校验说明文档,结合仓库源码与测试用例,完整拆解模板校验的两大体系:基于 htmllint 的标签白名单 / 属性黑名单语法校验,以及模板事件、变量与 script 定义的一致性语义校验。读完本文,你将能理解 Chameleon 模板校验的完整工作链路、各配置项的取值来源与生效方式,并能根据错误消息快速定位修复模板问题。

一、模板校验的整体架构:语法层 + 语义层两阶段

chameleon-linter 对模板的校验并非单次扫描完成,而是由两条独立链路协同工作:

  1. 语法校验(linter 层):以修改自 htmllint 的 cml-htmllinter 为引擎,负责标签、属性、指令、内嵌结构等"写法是否合法"的检查;
  2. 语义校验(checker 层):基于 AST 解析,负责"模板里用到的方法/变量在 script 中是否真实定义"、以及"自定义组件上使用的 props/events 是否在组件接口中声明"的检查。

两条链路的入口分别位于 linters/template.js(语法层,templatelint)与 checkers/template/index.js(语义层,TemplateChecker)。后者在构造时会同时消费 template、script、json 三部分的 AST,并将校验结果合并输出。

下面先看语法层。

二、标签校验:白名单机制

2.1 白名单的组成

标签校验采用白名单机制:模板中出现的标签必须位于给定的标签列表内,否则报错。校验代码入口为 linters/template.js(其 getLintOptions 函数负责拼装全部校验选项),底层规则实现见 cml-htmllinter 的 tag-white-list.js(新增 ruler tag-white-list,配置项 tag-only-allowed-names,凡是标签名不在列表中的即产生 E061 问题)。

白名单由三部分组成:

  • cml / vue 模板语言自身支持的标签:
    • cml 模板支持的标签(template、view、text、block、scroller、list、cell、image、switch、video、input、textarea、richtext、button、radio、checkbox、page、router-view、cover-view、slot 等)
    • vue 模板支持的标签(只包含"非 HTML 标签"集合,如 view、scroller、cell、router-view 等,其余 HTML 标签由 web 白名单补充)
  • 三端平台对应的 native 标签:
  • 模板中通过 usingComponents 配置引入的自定义标签:这类标签由 json 部分的 usingComponents 声明动态加入白名单。

2.2 白名单获取规则(按平台 × 语言组合)

白名单不是固定的,而是按当前组件对应的三端模板文件和 template 的 lang 属性组合而成。假设当前组件名为 index,三端模板文件分别为 index.web.cml、index.weex.cml、index.wx.cml,则对应三端的白名单构成如下:

模板文件 lang 为 cml lang 为 vue
index.web.cml cml 支持的标签 + 模板中自定义标签 + web 原生支持的标签 vue 支持的标签 + 模板中自定义标签 + web 原生支持的标签
index.weex.cml cml 支持的标签 + 模板中自定义标签 + weex 原生支持的标签 vue 支持的标签 + 模板中自定义标签 + weex 原生支持的标签
index.wx.cml cml 支持的标签 + 模板中自定义标签 + wx 原生支持的标签 vue 支持的标签 + 模板中自定义标签 + wx 原生支持的标签

源码中的支撑逻辑:getLintOptions 将 tag-only-allowed-names 赋值为 config/white-list/index.js 中 getAllowedTags()(返回 cml.tags)与 params.custimizedTags(即 getCustimizedTags 从 json AST 的 base.usingComponents 与平台级 usingComponents 中解析出的自定义组件名)拼接的结果。自定义组件名会经过 utils.js 的 toDash 转换为短横线命名。

2.3 使用方法

tag-white-list 规则的使用方式非常简单:向 htmllint 传入配置项 tag-only-allowed-names,值为允许的标签名数组即可:

const options = {
  'tag-only-allowed-names': ['view', 'template', 'text', 'block', 'scroller', /* ... */]
};

2.4 平台专属标签的校验验证

测试用例 platform-specific-tags-error.js 展示了白名单的跨平台约束:同样的 <scroll-view>,当 platformType 为 cml 时(即不在任何端上),报出 tag: "scroll-view" is either not allowed in this template or not referenced as a component;而当 platformType 为 wx 时(见 platform-specific-tags-pass.js),同一段模板则校验通过。这直观印证了"三端白名单按平台动态组装"的设计。

三、属性校验:黑名单机制

3.1 两种校验方式

属性校验采用黑名单机制,同样是基于 htmllint 实现,由两种方式互补构成:

  1. 通过 htmllint 的 attr-bans 直接添加禁止的属性列表:例如 cml 模板禁止 v-if、v-show、v-for 等 vue 指令。底层规则见 cml-htmllinter 的 attr-bans.js,凡属性名命中黑名单列表即报 E062。
  2. 通过新增 ruler 配合正则表达式匹配禁止的指令:文档中描述的新增 ruler 用于匹配"事件绑定类、属性绑定类"指令(如 cml 模板禁止 v-bind:src、:src、v-on:click、@click)。在仓库的实际实现中,这一职责由 directive-name-forbiden.js 承担,其配置项为 directive-name-forbidden-regex,凡属性名命中该正则即报 E062,并附带 directive 与 template-lang 信息。

这两种方式本可以通过把 attr-bans 的列表与正则表达式合并为一个表达式来统一实现,但为了语义清晰,目前采用两种方式并存互补的形式:精确的指令名用列表(attr-bans),需要模式匹配的绑定类指令用正则(directive-name-forbidden-regex)。

3.2 黑名单获取规则:cml 与 vue 指令互斥

目前需要校验的只有两类指令:cml 指令与类 vue 指令。规则为:

  • 校验 lang 为 cml 的模板时,要求模板里不能出现 vue 的指令;
  • 校验 lang 为 vue 的模板时,不能出现 cml 的指令。

源码中,config/white-list/index.js 的 getForbiddenAttrsByLang(lang) 实现了这一交叉逻辑:lang === 'cml' 时返回 vue.attrs(v-if、v-else、v-else-if、v-for、v-on、v-bind、v-html、v-show、v-model、v-pre、v-once、slot-scope),反之返回 cml.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)。

在 linters/template.js 中,对应指令的互斥由 directive-name-forbidden-regex 实现:

  • lang 为 vue 时:/^(c-(?:bind|catch)(?!\w))/ —— 禁止 cml 的 c-bind、c-catch 指令;
  • lang 为 cml(其他情况)时:/^((?:v-(?:bind|on|once)(?!\w))|:|@)/ —— 禁止 vue 的 v-bind、v-on、v-once 以及 :、@ 绑定语法。

3.3 使用方法

使用 attr-bans 配置指令黑名单,用 attr-name-forbidden-regex(实现中的 directive-name-forbidden-regex)传入匹配非法指令的正则表达式,具体配置组装参见 linters/template.js。

测试用例给出了非常直观的互斥效果:

  • directive-cml-error.js:lang='cml' 的模板中写 <view v-if='{{true}}' v-bind:onclick='onClick'>,分别报出 directive "v-if" is not allowed to be used in this template, as the template language is set to "cml" 与 directive "v-bind" is not allowed...;
  • directive-vue-error.js:lang='vue' 的模板中写 <view c-if='{{true}}' c-bind:onclick='onClick'>,同样报出 cml 指令被禁止的错误。

3.4 内置组件的属性 / 事件白名单校验(源码补充)

除标签与指令外,语法层还会对内置于 cml 的内置组件(chameleon-ui-builtin)做属性与事件的白名单校验,相关逻辑在 cml-htmllinter 的 component-attr-check.js 中:

  • component-allow-attr:由 config/built-in-components/index.js 从 node_modules/chameleon-ui-builtin/components 解析出各内置组件声明的 props 与 events;
  • component-event-regex:cml 模板为 /(?:c-bind:|c-catch:)(\w+)/,vue 模板为 /(?:v-on:|v-once:|@)(\w+)/;
  • component-prop-regex:仅 vue 模板启用,为 /(?:v-bind:|:)((?:\w|-)+)/,cml 模板为 false。

测试用例 built-in-props-error.js 演示了给 <button> 传未声明的 close-type 属性与 up 事件时分别报错;built-in-props-lang-vue-pass.js 则验证了 vue 语法下 :text、:size、v-on:onclick 等合法写法通过校验。

3.5 内嵌标签规则(源码补充)

语法层还通过 tag-embed.js(配置项 tag-embed-tags)校验标签的嵌套结构,规则定义见 tag-embed-rules.json:

  • text 只能包含 text(includes);
  • scroller、list 不允许直接或间接包含 textarea、video(excludes);
  • video 内只允许 text。

测试用例 built-in-embed-rule-excludes-error.js 验证了在 <scroller> 中嵌入 <textarea> 会报错。

3.6 模板标签唯一性(源码补充)

在正式进入 htmllint 前,linters/template.js 还会检查模板中 <template> 标签的数量,要求只能有一组,否则报出 Each template can only have one group of template tags。对应测试见 template-tag-error.js。

四、模板事件与模板变量校验

4.1 校验规则

语法层保证"写法正确",语义层则保证"引用正确":模板里使用的事件方法和变量名,必须在 script 的 class 中有相应定义。同时,自定义组件(通过 usingComponents 引入)上使用的属性与事件,也必须在该组件的接口声明中存在。

4.2 script class 定义的方法名与变量名获取

script 一侧的提取实现在 js-ast-parser.js,它内部调用 cml-js-parser 包提供的 CmlJsAstTreeParser 完成 script AST 解析:

  • 方法名:从 class 定义中的 methods 属性提取;
  • 变量名:从 class 定义中的 props、data、computed 属性中提取。

测试 template-lib-js.test.js 给出了预期结果:例如 class 写法下提取出的 vars 为 ['show', 'dataOne', 'computedOne', 'computedTwo']、methods 为 ['onTap', 'onClick'];export 写法(export default {})下则额外包含 computed 的 getter 名。

4.3 template 模板中方法名与变量名获取

template 一侧的提取实现在 template-ast-parser 目录。它的 getParseResults 接收模板 AST 与 usingComponents,先根据根标签的 lang 属性(支持 cml / vue,见 options.js)确定解析语言,再通过 AST 遍历(ast-tree-traversal.js)与两个 dispatcher 收集结果,最终返回 { vars, methods, customizedComponents }。

提取规则按语言区分:

  • 方法名
    • template lang 为 cml:从 c-bind、c-catch 指令对应的属性值获取;
    • template lang 为 vue:从 v-on、v-once、@ 指令对应的属性值获取。
  • 变量名
    • template lang 为 cml:从属性值由 {{}} 给出的表达式中获取;
    • template lang 为 vue:从 v-if、v-show、v-else-if、v-model、:(v-bind)等直接绑定数据值的指令中获取。

4.4 一致性比对与错误输出

比对逻辑集中在 checkers/template/index.js 的 TemplateChecker 中,它汇总了 json(json-ast-parser.js 解析 usingComponents)、script、template 三方的解析结果,提供两个检查入口:

  • checkTemplateAndScript():遍历模板提取出的 methods,若在 script 的 methods 中找不到同名定义,报出 method: "xxx" is not defined.;遍历模板提取出的 vars,若在 script 的 vars(props/data/computed)中找不到,报出 variable: "xxx" is not defined.。
  • checkCustomizedComponents():对于 usingComponents 引入的 cml 组件(isCml 为 true),比对模板中该组件上使用的 props/events 与组件接口声明的 props/events,未声明则分别报出 The property "xxx" is not a property of component "yyy" which path is: ... 与 The event "xxx" is not defined in component "yyy" which path is: ...。其中事件白名单还会叠加 common-events.json 中的公共事件(tap、click、touchstart、touchmove、touchend)。

对应的集成测试见 template.test.js:它分别以 cml 与 vue 两种模板语言跑通"变量/方法未定义"与"自定义组件 props/events 未定义"两组断言,错误信息(行号、列号、token、msg)与上述输出格式完全一致,是理解本文所述机制最直接的运行样例。

五、校验链路小结

综合以上分析,一个 .cml 模板文件从进入校验到输出问题的完整链路可以概括为:

  1. templatelint(linters/template.js)解析出 template part 的 AST,并校验 <template> 标签唯一性;
  2. 依据平台(web / weex / wx)与 lang(cml / vue)组装校验选项(标签白名单、指令黑名单、正则、内置组件属性表、内嵌标签规则);
  3. cml-htmllinter 逐规则执行语法检查,产出问题列表;
  4. TemplateChecker(checkers/template/index.js)消费 template / script / json 三部分 AST,分别从 script(methods、props、data、computed)与 template(c-bind、c-catch、v-on、v-once、@、{{}} 等)提取定义与引用,完成方法与变量的一致性比对,并对自定义组件做 props/events 接口校验;
  5. 两类检查的问题按统一的消息结构(line / column / token / msg)合并输出。

六、相关资源

本文机制所依赖的核心项目与模块:

说明:模板校验的 lang 属性目前支持 cml 与 vue 两种取值,属性黑名单与指令互斥规则均围绕这两类指令展开;若模板未显式声明 lang,校验默认按 cml 处理(见 linters/template.js 中 part.params.lang || (part.params.lang = 'cml'))。

登录后查看全文
chameleon