Chameleon 模板内部校验机制解析:白名单标签、黑名单属性与事件变量一致性检查
Chameleon 模板内部校验机制解析:白名单标签、黑名单属性与事件变量一致性检查
导读
在 Chameleon(一套代码运行多端)的工程体系中,.cml 文件中的 <template> 既要支持 cml 与 vue 两套指令语法,又要适配 web / weex / wx 三种平台的标签能力,如何保证模板语法正确、避免运行时才发现"方法未定义"这类低级错误,是静态校验层要解决的核心问题。本文基于 chameleon-linter 的 模板内部校验说明文档,结合仓库源码与测试用例,完整拆解模板校验的两大体系:基于 htmllint 的标签白名单 / 属性黑名单语法校验,以及模板事件、变量与 script 定义的一致性语义校验。读完本文,你将能理解 Chameleon 模板校验的完整工作链路、各配置项的取值来源与生效方式,并能根据错误消息快速定位修复模板问题。
一、模板校验的整体架构:语法层 + 语义层两阶段
chameleon-linter 对模板的校验并非单次扫描完成,而是由两条独立链路协同工作:
- 语法校验(linter 层):以修改自 htmllint 的
cml-htmllinter为引擎,负责标签、属性、指令、内嵌结构等"写法是否合法"的检查; - 语义校验(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 白名单补充)
- cml 模板支持的标签(
- 三端平台对应的 native 标签:
- wx 小程序原生支持标签(
scroll-view、swiper、movable-view、icon、picker、map、web-view、official-account等小程序专属标签) - weex 原生支持的标签(
div、recycle-list、loading、refresh、slider、waterfall、web等 weex 专属标签) - web 原生支持标签(覆盖完整的 HTML 标签集合,从
a、div、p到video、canvas等)
- wx 小程序原生支持标签(
- 模板中通过
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 实现,由两种方式互补构成:
- 通过 htmllint 的
attr-bans直接添加禁止的属性列表:例如 cml 模板禁止v-if、v-show、v-for等 vue 指令。底层规则见 cml-htmllinter 的 attr-bans.js,凡属性名命中黑名单列表即报E062。 - 通过新增 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
- 变量名
- template
lang为cml:从属性值由{{}}给出的表达式中获取; - template
lang为vue:从v-if、v-show、v-else-if、v-model、:(v-bind)等直接绑定数据值的指令中获取。
- template
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 模板文件从进入校验到输出问题的完整链路可以概括为:
templatelint(linters/template.js)解析出 template part 的 AST,并校验<template>标签唯一性;- 依据平台(web / weex / wx)与
lang(cml / vue)组装校验选项(标签白名单、指令黑名单、正则、内置组件属性表、内嵌标签规则); cml-htmllinter逐规则执行语法检查,产出问题列表;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 接口校验;- 两类检查的问题按统一的消息结构(line / column / token / msg)合并输出。
六、相关资源
本文机制所依赖的核心项目与模块:
cml-htmllinter:基于 htmllint 修改的模板语法校验器,新增了tag-white-list、directive-name-forbiden、component-attr-check、tag-embed等规则(rules 目录);htmlparser2:htmllint 底层依赖的 HTML 解析器;- 白名单 / 黑名单数据源:config/white-list 目录(cml、vue、wx、weex、web 五份配置);
- 语义校验解析器:js-ast-parser.js(基于
cml-js-parser)、template-ast-parser 目录(基于htmlparser2的 AST 遍历)、json-ast-parser.js; - 完整测试用例:语法层见 test/template/linter/cases(fail 与 pass 两组),语义层见 test/template/checker/template.test.js。
说明:模板校验的
lang属性目前支持cml与vue两种取值,属性黑名单与指令互斥规则均围绕这两类指令展开;若模板未显式声明lang,校验默认按cml处理(见 linters/template.js 中part.params.lang || (part.params.lang = 'cml'))。