Skyline – 第 2 页 – 微信小程序开发指南

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

否

首次渲染时渲染的列表项数量，用于减少首次渲染时的白屏时长。不传则首屏也根据布局结果按需渲染

3.7.12

Bug & Tip

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 兼容实现。

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

通用属性

属性

类型

默认值

必填

说明

最低版本

type

string

aligned

是

布局方式

合法值	说明
aligned	每行高度由同一行中最大高度子节点决定
masonry	瀑布流，根据子元素高度自动布局

cross-axis-count

number

否

交叉轴元素数量

max-cross-axis-extent

number

否

交叉轴元素最大范围

main-axis-gap

number

否

主轴方向间隔

cross-axis-gap

number

否

交叉轴方向间隔

padding

Array

[0, 0, 0, 0]

否

长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距

3.0.0

示例代码

在开发者工具中预览效果

Tip

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

需具有可见的宽高（clientWidth 和 clientHeight）。例如：设置 display: block 属性；使用 image 组件时，应当手动指定高度或设置 mode="widthFix"。
若使用 padding、margin 等影响盒模型的CSS属性，需同时设置 box-sizing: border。
仅针对在末尾增删元素做优化，尽量避免在中间插入子元素。
子节点过多时仍会影响布局性能。对性能敏感的场景，建议使用 Skyline 对应组件。

grid-builder

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

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

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）

功能描述

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

通用属性

属性

类型

默认值

必填

说明

padding

Array

[0, 0, 0, 0]

否

长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距

list

Array

是

需要用于渲染的列表

child-count

Array

否

完整列表的长度，如果不传则取 list 的长度作为其值

type

string

aligned

是

布局方式

合法值	说明
aligned	每行高度由同一行中最大高度子节点决定
masonry	瀑布流，根据子元素高度自动布局

cross-axis-count

number

否

交叉轴元素数量

max-cross-axis-extent

number

否

交叉轴元素最大范围

main-axis-gap

number

否

主轴方向间隔

cross-axis-gap

number

否

交叉轴方向间隔

binditembuild

eventhandle

否

列表项创建时触发，event.detail = {index}，index 即被创建的列表项序号

binditemdispose

eventhandle

否

列表项回收时触发，event.detail = {index}，index 即被回收的列表项序号

Bug & Tip

tip: 目前只支持纵向滚动列表
bug: 目前 grid-builder 在进入屏幕后不允许再被滚动出屏幕，否则会被判定成列表需要重新布局进而自动滚动到 grid-builder 的顶端

使用方法

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

draggable-sheet

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

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

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）

功能描述

半屏可拖拽组件。该组件需配合 DraggableSheetContext 接口使用。目前仅在 Skyline 渲染引擎下支持。

属性说明

属性	类型	默认值	必填	说明	最低版本
initial-child-size	number	0.5	否	初始时占父容器的比例	3.2.0
min-child-size	number	0.25	否	最小时占父容器的比例	3.2.0
max-child-size	number	1.0	否	最大时占父容器的比例	3.2.0
snap	boolean	false	否	拖拽后是否自动对齐关键点	3.2.0
snap-sizes	Array.`<number>`	[]	否	拖拽后对齐的关键点，无需包含最小和最大值	3.2.0
worklet:onsizeupdate	worklet		否	尺寸发生变化时触发，仅支持 worklet 作为回调。event = {pixels, size}	3.2.0

示例代码

<draggable-sheet
  class="sheet"
  initial-child-size="0.5"
  min-child-size="0.2"
  max-child-size="0.8"
  snap="{{true}}"
  snap-sizes="{{[0.4, 0.6]}}"
  worklet:onsizeupdate="onSizeUpdate"
>
  <scroll-view
    scroll-y="{{true}}"
    type="list"
    associative-container="draggable-sheet"
    bounces="{{true}}"
  />
</draggable-sheet>

Page({
  onReady() {
    this.createSelectorQuery()
      .select(".sheet")
      .node()
      .exec(res => {
        const sheetContext = res[0].node
        sheetContext.scrollTo({
          size: 0.7,
          animated: true,
          duration: 300,
          easingFunction: 'ease'
        })
  },

  onSizeUpdate(e) {
    'worklet'
    console.info(`sizeUpdate pixels: ${e.pixels} size: ${e.size}`)
  }
})

效果演示

示例代码片段

在开发者工具中预览效果

vertical-drag-gesture-handler

相关文档: 手势系统

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）

功能描述

纵向滑动时触发手势

通用属性

属性类型默认值必填说明

tag string 否声明手势协商时的组件标识

worklet:ongesture eventhandler 否手势识别成功的回调

eventhandler 回调参数	说明
state	手势状态
absoluteX	相对于全局的 X 坐标
absoluteY	相对于全局的 Y 坐标
deltaX	相对上一次，X 轴方向移动的坐标
deltaY	相对上一次，Y 轴方向移动的坐标
velocityX	手指离开屏幕时的横向速度（pixel per second)
velocityY	手指离开屏幕时的纵向速度（pixel per second)

worklet:should-response-on-move callback 否手指移动过程中手势是否响应

worklet:should-accept-gesture callback 否手势是否应该被识别

simultaneous-handlers Array.<string> 否声明可同时触发的手势节点

native-view string 否代理的原生节点类型

tap-gesture-handler

相关文档: 手势系统

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）

功能描述

点击时触发手势

通用属性

属性类型默认值必填说明

tag string 否声明手势协商时的组件标识

worklet:ongesture eventhandler 否手势识别成功的回调

eventhandler 回调参数	说明
state	手势状态
absoluteX	相对于全局的 X 坐标
absoluteY	相对于全局的 Y 坐标

worklet:should-response-on-move callback 否手指移动过程中手势是否响应

worklet:should-accept-gesture callback 否手势是否应该被识别

simultaneous-handlers Array.<string> 否声明可同时触发的手势节点

native-view string 否代理的原生节点类型

微信小程序scale-gesture-handler

相关文档: 手势系统

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）

功能描述

多指缩放时触发手势

通用属性

属性类型默认值必填说明

tag string 否声明手势协商时的组件标识

worklet:ongesture eventhandler 否手势识别成功的回调

eventhandler 回调参数	说明
state	手势状态
focalX	中心点相对于全局的X坐标
focalY	中心点相对于全局的Y坐标
focalDeltaX	相对上一次，中心点在X轴方向移动的坐标
focalDeltaY	相对上一次，中心点在Y轴方向移动的坐标
scale	放大或缩小的比例
horizontalScale	scale的横向分量
verticalScale	scale的纵向分量
rotation	旋转角（单位：弧度）
velocityX	手指离开屏幕时的横向速度（pixel per second)
velocityY	手指离开屏幕时的纵向速度（pixel per second)
pointerCount	跟踪的手指数

worklet:should-response-on-move callback 否手指移动过程中手势是否响应

worklet:should-accept-gesture callback 否手势是否应该被识别

simultaneous-handlers Array.<string> 否声明可同时触发的手势节点

native-view string 否代理的原生节点类型

pan-gesture-handler

相关文档: 手势系统

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）

功能描述

拖动（横向/纵向）时触发手势

通用属性

属性类型默认值必填说明

tag string 否声明手势协商时的组件标识

worklet:ongesture eventhandler 否手势识别成功的回调

eventhandler 回调参数	说明
state	手势状态
absoluteX	相对于全局的 X 坐标
absoluteY	相对于全局的 Y 坐标
deltaX	相对上一次，X 轴方向移动的坐标
deltaY	相对上一次，Y 轴方向移动的坐标
velocityX	手指离开屏幕时的横向速度（pixel per second)
velocityY	手指离开屏幕时的纵向速度（pixel per second)

worklet:should-response-on-move callback 否手指移动过程中手势是否响应

worklet:should-accept-gesture callback 否手势是否应该被识别

simultaneous-handlers Array.<string> 否声明可同时触发的手势节点

native-view string 否代理的原生节点类型

微信小程序长按手势处理

相关文档: 手势系统

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）

功能描述

长按时触发手势

通用属性

属性类型默认值必填说明

tag string 否声明手势协商时的组件标识

worklet:ongesture eventhandler 否手势识别成功的回调

eventhandler 回调参数	说明
state	手势状态
absoluteX	相对于全局的 X 坐标
absoluteY	相对于全局的 Y 坐标
translationX	相对于初始触摸点的 X 轴偏移量
translationY	相对于初始触摸点的 Y 轴偏移量
velocityX	手指离开屏幕时的横向速度（pixel per second)
velocityY	手指离开屏幕时的纵向速度（pixel per second)

worklet:should-response-on-move callback 否手指移动过程中手势是否响应

worklet:should-accept-gesture callback 否手势是否应该被识别

simultaneous-handlers Array.<string> 否声明可同时触发的手势节点

native-view string 否代理的原生节点类型