snapshot

基础库 3.0.1 开始支持,低版本需做兼容处理。

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

截图组件。 支持将其子节点的渲染结果导出成图片,该组件需配合 snapshot 接口使用。 目前仅在 Skyline 渲染引擎 下支持。

通用属性

属性 类型 默认值 必填 说明
mode string view 渲染模式
合法值 说明 最低版本
view 以真实节点渲染。 3.1.0
picture 对子节点生成的内容截图渲染。 3.1.0

Bug & Tip

  1. tip:如需离屏渲染导出,可将 snapshot 组件移动到屏幕外或设置 width: 100%; position: absolute; transform: scale(0) 即可,但不能设置为 display: none 或 visibility: hidden
  2. tip:子节点不能包含原生组件,其他任意组件均可使用
  3. tip:支持对任意大小的区域导出图片,即导出图片没有尺寸限制
  4. tip: 如需实现长列表截图,不建议直接嵌在 scroll-view 内(即 <scroll-view><snapshot></snapshot></scroll-view>),会影响列表滚动性能,建议将 snapshot 组件放在 scroll-view 外,与 scroll-view 加载同一批列表数据,要截图时再将 snapshot 渲染出来

渲染模式

Skyline 下对节点进行 transform: scale() rotate() 动画时,若子节点内容比较复杂,动画性能可能不佳。为解决该问题,可利用 snapshot 组件改变渲染模式。

<snapshot mode="view">
 <view></view>
</snapshot>

view 模式渲染时,snapshot 组件与普通的 view 无差别,对子节点设置样式,变化会体现在界面上。 以 picture 模式渲染时,snapshot 组件会对当下渲染的子节点进行截图,后续子节点被替换为图片进行渲染,此时对子节点设置样式,变化不会体现在界面上。

picture 模式下进行 transform: scale() rotate() 动画时,性能较好。此时通过 setData 等对子节点进行的修改,当再次切换为 view 模式时,界面会立刻改变为最终样式。

通常在对大范围节点进行 scalerotate 动画时,可在动画开始设置为 picture 模式,动画结束设置为 view 模式,以提高动画表现。如子节点内容会发生改变,则不适用该模式切换。

示例代码

  <snapshot id="target">
    <view>content</view>
  </snapshot>
Page({
  onReady() {
    this.createSelectorQuery()
      .select("#target")
      .node()
      .exec(res => {
        const node = res[0].node
        node.takeSnapshot({
          type: 'arraybuffer',
          format: 'png',
          success: (res) => {},
          fail(res) {}
        })
  }
})

示例代码片段

在开发者工具中预览效果

share-element

基础库 2.16.0 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

共享元素。

共享元素是一种动画形式,类似于 Flutter 的 Hero 动画,表现为元素像是在页面间穿越一样。该组件需与 page-container 组件结合使用。

使用时需在当前页放置 share-element 组件,同时在 page-container 容器中放置对应的 share-element 组件,对应关系通过属性值 key 映射。当设置 page-container 显示时,transform 属性为 true 的共享元素会产生动画。当前页面容器退出时,会产生返回动画。

  1. 使用 worklet 函数需要开启开发者工具 “将 JS 编译成 ES5” 或 “编译 worklet 函数” 选项。

通用属性

属性 类型 默认值 必填 说明 最低版本
key string 映射标记,页面内唯一 2.29.2
transform boolean false 是否进行动画 2.16.0
duration number 300 动画时长,单位毫秒 2.16.0
easing-function string ease-out css缓动函数 2.16.0

Skyline 特有属性

属性 类型 默认值 必填 说明 最低版本
transition-on-gesture boolean false 手势返回时是否进行动画 2.29.2
shuttle-on-push string to 指定 push 阶段的飞跃物 2.30.2
合法值 说明
from push 阶段采用源页面节点作为飞跃物
to push 阶段采用目标页面节点作为飞跃物
from pop 阶段采用源页面节点作为飞跃物
to pop 阶段采用目标页面节点作为飞跃物
shuttle-on-pop string to 指定 pop 阶段的飞跃物 2.30.2
worklet:onframe callback 动画帧回调 2.30.2
rect-tween-type string materialRectArc 动画插值曲线 2.30.2
合法值 说明
materialRectArc 矩形对角动画
materialRectCenterArc 径向动画
linear
elasticIn
elasticOut
elasticInOut
bounceIn
bounceOut
bounceInOut
cubic-bezier(x1, y1, x2, y2 )

WebView 示例代码

在开发者工具中预览效果

Skyline 示例代码

在开发者工具中预览效果

open-data-list

基础库 3.7.8 开始支持,低版本需做兼容处理。

相关文档: 聊天工具模式、Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

展示微信开放数据。

通用属性

属性 类型 默认值 必填 说明
type string 开放数据类型
合法值 说明
groupMembers 群成员信息
members Array.<string> 群成员group_openid列表

示例代码

<open-data-list type="groupMembers" members="{{members}}">
  <view class="userinfo" slot:index>
    <open-data-item class="avatar " type="userAvatar" index="{{index}}" />
    <open-data-item class="" type="userNickName" index="{{index}}" />
  </view>
</open-data-list>

open-data-item

基础库 3.7.8 开始支持,低版本需做兼容处理。

相关文档: 聊天工具模式、Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

展示微信开放数据,需配合 open-data-list 组件使用。

通用属性

属性 类型 默认值 必填 说明
type string 开放数据类型
合法值 说明
userNickName 用户昵称
userAvatar 用户头像
index number 序号

示例代码

<open-data-list type="groupMembers" members="{{members}}">
  <view class="userinfo" slot:index>
    <open-data-item class="avatar " type="userAvatar" index="{{index}}" />
    <open-data-item class="" type="userNickName" index="{{index}}" />
  </view>
</open-data-list>

open-container

基础库 3.4.0 开始支持,低版本需做兼容处理。

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

容器转场动画组件。

点击 <open-container> 组件,当使用 wx.navigateTo 跳转下一页面时,对其子节点和下一个页面进行过渡。

下个页面从 <open-container> 所在位置大小渐显放大,同时 <open-container> 内容渐隐,过渡效果包含背景色、圆角和阴影。

源页面 <open-container>closed 状态,转场动画后为 open 状态。

通用属性

属性 类型 默认值 必填 说明
closed-color string white 初始容器背景色
closed-elevation number 0 初始容器影深大小
closed-border-radius number 0 初始容器圆角大小
middle-color string fadeThrough 模式下的过渡背景色
open-color string white 打开状态下容器背景色
open-elevation number 0 打开状态下容器影深大小
open-border-radius number 0 打开状态下容器圆角大小
transition-duration number 300 动画时长
transition-type string fade 动画类型
合法值 说明
fade 将传入元素淡入传出元素之上
fadeThrough 首先淡出传出元素,并在传出元素完全淡出后开始淡入传入元素

示例代码

<open-container
  closed-elevation="{{closedElevation}}"
  closed-border-radius="{{closedBorderRadius}}"
  open-elevation="{{openElevation}}"
  open-border-radius="{{openBorderRadius}}"
  transition-type="{{type}}"
  transition-duration="{{duration}}"
  bind:tap="goDetail"
>
  <card/>
</open-container>
Page({
   goDetail() {
    wx.navigateTo({
      url: 'nextPageUrl'
    })
  }
})

示例代码片段

在开发者工具中预览效果

nested-scroll-header

基础库 3.2.0 开始支持,低版本需做兼容处理。

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

在嵌套的 scroll-view 场景中,属于外层 scroll-view 的节点,只支持作为 <scroll-view type="nested"> 模式的直接子节点。不支持多个子节点,渲染时会取第一个子节点来渲染。具体用法可以参考 scroll-view

使用方法

<scroll-view
  type="nested"
  scroll-y
>
  <nested-scroll-header>
    <view>会渲染</view>
    <view>不会渲染,因为 nested-scroll-header 只会渲染第一个子节点</view>
  </nested-scroll-header>
  <nested-scroll-header>
    <view>如果存在多个头部节点,那么就使用多个 nested-scroll-header 来将其包裹</view>
  </nested-scroll-header>
  <nested-scroll-body>
    <view></view>
  </nested-scroll-body>
</scroll-view>

nested-scroll-body

基础库 3.2.0 开始支持,低版本需做兼容处理。

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

在嵌套的 scroll-view 场景中,属于里层 scroll-view 的节点,只支持作为 <scroll-view type="nested"> 模式的直接子节点。不支持多个子节点,渲染时会取第一个子节点来渲染。具体用法可以参考 scroll-view。

属性说明

属性 类型 默认值 必填 说明 最低版本
offset-top number 0 滚动目标距离顶部的距离(单位:px)。在外层 scroll-view 滚动时,此组件会在主轴方向逐渐撑开,直到此组件顶部与视窗顶部距离等于该属性值时,才开始里层 scroll-view 的滚动。默认为 0,即表示此组件撑开到顶部与视窗顶部齐平时,才开始里层 scroll-view 的滚动。 3.6.2

使用方法

<scroll-view
  type="nested"
  scroll-y
>
  <nested-scroll-header>
    <view></view>
  </nested-scroll-header>
  <nested-scroll-body>
    <scroll-view
      type="list"
      scroll-y
    >
      <view>嵌套里层的 scroll-view</view>
    </scroll-view>
    <view>不会渲染,因为 nested-scroll-body 只会渲染第一个子节点</view>
  </nested-scroll-body>
</scroll-view>

list-view

基础库 2.29.0 开始支持,低版本需做兼容处理。

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

列表布局容器,仅支持作为 <scroll-view type="custom"> 模式的直接子节点或 sticky-section 组件直接子节点

属性说明

属性 类型 默认值 必填 说明 最低版本
padding Array [0, 0, 0, 0] 长度为 4 的数组,按 top、right、bottom、left 顺序指定内边距 3.0.0

list-builder

基础库 3.3.0 开始支持,低版本需做兼容处理。

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

列表构造器,仅支持作为 <scroll-view type="custom"> 模式的直接子节点。具体用法可参考 scroll-view

通用属性

属性 类型 默认值 必填 说明 最低版本
padding Array [0, 0, 0, 0] 长度为 4 的数组,按 top、right、bottom、left 顺序指定内边距
type string static 类型,默认为定高模式
合法值 说明
static 定高模式,所有列表项等高,需要传入 child-height
dynamic 不定高模式
list Array 需要用于渲染的列表
child-count Array 完整列表的长度,如果不传则取 list 的长度作为其值
child-height Array 列表项的高度,当 type 为 static 时必须传入
binditembuild eventhandle 列表项创建时触发,event.detail = {index},index 即被创建的列表项序号
binditemdispose eventhandle 列表项回收时触发,event.detail = {index},index 即被回收的列表项序号
initial-child-count number 0 首次渲染时渲染的列表项数量,用于减少首次渲染时的白屏时长。不传则首屏也根据布局结果按需渲染 3.7.12

Bug & Tip

  1. tip: 目前只支持纵向滚动列表

使用方法

<scroll-view
  type="custom"
  scroll-y
>
   <list-builder
    list="{{list}}"
    child-count="{{list.length}}"
    child-height="200"
  >
    <view slot:item slot:index style="height: 200px;">
      <view>{{item.id}}-{{index}}</view>
    </view>
  </list-builder>
</scroll-view>

grid-view

基础库 2.29.0 开始支持,低版本需做兼容处理。

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

Skyline 下网格布局容器 和 瀑布流布局容器。基础库版本 2.30.4 起提供 WebView 兼容实现。

  1. 仅支持作为 <scroll-view type="custom"> 模式的直接子节点
  2. 按需渲染节点,比 WebView 兼容实现具备更好的性能。

通用属性

属性 类型 默认值 必填 说明 最低版本
type string aligned 布局方式
合法值 说明
aligned 每行高度由同一行中最大高度子节点决定
masonry 瀑布流,根据子元素高度自动布局
cross-axis-count number 2 交叉轴元素数量
max-cross-axis-extent number 0 交叉轴元素最大范围
main-axis-gap number 0 主轴方向间隔
cross-axis-gap number 0 交叉轴方向间隔
padding Array [0, 0, 0, 0] 长度为 4 的数组,按 top、right、bottom、left 顺序指定内边距 3.0.0

示例代码

在开发者工具中预览效果

Tip

在 WebView 下且 type="masonry" 时,grid-view 的子元素:

  1. 需具有可见的宽高(clientWidthclientHeight)。例如: 设置 display: block 属性; 使用 image 组件时,应当手动指定高度或设置 mode="widthFix"
  2. 若使用 paddingmargin 等影响盒模型的CSS属性,需同时设置 box-sizing: border
  3. 仅针对在末尾增删元素做优化,尽量避免在中间插入子元素。
  4. 子节点过多时仍会影响布局性能。对性能敏感的场景,建议使用 Skyline 对应组件。