# glass-easel 適配指引

glass-easel 是一個(gè)新的組件框架，是對(duì)舊版組件框架 exparser 的一個(gè)重寫，擁有 比舊版組件框架更好的性能和更多的特性。

將現(xiàn)有的運(yùn)行在 exparser 上的小程序遷移到 glass-easel 需要一些適配，下面的文檔會(huì)為適配提供一些指引。

# 運(yùn)行環(huán)境

對(duì)于 Skyline 渲染引擎，版本 3.0.0 起的基礎(chǔ)庫將全量運(yùn)行在 glass-easel 上，因此頁面必須適配 glass-easel 才能正常運(yùn)行（在上傳時(shí)會(huì)有相應(yīng)的檢查）；在 3.0.0 以下版本基礎(chǔ)庫或不支持 Skyline 的運(yùn)行環(huán)境中，頁面將在 exparser 上以兼容模式運(yùn)行。

WebView 后端暫不支持 glass-easel（進(jìn)行中），但頁面可以在 exparser 上以兼容模式運(yùn)行。

使用微信開發(fā)者工具進(jìn)行調(diào)試時(shí)，glass-easel 需要 1.06.2308142 或更高版本的工具；當(dāng)工具版本不支持使用 glass-easel 時(shí)，基礎(chǔ)庫將中斷渲染并提示升級(jí)。

在運(yùn)行過程中，vConsole 內(nèi)的路由日志可以協(xié)助確認(rèn)當(dāng)前正在使用的組件框架：

AppRouteLog

# JSON 配置

通過在頁面或自定義組件的 JSON 配置中添加以下配置開始適配：

{ "componentFramework": "glass-easel" }

添加后，WXML 模板將被編譯為適配 glass-easel 的新格式 ProcGen，并同時(shí)保持對(duì)舊版組件框架 exparser 兼容。

為一個(gè)頁面或自定義組件添加這個(gè)配置后，所有它依賴的組件也將自動(dòng)被標(biāo)記為 glass-easel 適配（包括 usingComponents 依賴和 componentGenerics#default 依賴）

在 app.json 中添加這個(gè)配置可以全局開啟 glass-easel 支持。但需要注意的是，配置后編譯生成的模板雖然也能在 exparser 上運(yùn)行，但兼容版本在 exparser 上有可能遇到邊界情況下的兼容性問題，因此除非不需要兼容舊版本基礎(chǔ)庫或者小程序整體都以 Skyline 運(yùn)行，否則應(yīng)該更謹(jǐn)慎地使用全局配置。

插件暫未支持頁面或自定義組件級(jí)別的 componentFramework 配置項(xiàng)，可以在 plugin.json 中添加這個(gè)配置項(xiàng)來開始適配。

# 變更點(diǎn)適配

glass-easel 在設(shè)計(jì)上兼容絕大多數(shù)的舊版組件框架 exparser 的接口，僅有少數(shù)地方需要變更：

[必須] 模板中數(shù)據(jù)綁定外的轉(zhuǎn)義改為標(biāo)準(zhǔn) XML 轉(zhuǎn)義，數(shù)據(jù)綁定內(nèi)的轉(zhuǎn)義現(xiàn)在無需轉(zhuǎn)義
- 兼容性：[需要手動(dòng)兼容] exparser 上不能使用新的轉(zhuǎn)義寫法
- 舊例：
```
<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 }}" />
```
[必須] 運(yùn)行在 exparser 兼容模式上時(shí)，不支持 WXSS input 標(biāo)簽選擇器
- 兼容性：[推薦直接變更]
- 舊例：
```
input {
   height: 30px;
}
```
- 新例：
```
.my-input {
   height: 30px;
}
```
[可選] 由于兼容需要，wx.createSelectorQuery 性能不如 this.createSelectorQuery，應(yīng)盡量使用后者
- 兼容性：[推薦直接變更] exparser 同樣支持 this.createSelectorQuery
- 舊例：
```
wx.createSelectorQuery()
  .in(this)
  .select('#webgl')
  .exec(res => { })
```
- 新例：
```
this.createSelectorQuery()
  .select('#webgl')
  .exec(res => { })
```
[必須] SelectorQuery 等接口中的選擇器現(xiàn)在和 CSS 選擇器一樣，不再支持以數(shù)字開頭
- 兼容性：[推薦直接變更]
- 舊例：
```
this.createSelectorQuery()
  .select('#1')
  .exec(res => { })
```
- 新例：
```
this.createSelectorQuery()
  .select('#element-1')
  .exec(res => { })
```

[必須] Skyline 渲染后端上的 Worklet 回調(diào)函數(shù)名稱變更

兼容性：[推薦直接變更] 舊版本基礎(chǔ)庫同樣支持這些事件名稱

變更對(duì)應(yīng)：

組件名	原 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
[正在支持] 暫不支持以下組件實(shí)例方法：
- animate
- applyAnimation
- clearAnimation
- setInitialRenderingCache

# 已知問題

運(yùn)行在 exparser 兼容模式上時(shí)，text 組件無法換行

# 更新記錄