Skyline Scroll Api

Skyline 滚动控制 API

适用场景

• 程序化触发 scroll-view 下拉刷新或关闭刷新
• 程序化触发/关闭下拉二级（"二楼"页面）
• 通过 ScrollViewContext 控制滚动位置和行为
• 控制 DraggableSheet 半屏面板滚动到指定位置
• 在 worklet 函数中（UI 线程）直接控制 scroll-view 滚动

核心概念

三大 API 族群

获取实例

// ScrollViewContext（需开启 enhanced）
wx.createSelectorQuery().select('#scrollview').node()
  .exec(res => { const ctx = res[0].node })

// DraggableSheetContext
wx.createSelectorQuery().select('.sheet').node()
  .exec(res => { const ctx = res[0].node })

// worklet.scrollViewContext（通过 ref）
this.scrollRef = wx.worklet.shared()
this.createSelectorQuery().select('.scrollable')
  .ref(res => { this.scrollRef.value = res.ref }).exec()

文档索引

根据需求快速定位（路径相对于 references/）：

强制规则

MUST（必须遵守）

1. scroll-view 必须开启 `enhanced` 属性才能获取 ScrollViewContext：

   <!-- ❌ 错误：未开启 enhanced，node() 返回的不是 ScrollViewContext -->
   <scroll-view type="list" scroll-y>

   <!-- ✅ 正确 -->
   <scroll-view type="list" scroll-y enhanced>

2. DraggableSheetContext.scrollTo 中 size 和 pixels 同时传入时，仅 size 生效：

   // ❌ 错误：同时传入 size 和 pixels，pixels 被忽略
   sheetContext.scrollTo({ size: 0.7, pixels: 200 })

   // ✅ 正确：二选一
   sheetContext.scrollTo({ size: 0.7 })   // 相对位置
   sheetContext.scrollTo({ pixels: 200 }) // 绝对位置

3. worklet.scrollViewContext 必须通过 `NodesRef.ref` 获取引用并存入 SharedValue：

   // ❌ 错误：使用 node() 而非 ref()
   this.createSelectorQuery().select('.scroll').node()
     .exec(res => { /* 这是 ScrollViewContext，不是 worklet 引用 */ })

   // ✅ 正确：使用 ref() + shared()
   this.scrollRef = wx.worklet.shared()
   this.createSelectorQuery().select('.scroll')
     .ref(res => { this.scrollRef.value = res.ref }).exec()

4. 调用 worklet.scrollViewContext.scrollTo 的函数必须声明 `'worklet'` 指令：

   // ❌ 错误：缺少 worklet 指令
   onTap() {
     scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
   }

   // ✅ 正确
   onTap() {
     'worklet'
     scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
   }

NEVER（禁止行为）

1. NEVER 在逻辑线程中调用 worklet.scrollViewContext.scrollTo——该 API 仅在 UI 线程（worklet 函数内）可用 2. NEVER 在小程序插件中使用 worklet.scrollViewContext.scrollTo——该 API 不支持小程序插件

Quick Reference

ScrollViewContext 方法速查

ScrollViewContext 属性速查

场景决策表

程序化刷新最小示例

// 获取 ScrollViewContext
wx.createSelectorQuery().select('#sv').node().exec(res => {
  const ctx = res[0].node
  ctx.triggerRefresh({ duration: 300 })
  // 数据加载完成后
  setTimeout(() => ctx.closeRefresh(), 2000)
})

相关技能

References 目录结构

references/
├── api/
│   ├── draggable-sheet-context.md
│   ├── scroll-view-context.md
│   └── worklet-scroll-context.md
└── patterns.md

DraggableSheetContext API 参考

基础库 3.2.0+

概述

DraggableSheet 实例，可通过 wx.createSelectorQuery 的 NodesRef.node 方法获取。用于程序化控制 draggable-sheet 组件的滚动位置。

📌 组件属性详情请参阅：skyline-components - draggable-sheet 组件

获取方式

// WXML: <draggable-sheet class="sheet">...</draggable-sheet>
wx.createSelectorQuery()
  .select('.sheet')
  .node()
  .exec(res => {
    const sheetContext = res[0].node
    // sheetContext 即 DraggableSheetContext 实例
  })

方法

DraggableSheetContext.scrollTo(Object object)

小程序插件：支持

滚动到指定位置。

重要：size 取值 [0, 1]，size = 1 时表示撑满 draggable-sheet 组件。`size` 和 `pixels` 同时传入时，仅 size 生效。

参数

size vs pixels

⚠️ 两者同时传入时，size 优先，pixels 被忽略。

示例代码

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'
        })

        // 方式二：绝对位置
        sheetContext.scrollTo({
          pixels: 200,
          animated: true
        })
      })
  }
})

常见用法

配合按钮展开/收起

Page({
  data: { expanded: false },

  onReady() {
    this.createSelectorQuery().select('.sheet').node()
      .exec(res => { this.sheetCtx = res[0].node })
  },

  toggleSheet() {
    const size = this.data.expanded ? 0.3 : 0.8
    this.sheetCtx.scrollTo({ size, animated: true, duration: 300 })
    this.setData({ expanded: !this.data.expanded })
  }
})

ScrollViewContext API 参考

基础库 2.14.4+

概述

增强 ScrollView 实例，可通过 wx.createSelectorQuery 的 NodesRef.node 方法获取。仅在 scroll-view 组件开启 `enhanced` 属性后生效。

获取方式

// WXML: <scroll-view id="sv" type="list" scroll-y enhanced>
wx.createSelectorQuery()
  .select('#sv')
  .node()
  .exec((res) => {
    const scrollView = res[0].node
    // scrollView 即 ScrollViewContext 实例
    scrollView.scrollEnabled = false
  })

属性

方法

ScrollViewContext.scrollTo(Object object)

基础库 2.14.4+ | 小程序插件：支持 | Windows/Mac：支持

滚动至指定位置。

scrollView.scrollTo({ top: 500, animated: true })

ScrollViewContext.scrollIntoView(string selector, object ScrollIntoViewOptions)

基础库 2.14.4+ | 小程序插件：支持 | Windows/Mac：支持

滚动至指定元素位置。

参数 1: selector - 元素选择器

参数 2: ScrollIntoViewOptions（基础库 3.1.0+，仅 Skyline 模式支持）

// 基础用法
scrollView.scrollIntoView('#target')

// Skyline 增强用法（基础库 3.1.0+）
scrollView.scrollIntoView('#target', {
  alignment: 'center',
  offset: -20,
  animated: true
})

⚠️ ScrollIntoViewOptions 仅在 Skyline 模式下支持，WebView 模式仅支持 selector 参数。

ScrollViewContext.triggerRefresh(Object object)

基础库 3.0.0+ | 小程序插件：支持

触发下拉刷新。

ScrollViewContext.closeRefresh()

基础库 3.0.0+ | 小程序插件：支持

关闭下拉刷新。无参数。

ScrollViewContext.triggerTwoLevel(Object object)

基础库 3.0.0+ | 小程序插件：支持

触发下拉二级。

ScrollViewContext.closeTwoLevel(Object object)

基础库 3.0.0+ | 小程序插件：支持

关闭下拉二级。

与组件属性的关系

ScrollViewContext 提供程序化控制能力，与 scroll-view 组件的声明式属性互补：

📌 组件属性详情请参阅：skyline-components - scroll-view 组件

worklet.scrollViewContext API 参考

基础库 3.3.0+ | 小程序插件：不支持

概述

worklet.scrollViewContext 提供在 worklet 函数内操作 scroll-view 组件的能力。通过 NodesRef.ref 获取 scroll-view 的引用，即可在 UI 线程中直接控制滚动，适用于配合手势事件实现高性能自定义滚动交互。

📌 Worklet 基础概念请参阅：skyline-worklet - SharedValue、worklet 指令

与 ScrollViewContext.scrollTo 的对比

获取引用

const { shared } = wx.worklet

Page({
  onLoad() {
    // 1. 创建 SharedValue 存储引用
    this.scrollRef = shared()
    // 2. 通过 ref() 获取 scroll-view 引用
    this.createSelectorQuery()
      .select('.scrollable')
      .ref((res) => {
        this.scrollRef.value = res.ref
      })
      .exec()
  }
})

⚠️ 必须使用 ref()（非 node()），且引用必须存入 SharedValue，以便在 worklet 函数内访问。

方法

worklet.scrollViewContext.scrollTo(ref, Object object)

在 UI 线程中滚动 scroll-view 至指定位置。

参数 1: ref - 通过 NodesRef.ref() 获取并存入 SharedValue 的引用

参数 2: Object object

示例代码

const { shared, scrollViewContext } = wx.worklet

Page({
  onLoad() {
    this.scrollRef = shared()
    this.createSelectorQuery()
      .select('.scrollable')
      .ref((res) => {
        this.scrollRef.value = res.ref
      })
      .exec()
  },

  onTap() {
    'worklet'
    scrollViewContext.scrollTo(this.scrollRef.value, {
      top: 200,
      duration: 2000,
      animated: true,
      easingFunction: 'ease'
    })
  }
})

要点

• 调用 scrollTo 的函数必须声明 `'worklet'` 指令
• 引用通过 createSelectorQuery().select().ref() 获取，存储在 SharedValue 中
• 可配合手势事件在 UI 线程中实现自定义滚动控制，避免跨线程通信延迟
• 不支持小程序插件

滚动 API 代码模式

模式 1：程序化下拉刷新

scroll-view 开启 refresher-enabled 后，通过 ScrollViewContext 程序化控制刷新状态。

WXML

<scroll-view
  id="sv"
  type="list"
  scroll-y
  enhanced
  refresher-enabled="{{true}}"
  refresher-default-style="none"
  refresher-triggered="{{refreshing}}"
  bindrefresherrefresh="onRefresh"
  bind:refresherstatuschange="onStatusChange"
>
  <view slot="refresher" class="custom-refresher">
    <view wx:if="{{status === 0}}">下拉刷新</view>
    <view wx:elif="{{status === 1}}">松手刷新</view>
    <view wx:elif="{{status === 2}}">刷新中...</view>
    <view wx:elif="{{status === 3}}">刷新完成</view>
  </view>
  <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
</scroll-view>

JS

Page({
  data: {
    refreshing: false,
    status: 0,
    list: []
  },

  onReady() {
    wx.createSelectorQuery().select('#sv').node()
      .exec(res => { this.svCtx = res[0].node })
  },

  // 用户手动下拉触发
  onRefresh() {
    this.loadData()
  },

  onStatusChange(e) {
    this.setData({ status: e.detail.status })
  },

  // 程序化触发刷新（如点击按钮）
  manualRefresh() {
    this.svCtx.triggerRefresh({ duration: 300, easingFunction: 'ease' })
    this.loadData()
  },

  loadData() {
    this.setData({ refreshing: true })
    // 模拟请求
    setTimeout(() => {
      this.setData({ refreshing: false, list: [...] })
      // 也可通过 Context 关闭
      // this.svCtx.closeRefresh()
    }, 2000)
  }
})

模式 2：下拉二级（"二楼"页面）

下拉二级是下拉刷新的扩展，继续下拉可进入"二楼"页面。

WXML

<scroll-view
  id="sv"
  type="list"
  scroll-y
  enhanced
  refresher-enabled="{{true}}"
  refresher-two-level-enabled="{{true}}"
  refresher-two-level-scroll-enabled="{{true}}"
  refresher-two-level-threshold="{{150}}"
  bind:refresherstatuschange="onStatusChange"
>
  <view slot="refresher" class="refresher-container">
    <view wx:if="{{status < 5}}">下拉刷新区域</view>
    <view wx:else class="two-level-content">
      二级页面内容（"二楼"）
    </view>
  </view>
  <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
</scroll-view>

JS

Page({
  data: { status: 0 },

  onReady() {
    wx.createSelectorQuery().select('#sv').node()
      .exec(res => { this.svCtx = res[0].node })
  },

  onStatusChange(e) {
    this.setData({ status: e.detail.status })
  },

  // 程序化打开二楼
  openTwoLevel() {
    this.svCtx.triggerTwoLevel({
      duration: 500,
      easingFunction: 'ease'
    })
  },

  // 程序化关闭二楼
  closeTwoLevel() {
    this.svCtx.closeTwoLevel({
      duration: 500,
      easingFunction: 'ease'
    })
  }
})

RefreshStatus 枚举

模式 3：DraggableSheet 程序化控制

通过 DraggableSheetContext 控制半屏面板的展开/收起。

Page({
  data: { expanded: false },

  onReady() {
    this.createSelectorQuery().select('.sheet').node()
      .exec(res => { this.sheetCtx = res[0].node })
  },

  // 展开到 70%
  expandSheet() {
    this.sheetCtx.scrollTo({
      size: 0.7,
      animated: true,
      duration: 300,
      easingFunction: 'ease'
    })
  },

  // 收起到 30%
  collapseSheet() {
    this.sheetCtx.scrollTo({
      size: 0.3,
      animated: true,
      duration: 300
    })
  },

  // 使用绝对像素定位
  scrollToPixels() {
    this.sheetCtx.scrollTo({
      pixels: 200,
      animated: true,
      duration: 300
    })
  }
})

模式 4：Worklet 内滚动控制

在 UI 线程中直接控制 scroll-view 滚动，配合手势实现高性能交互。

const { shared, scrollViewContext } = wx.worklet

Page({
  onLoad() {
    // 1. 创建 SharedValue 存储引用
    this.scrollRef = shared()

    // 2. 通过 ref() 获取引用
    this.createSelectorQuery()
      .select('.scrollable')
      .ref((res) => {
        this.scrollRef.value = res.ref
      })
      .exec()
  },

  // 3. 在 worklet 函数中控制滚动
  handleGesture(e) {
    'worklet'
    const { absoluteY } = e
    // 根据手势位置控制滚动
    scrollViewContext.scrollTo(this.scrollRef.value, {
      top: absoluteY * 2,
      duration: 0,
      animated: false
    })
  },

  // 带动画的滚动
  scrollToTop() {
    'worklet'
    scrollViewContext.scrollTo(this.scrollRef.value, {
      top: 0,
      duration: 500,
      animated: true,
      easingFunction: 'ease'
    })
  }
})

模式 5：ScrollIntoView Skyline 增强

Skyline 模式下 scrollIntoView 支持额外配置项。

Page({
  onReady() {
    wx.createSelectorQuery().select('#sv').node()
      .exec(res => { this.svCtx = res[0].node })
  },

  // 基础用法（WebView + Skyline 均支持）
  scrollToItem() {
    this.svCtx.scrollIntoView('#item-50')
  },

  // Skyline 增强用法（基础库 3.1.0+）
  scrollToItemEnhanced() {
    this.svCtx.scrollIntoView('#item-50', {
      alignment: 'center',     // 目标居中显示
      offset: -20,             // 额外偏移 -20px
      withinExtent: true,      // 仅滚动到 cacheExtent 内的节点
      animated: true
    })
  }
})