# Glass-easel Adaptation Guidelines

glass-easel is a new component framework, a rewrite of the old component framework_exparser, with **better performance and more features than the old component frame.

Migrating an existing Weixin Mini Program running on_exparser_to_glass-easel_requires some adaptation, and the following documentation provides some guidelines for adaptation.

# Operating environment

For ** _Skyline_Rendering Engine ** , version {% version ('3.0.0')%} From now on, the base library will run at full capacity on_glass-easel, so pages **must be compatible with_glass_easel to function properly (checked accordingly when uploaded);In versions below {% version ('3.0.0')%} of the base library or running environments that do not support_Skyline_, the page will run in compatibility mode on_exparser_.

The_WebView_backend does not support_glass-easel_(in progress), but the page can run in compatibility mode on_exparser_.

When debugging with the WeChat developer tools,glass-easel_requires a 1.06.2308142 or later tool;When the tool version does not support the use of_glass-easel, the base library breaks rendering and prompts for an upgrade.

During runtime, the routing log in_vConsole_can assist in identifying the component framework currently in use: AppRouteLog

# JSON configuration

Start the adaptation by adding the following configuration to the JSON configuration of the page or custom component:

{ "componentFramework": "glass-easel" }

Once added, the WXML template will be compiled into the new format_ProcGen_adapted to_glass-easel_while remaining compatible with the older component framework_exparser_.

When you add this configuration to a page or custom component, all of the components on which it depends will also be automatically marked as_glass-easel_adaptations (includingusingComponentsdependencies and [[]]componentGenerics # defaultdependent upon)

Add this configuration toapagejsonto globally enable_glass-easel_support.However, it should be noted that the template generated by compiling after configuration can also be run on_exparser_,However, compatible versions can encounter compatibility issues in boundary situations on_exparser_, so unless you don't need a compatible legacy repository or Weixin Mini Program as a whole runs in_Skyline_, you should use global configuration more carefully.

The plugin does not currently support thecomponentFrameworkconfiguration entry at the page or custom component level. You can start adaptation by adding this configuration entry inplugin.json.

# Change point adaptation

_glass-easel_is designed to be compatible with most of the older component framework_exparser_interfaces, with only a few changes needed:

[Must] Escapes outside the data binding in the template have been changed to standard XML escapes, escapes inside the data binding now need not be escaped

Compatibility: [Manual compatibility required] _exparser_New escape writing cannot be used

Old examples:

<view prop-a="\"test\"" prop-b="{{ test === \"test\" }}" />

新例：

<view prop-a="&quot;test&quot;" prop-b="{{ test === "test" }}" />

[必须] 模板中不再支持 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;
}
```
[可选] 由于兼容需要，wx.createSelectorQuery 性能不如 this.createSelectorQuery，应尽量使用后者
- 兼容性：[推荐直接变更] exparser 同样支持 this.createSelectorQuery
- 旧例：
```
wx.createSelectorQuery()
  .in(this)
  .select('#webgl')
  .exec(res => { })
```
- 新例：
```
this.createSelectorQuery()
  .select('#webgl')
  .exec(res => { })
```

[必须] 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"
/>

[正在支持] 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
2024-05-20 支持全空的数据绑定
- 重新预览或上传即可，无版本依赖
2024-10-18 支持在组件 JS 的 options 中定义 styleIsolation 和 addGlobalClass
- 需要基础库版本 3.6.3 或以上，后续争取兼容到版本 3.0.0
2024-10-28 支持 WXS 事件响应函数
- 需要基础库版本 3.6.4 或以上，后续争取兼容到版本 3.0.0