分类： 从 WebView 迁移

Skyline 后端默认启用 glass-easel 框架，故 Skyline 微信小程序需要进行一些少量适配，点击查阅更多适配详情。

按需注入

Skyline 依赖 按需注入 特性。按需注入特性开启后，微信小程序的部分表现会发生变化，有可能带来兼容问题（具体见按需注入特性文档）；因此建议在开始适配 Skyline 前，先开启按需注入并妥善测试，以提前排除该特性带来的影响。

渐进式迁移

对于已有的项目，建议渐进式迁移，即逐个页面打开，推荐迁移使用该微信小程序的关键路径上的页面，以便让大多数用户获得更好的体验；对于新增页面，建议默认开启 Skyline；而对于全新项目，建议直接全局打开，除了有更好的体验外，也能使微信小程序的内存占用更低

使用局部滚动

在 WebView 下，页面全局默认是可以滚动的，因此大多数开发者会直接使用全局的滚动，这使得

1. 无需滚动的元素使用 position: fixed 固定位置，如自定义导航栏，这是用全局滚动模拟了局部滚动，此时滚动条的显示位置会溢出
2. 针对滚动的自定义功能只能通过配置或 API 的方式提供，如 Page.onPageScroll 等，也使得部分特性无法实现

因此，Skyline 不再提供全局滚动，在需要滚动的区域使用 scroll-view 实现，后续我们也能针对 scroll-view 组件提供更多扩展。

一般来说，界面布局大多数都是导航栏 + 滚动区域的形式，这里提供一种常规做法（兼容 WebView）

<navigation-bar></navigation-bar>
<!-- 通过使用 flex 布局，将 scroll-view 设置 flex:1 以占据页面剩余空间 -->
<scroll-view type="list" scroll-y style="display: flex; flex-direction: column; flex: 1; width: 100%; overflow: auto;">
  <view wx:for="{{items}}" list-item></view>
</scroll-view>

全局样式重置

Skyline 支持的 WXSS 是 WebView 的子集，未来可能会再支持一些必要的或常用的特性，但还是会一直保持 WebView 子集的状态。

因此，为了让 WebView 的兼容表现尽量对齐 Skyline，同时减少重复设置的代码，建议全启开启下述配置项：

rendererOptions: {
  "skyline": {
    "defaultDisplayBlock": true,
    "defaultContentBox": true,
    "tagNameStyleIsolation": "legacy",
    "enableScrollViewAutoSize": true,
  }
}

同时考虑全局或页面级应用如下 WXSS Reset：

page,
view,
text,
image,
button,
video,
map,
scroll-view,
swiper,
input,
textarea,
navigator {
  position: relative;
  background-origin: border-box;
  isolation: isolate;
}
page {
  height: 100%;
}

优化长列表性能

Skyline 下的 scroll-view 组件自带按需渲染的优化，这在很大程度上提升了长列表的渲染性能，这里是以 scroll-view 的直接子节点为粒度来按需渲染的，当其某个子节点接近 scroll-view 的 viewport 时就会被渲染，反之则会回收。

<!-- 以下 scroll-view 的直接子节点有 5 个 view，此时每个 view 都能按需渲染 -->
<scroll-view type="list" scroll-y>
    <view> a </view>
    <view> b </view>
    <view> c </view>
    <view> d </view>
    <view> e </view>
</scroll-view>
<!-- 以下 scroll-view 的直接子节点只有 1 个 view，按需渲染并不能发挥作用 -->
<scroll-view type="list" scroll-y>
    <view>
        <view> a </view>
        <view> b </view>
        <view> c </view>
        <view> d </view>
        <view> e </view>
    </view>
</scroll-view>

此外，长列表的每一项的样式基本是一样的，Skyline 也支持了相似节点的样式共享，使得样式只需要计算一次便能共享给其它相似节点，大大提升了样式计算的性能。一般来说，我们会用 WXML 模板语法 wx:for 来展开列表，因此只需要在列表项声明 list-item 就能启动样式共享（后续版本会识别 wx:for 而自动启用）

<scroll-view type="list" scroll-y>
    <view wx:for="" list-item> {{index}} </view>
</scroll-view>

预加载

微信小程序有个重要优化是会预加载环境，包括 WebView 环境、AppService 线程、提前注入基础库等，而由于目前微信小程序大多还是以 WebView 渲染，为了节省资源，微信客户端并不会自动预加载 Skyline 环境（后续根据实际情况不断优化策略），因此我们提供了 wx.preloadSkylineView 预加载 Skyline 环境的接口，开发者可以在可能跳转到 Skyline 页面的路径上手动调用该接口，建议在 onShow 生命周期里延迟一段时间后调用，使得 Skyline 页面被返回时能够重新预载

使用增强特性

为了使微信小程序的体验能够跟接近原生 App，Skyline 新增了若干个特性，包括 worklet 动画机制、手势系统、自定义路由、共享元素动画等，这些特性使得 Skyline 能够做出一些 WebView 下无法实现或实现效果不够流畅的交互动效。

考虑在 WebView 下都不支持，推荐以一种体验降级的方式去兼容。比如自定义路由，同样是以 wx.navigateTo 接口跳转页面，在 Skyline 下可以以自定义路由动画的方式跳转页面，以获得更好的体验，而 WebView 则 fallback 到朴素的从右到左的页面切换动画，同理，共享元素动画特性亦是如此，也无需额外的兼容代码。

Skyline 目前各端的支持情况见下表

可以看出，微信小程序若不是只跑在最新版本的微信移动端，则需要关注兼容 WebView 的情况，这里我们整理了一些兼容方法及常见的兼容问题

兼容方法

样式兼容

Skyline 与 WebView 的主要差异在于样式支持度，因此大部分兼容工作主要集中在样式适配，这里可以利用开发者工具的 WXML 调试工具，通过定位到有问题的节点，分析对应的样式兼容性。

对于具体样式兼容的策略上，由于 Skyline 中部分样式的默认值与 web 不同，因使用默认值而省略的样式需要显示指定，如 flex-direction: row，但此处更推荐开启默认 Block 布局和默认 ContentBox 盒模型，默认值处理与 web 更接近，其它更多信息，详见 Skyline WXSS 样式支持与差异

根据不同 renderer 兼容

有时，单纯用 WXML 和 WXSS 无法做好兼容时，可以通过 JS 判断是否 Skyline 以使用不同的 WXML 或 WXSS 实现。我们在页面或组件实例增加了 renderer 成员，取值为 webview 或 skyline，参考以下代码

<view class="position {{renderer}}"></view>

.position {
    position: fixed;
}
.position.skyline {
    position: absolute;
}

Page({
    data: {
        renderer: 'webview'
    },
    onLoad() {
        this.setData({
            renderer: this.renderer,
        })
    },
})

常见的兼容问题

• Skyline 一定需要应用到整个微信小程序吗？

  不需要，Skyline 支持按页面粒度或分包粒度开启，可渐进式迁移。

• 开启 Skyline 后布局错乱

  一般是默认 flex 布局及 box-sizing 默认为 border-box 导致，推荐开发者开启默认 Block 布局、默认 ContentBox 盒模型。

• 切换 Skyline后，为什么顶部原生导航栏消失？

  不支持原生导航栏，需自行实现，或使用 weui 组件库。推荐页面配置加上 “navigationStyle”: “custom” 以保持与 WebView 兼容

• 切换 Skyline 后，为什么 position: absolute 相对坐标不准确？

  在 Skyline 模式下，所有节点默认是 relative，可能导致 absolute 相对坐标不准。建议开发者修改节点 position 或者修改相对坐标。

• 多段文本无法内联

  因不支持 inline 布局导致，需改成 flex 布局实现，或者使用 text 组件包裹多段文本，而不是用 view 组件包裹，也可以使用 span 组件包裹 text 和 image 混合内联。如 <span><image /></span>、<span><view style="width: 50px;"/></span>

• 单行文本的省略样式失效

  text-overflow: ellipse 只在 text 组件上生效，不能应用在 view 组件上，同时需要声明 white-space: nowrap 以及 overflow: hidden，建议直接使用 <text overflow="ellipsis"/>

• 多行文本的省略样式失效

  在单行文本省略的基础上，通过 text 组件的 max-lines 属性设置最长行数，即 <text max-lines="2"></text>

• z-index 表现异常

  这是由于 Skyline 不支持 web 标准的层叠上下文所致，只有在同层级的节点之前应用 z-index 才有效，可根据实际情况调整取值

• weui 扩展库无法使用

  平台正在支持扩展库，预计近期上线。建议开发者使用 npm 安装 weui 组件库 后，将 node_ modules/weui-miniprogram 下的miniprogram_ dist 替换为 链接 中的 miniprogram_dist，然后在微信开发中工具中构建 npm 即可。

• 不支持组件 animate 动画接口

  暂不支持组件 animate 动画接口。如需实现相关效果，可使用 worklet 动画机制 实现

• svg 渲染不正确

  Skyline 上的 SVG 不支持 选择器匹配，可自行转成内联的方式；不支持 rgba 格式，可使用 fill-opacity 替代；建议用 SVGO 在线工具优化

• 自定义组件的样式表现不正确

  • 可留意是否存在跨自定义组件的样式匹配，Skyline 下 tag 和 id 选择器不支持跨自定义组件匹配，而 class 则遵循 组件样式隔离机制，可开启 tag 选择器全局匹配以保持与旧版行为对齐

• WebView scroll-view 横向滚动不生效

  横向滚动需打开 enable-flex 以兼容 WebView，同时 scroll-view 添加样式 display: flex; flex-direction: row;，scroll-view 子节点添加样式 flex-shrink: 0;

• 当 scroll-view 包含的内容较多时，为什么 boundingClientRect 无法执行？

  由于 scroll-view 的直接子节点（第一层节点）是按需渲染，即直接子节点不在屏时不会渲染，无法获取到节点尺寸，因此当 boundingClientRect 通过 query.selectAll 获取时，无法立即获取节点尺寸，只有在所有节点渲染才能获取。建议开发者尝试调整为逐个获取节点的 boundingClientRect。

• 切换 Skyline 后，为什么 map / canvas / video / camera 在微信开发者工具渲染失败？

  在 Skyline 模式下，微信开发者工具暂未支持调试原生组件，建议开发者使用真机预览完成调试。

• 在 Skyline 模式下，为什么微信开发者工具热重载无响应？

  目前 Skyline 模式暂不支持热重载，建议先关闭热重载，重新编译来预览渲染结果。后续平台将支持热重载能力。

为了方便开发者从 WebView 迁移到 Skyline，我们将一些最佳实践和常见的兼容问题都整理成一个检测工具 Skylint

Skylint 不仅会罗列出有兼容问题的具体代码行，对一些明确的兼容问题，也提供自动修改代码的操作，旨在最大程度降低迁移成本

更多说明和用法请前往 Github 查看