# glass-easel 适配指引

glass-easel 是一个新的组件框架，是对旧版组件框架 exparser 的一个重写，拥有 比旧版组件框架更好的性能和更多的特性。

将现有的运行在 exparser 上的小程序迁移到 glass-easel 需要一些适配，下面的文档会为适配提供一些指引。

# 运行环境

对于 Skyline 渲染引擎，版本 3.0.0 起的基础库将全量运行在 glass-easel 上，因此页面必须适配 glass-easel 才能正常运行（在上传时会有相应的检查）；在 3.0.0 以下版本基础库或不支持 Skyline 的运行环境中，页面将在 exparser 上以兼容模式运行。

WebView 后端暂不支持 glass-easel（进行中），但页面可以在 exparser 上以兼容模式运行。

使用微信开发者工具进行调试时，glass-easel 需要 1.06.2308142 或更高版本的工具；当工具版本不支持使用 glass-easel 时，基础库将中断渲染并提示升级。

在运行过程中，vConsole 内的路由日志可以协助确认当前正在使用的组件框架：

AppRouteLog

# 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="&quot;test&quot;" 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 兼容模式上时，不支持 WXSS input 标签选择器
- 兼容性：[推荐直接变更]
- 旧例：
```
input {
   height: 30px;
}
```
- 新例：
```
.my-input {
   height: 30px;
}
```
[必须] 自定义组件 JS 配置 options 中的 styleIsolation 改为在 JSON 中配置
- 兼容性：[推荐直接变更] exparser 同样会读取 JSON 中的 styleIsolation
- 旧例：
```
Component({
  options: {
    styleIsolation: 'isolated'
  }
})
```
- 新例：
```
{
  "component": true,
  "styleIsolation": "isolated"
}
```
[必须] 自定义组件 JS 配置 options 中的 addGlobalClass 改为在 JSON 中配置
- 兼容性：[推荐废弃] exparser 不会读取 JSON 中的 addGlobalClass，但 addGlobalClass 可以等价转换为对应的 styleIsolation 从而兼容：
  1. 由于当 styleIsolation 并非默认值时，addGlobalClass 无效，因此如果组件已经有 styleIsolation 配置项，直接去掉 addGlobalClass 即可
  2. 如果组件使用 Page({}) 进行注册，由于 Page({}) 拥有 styleIsolation: shared 默认值，因此 addGlobalClass 不会生效，去掉即可
  3. 区分自定义组件是否做为页面使用，按照下表将 addGlobalClass 转换为 styleIsolation：
    
    作为页面根节点不作为页面根节点
    
    addGlobalClass: true 无需添加（没有意义） styleIsolation: apply-shared
    
    addGlobalClass: false styleIsolation: shared styleIsolation: isolated
- 旧例：
```
Component({
  options: {
    addGlobalClass: true
  }
})
```
- 新例：
```
{
  "component": true,
  "styleIsolation": "apply-shared"
}
```
[可选] 由于兼容需要，wx.createSelectorQuery 性能不如 this.createSelectorQuery，应尽量使用后者
- 兼容性：[推荐直接变更] exparser 同样支持 this.createSelectorQuery
- 旧例：
```
wx.createSelectorQuery()
  .in(this)
  .select('#webgl')
  .exec(res => { })
```
- 新例：
```
this.createSelectorQuery()
  .select('#webgl')
  .exec(res => { })
```

	作为页面根节点	不作为页面根节点
`addGlobalClass: true`	无需添加（没有意义）	`styleIsolation: apply-shared`
`addGlobalClass: false`	`styleIsolation: shared`	`styleIsolation: isolated`

[必须] SelectorQuery 等接口中的选择器现在和 CSS 选择器一样，不再支持以数字开头

兼容性：[推荐直接变更]

旧例：

this.createSelectorQuery()
  .select('#1')
  .exec(res => { })

新例：

this.createSelectorQuery()
  .select('#element-1')
  .exec(res => { })

[必须] Skyline 渲染后端上的 Worklet 回调函数名称变更

兼容性：[推荐直接变更] 旧版本基础库同样支持这些事件名称

变更对应：

组件名	原 Worklet 事件名	新 Worklet 事件名
pan-gesture-handler	`on-gesture-event`	`worklet:ongesture`
pan-gesture-handler	`should-response-on-move`	`worklet:should-response-on-move`
pan-gesture-handler	`should-accept-gesture`	`worklet:should-accept-gesture`
scroll-view	`bind:scroll-start`	`worklet:onscrollstart`
scroll-view	`bind:scroll`	`worklet:onscrollupdate`
scroll-view	`bind:scroll-end`	`worklet:onscrollend`
scroll-view	`adjust-deceleration-velocity`	`worklet:adjust-deceleration-velocity`
swiper	`bind:transition` `bind:animationfinish`	`worklet:onscrollstart` `worklet:onscrollupdate` `worklet:onscrollend`
share-element	`on-frame`	`worklet:onframe`

旧例：

<scroll-view bindscroll="onScrollWorklet" />
<swiper bind:transition="onTransitionWorklet" />

新例：

<scroll-view worklet:onscrollupdate="onScrollWorklet" />
<swiper
   worklet:onscrollstart="onTransitionWorklet"
   worklet:onscrollupdate="onTransitionWorklet"
   worklet:onscrollend="onTransitionWorklet"
/>

[正在支持] 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]
- 重新预览或上传即可，无版本依赖
2023-07-28 支持兼容模式下 WXS 事件响应中 ComponentDescriptor 的 getState 方法
- 需要基础库版本 3.0.0 或以上，正在逐步支持到版本 2.19.2