# glass-easel Adaptation guidelines

[glass-easel](https://github.com/WeChat mini-program /glass-easel) Is a new component framework that is a revision of the old component framework _exparser _ Of a rewrite, owned by Better performance and more features than older component frameworks。

The existing operation in the _exparser _ The Mini Program on the glass-easel Some adaptations are required, and the following documentation provides some guidelines for adaptations.

# Operating environment

for Skyline Rendering engine, Version 3.0.0 The base library will run the full amount on the glass-easel On this page. Must adaptation glass-easel In order to function properly (there will be a corresponding check at the time of upload)in 3.0.0 The following versions base library or not supported Skyline Of the running environment, the page will be in the _exparser _ Run in compatibility mode.

WebView Back end not supported glass-easel(in progress), but the page can be found in the _exparser _ Run in compatibility mode.

When debugging with the WeChat developer tool,glass-easel Need 1.06.2308142 Or a later version of the toolWhen the tool version does not support the use of glass-easel The base library interrupts rendering and prompts for upgrade.

During operation,vConsole The routing log in the API can assist in identifying the component framework currently in use:

AppRouteLog

# JSON To configure

By creating a page or custom component's JSON Add the following configuration to the configuration to start the adaptation:

{ "componentFramework": "glass-easel" }

When added, the WXML The template will be compiled to adaptation glass-easel The new format of ProcGen, and at the same time maintain an understanding of the older component framework _exparser _ Compatible.

When you add this configuration for a page or custom component, all its dependent components will also be automatically marked as glass-easel Adaptation (including usingComponents Dependence and componentGenerics#default Dependent)

in app.json Add this configuration to the glass-easel Support. However, it should be noted that the template generated after the configuration is compiled can also be _exparser _ Runs on, but the compatible version is available in _exparser _ It is possible to run into compatibility issues in boundary conditions on the API, so unless you do not need to be compatible with older versions of the base library or the Mini Program as a whole Skyline Run, otherwise you should use global configuration more carefully.

The plug-in does not support page or custom component level componentFramework Configuration items, which can be found in plugin.json To start the adaptation by adding this configuration item in.

# Change point adaptation

glass-easel Designed to be compatible with most older component frameworks _exparser _ There are only a few areas that need to be changed:

[Must] The escape outside the data binding in the template is changed to standard XML Escape, the escape within the data binding is now unescaped
- Compatibility:[Requires manual compatibility] _exparser _ You cannot use new escapes on
- Old Example:
```
<view prop-a=""test"" prop-b=  test === "test" }}" />
```
- New example:
```
<view prop-a=" test" " prop-b=  test === "test" }}" />
```
[Must] No longer supported in templates wx-if, wx-for Both types are supported. wx:if, wx:for
- Compatibility:[Recommend Direct Change] _exparser _ The same can be used wx:if, wx:for
- Old Example:
```
<view wx-if="{{ arr }}" />
```
- New example:
```
<view wx:if="{{ arr }}" />
```
[Must] Running in the _exparser _ Compatibility mode is not supported WXSS input Tag Selector
- Compatibility:[Recommend Direct Change]
- Old Example:
```
input {
   height: 30px
}
```
- New example:
```
.my-input {
   height: 30px
}
```
[Must] Custom Components JS To configure options to hit the target styleIsolation To read in the JSON In Configuration
- Compatibility:[Recommend Direct Change] _exparser _ Will also read JSON to hit the target styleIsolation
- Old Example:
```
Component({
  options: {
    styleIsolation: 'isolated'
  }
})
```
- New example:
```
{
  "component": true,
  "styleIsolation": "isolated"
}
```
[Must] Custom Components JS To configure options to hit the target addGlobalClass To read in the JSON In Configuration
- Compatibility:[Recommended Abandoned] _exparser _ Will not read JSON to hit the target addGlobalClass, but addGlobalClass Can be converted equivalent to a corresponding styleIsolation Thus compatible with:
  1. Because when styleIsolation Is not the default value,addGlobalClass Invalid, so if the component already has styleIsolation Configuration item, just remove the addGlobalClass can then
  2. If the component uses Page({}) For registration, because Page({}) have styleIsolation: shared Default value. Therefore, addGlobalClass It will not work, remove it.
  3. Distinguish whether a custom component is used as a page, according to the following table addGlobalClass Converted to styleIsolation：
    
    As the page root node Not as a page root node
    
    addGlobalClass: true No need to add (no point) styleIsolation: apply-shared
    
    addGlobalClass: false styleIsolation: shared styleIsolation: isolated
- Old Example:
```
Component({
  options: {
    addGlobalClass:  true
  }
})
```
- New example:
```
{
  "component": true,
  "styleIsolation": "apply-shared"
}
```
[available] Due to compatibility requirements,wx.createSelectorQuery Performance is not as good as this.createSelectorQueryThe latter should be used as much as possible.
- Compatibility:[Recommend Direct Change] _exparser _ The same support this.createSelectorQuery
- Old Example:
```
wx.createSelectorQuery()
  .in(this)
  .select('#Webgl )
  .exec(res => { })
```
- New example:
```
this.createSelectorQuery()
  .select('#Webgl )
  .exec(res => { })
```
[Must] SelectorQuery Etc. The selector in the interface is now associated with the CSS Selector, no longer supports starting with a number
- Compatibility:[Recommend Direct Change]
- Old Example:
```
this.createSelectorQuery()
  .select('#1')
  .exec(res => { })
```
- New example:
```
this.createSelectorQuery()
  .select('#element-1')
  .exec(res => { })
```

	As the page root node	Not as a page root node
`addGlobalClass: true`	No need to add (no point)	`styleIsolation: apply-shared`
`addGlobalClass: false`	`styleIsolation: shared`	`styleIsolation: isolated`

[Must] Skyline On the rendering backend Worklet Callback function name change

Compatibility:[Recommend Direct Change] Older versions of the base library also support these event names

The change corresponds to:

Component name	primary Worklet Name of event	new Worklet Name of event
[pan-gesture-handler ]((skyline/gesture#Common attributes ))	`on-gesture-event`	`worklet:ongesture`
[pan-gesture-handler ]((skyline/gesture#Common attributes ))	`should-response-on-move`	`worklet:should-response-on-move`
[pan-gesture-handler ]((skyline/gesture#Common attributes ))	`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`

Old Example:

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

New example:

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

[Is being supported] glass-easel Down, temporarily not supported WXS Event Response
[Is being supported] Skyline On the rendering backend, IntersectionObserver Not yet supported relativeTo, Support only relativeToViewport
[Is being supported] The following component instance methods are not supported:

animate
applyAnimation
clearAnimation
setInitialRenderingCache

# Known issues

Running in the exparser Compatibility mode,text Component cannot wrap

# Update record

2023-06-01 Support WXS
- Re-preview or upload without version dependency
2023-06-02 repair Nested wx:for May lead to anomalies [[WeChat mini-program /glass-easel#45]](https://github.com/WeChat mini-program /glass-easel/issues/45)
- Re-preview or upload without version dependency
2023-06-02 repair <template Name> Used in the WXS May fail when referenced to other files [[WeChat mini-program /glass-easel#47]](https://github.com/WeChat mini-program /glass-easel/issues/47)
- Re-preview or upload without version dependency
2023-06-12 repair <template>, <include>, <slot> Not supported on nodes wx: instruction [[WeChat mini-program /glass-easel#30]](https://github.com/WeChat mini-program /glass-easel/issues/30)
- Re-preview or upload without version dependency
2023-07-28 Support for compatibility mode WXS In Event Response ComponentDescriptor of getState method
- Base library version required 3.0.0 Or above, is gradually supported to version 2.19.2
2024-05-20 Supports fully empty data binding
- Re-preview or upload without version dependency