新版组件框架适配指引
# glass-easel 适配指引
glass-easel 是一个新的组件框架,是对旧版组件框架 exparser 的一个重写,拥有比旧版组件框架更好的性能和更多的特性。
Skyline 后端将全量改为 glass-easel 框架,目前的 Skyline 小程序需要进行一些适配,下面的文档会为适配提供一些指引;WebView 后端暂不支持 glass-easel,支持工作仍在进行中。
# 测试环境
支持 glass-easel 的基础库尚未发布(近期发布),目前所有支持 Skyline 渲染引擎的基础库(2.29.2 及以上)均支持在 exparser 上以兼容模式运行 glass-easel 适配的小程序。
开发者工具的支持工作正在进行中,目前可以在真机上进行适配。
# JSON 配置
通过在页面或自定义组件的 JSON 配置中添加以下配置开始适配:
{ "componentFramework": "glass-easel" }
添加后,WXML 模板将被编译为适配 glass-easel 的新格式 ProcGen,并同时保持对旧版组件框架 exparser 兼容。
为一个页面或自定义组件添加这个配置后,所有它依赖的组件也将自动被标记为 glass-easel 适配(包括 usingComponents
依赖和 componentGenerics#default
依赖)
在 app.json
中添加这个配置可以全局开启 glass-easel 支持。但需要注意的是,配置后编译生成的模板虽然也能在 exparser 上运行,但兼容版本在 exparser 上有可能遇到边界情况下的兼容性问题,因此除非不需要兼容旧版本基础库或者小程序整体都以 Skyline 运行,否则应该更谨慎地使用全局配置。
插件暂未支持页面或自定义组件级别的 componentFramework
配置项,可以在 plugin.json
中添加这个配置项来开始适配。
# 变更点适配
glass-easel 在设计上兼容绝大多数的旧版组件框架 exparser 的接口,仅有少数地方需要变更:
[必须] 模板中数据绑定外的转义改为标准 XML 转义,数据绑定内的转义现在无需转义
- 兼容性:[需要手动兼容] exparser 上不能使用新的转义写法
- 旧例:
<view prop-a="\"test\"" prop-b="{{ test === \"test\" }}" />
- 新例:
<view prop-a=""test"" prop-b="{{ test === "test" }}" />
[必须] 模板不再支持全空的数据绑定
- 兼容性:[推荐直接变更] 全空的数据绑定求值结果为空字符串,直接去掉即可
- 旧例:
<view prop="{{}}">{{ }}</view>
- 新例:
<view prop=""></view>
[必须] 模板中不再支持
wx-if
,wx-for
两种写法,仅支持wx:if
,wx:for
- 兼容性:[推荐直接变更] exparser 同样可以使用
wx:if
,wx:for
- 旧例:
<view wx-if="{{ arr }}" />
- 新例:
<view wx:if="{{ arr }}" />
- 兼容性:[推荐直接变更] exparser 同样可以使用
[必须] 运行在 exparser 兼容模式上时,不支持 WXSS
input
标签选择器- 兼容性:[推荐直接变更]
- 旧例:
input { height: 30px; }
- 新例:
.my-input { height: 30px; }
[必须] 自定义组件 JS 配置
options
中的styleIsolation
改为在 JSON 中配置- 兼容性:[推荐直接变更] exparser 同样会读取 JSON 中的
styleIsolation
- 旧例:
Component({ options: { styleIsolation: 'isolated' } })
- 新例:
{ "component": true, "styleIsolation": "isolated" }
- 兼容性:[推荐直接变更] exparser 同样会读取 JSON 中的
[必须] 自定义组件 JS 配置
options
中的addGlobalClass
改为在 JSON 中配置- 兼容性:[推荐废弃] exparser 不会读取 JSON 中的
addGlobalClass
,但addGlobalClass
可以等价转换为对应的styleIsolation
从而兼容:由于当
styleIsolation
并非默认值时,addGlobalClass
无效,因此如果组件已经有styleIsolation
配置项,直接去掉addGlobalClass
即可如果组件使用
Page({})
进行注册,由于Page({})
拥有styleIsolation: shared
默认值,因此addGlobalClass
不会生效,去掉即可区分自定义组件是否做为页面使用,按照下表将
addGlobalClass
转换为styleIsolation
:
- 旧例:
Component({ options: { addGlobalClass: true } })
- 新例:
{ "component": true, "styleIsolation": "apply-shared" }
- 兼容性:[推荐废弃] exparser 不会读取 JSON 中的
[可选] 由于兼容需要,
wx.createSelectorQuery
性能不如this.createSelectorQuery
,应尽量使用后者- 兼容性:[推荐直接变更] exparser 同样支持
this.createSelectorQuery
- 旧例:
wx.createSelectorQuery() .in(this) .select('#webgl') .exec(res => { })
- 新例:
this.createSelectorQuery() .select('#webgl') .exec(res => { })
- 兼容性:[推荐直接变更] exparser 同样支持
[必须] Skyline 渲染后端上的 Worklet 回调函数名称变更
兼容性:[推荐直接变更] 旧版本基础库同样支持这些事件名称
变更对应:
旧例:
<scroll-view bindscroll="onScrollWorklet" /> <swiper bind:transition="onTransitionWorklet" />
新例:
<scroll-view worklet:onscrollupdate="onScrollWorklet" /> <swiper worklet:onscrollstart="onTransitionWorklet" worklet:onscrollupdate="onTransitionWorklet" worklet:onscrollend="onTransitionWorklet" />
[正在支持] 兼容模式下,暂不支持 WXS 事件响应中
ComponentDescriptor
的getState
方法[正在支持] glass-easel 下,暂不支持 WXS 事件响应
[正在支持] Skyline 渲染后端上,IntersectionObserver 暂不支持
relativeTo
, 仅支持relativeToViewport
[正在支持] 暂不支持以下组件实例方法:
animate
applyAnimation
clearAnimation
setInitialRenderingCache
# 已知问题
- 运行在
exparser
兼容模式上时,text
组件无法换行
# 更新记录
2023-06-01
支持 WXS- 重新预览或上传即可,无版本依赖
2023-06-02
修复 嵌套的wx:for
可能导致异常 [wechat-miniprogram/glass-easel#45]- 重新预览或上传即可,无版本依赖
2023-06-02
修复<template name>
中使用的 WXS 在引用到其他文件中时可能失效 [wechat-miniprogram/glass-easel#47]- 重新预览或上传即可,无版本依赖
2023-06-12
修复<template>
,<include>
,<slot>
节点上不支持wx:
指令 [wechat-miniprogram/glass-easel#30]- 重新预览或上传即可,无版本依赖