Skyline 滚动控制 API

适用场景

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

核心概念

三大 API 族群

NodesRef.node()

enhanced

NodesRef.node()

NodesRef.ref()

获取实例

// 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/

api/scroll-view-context.md

api/draggable-sheet-context.md

api/worklet-scroll-context.md

patterns.md

强制规则

MUST（必须遵守）

1. scroll-view 必须开启

   enhanced

   属性才能获取 ScrollViewContext：
   html

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

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

   // ❌ 错误：同时传入 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：
   js

   // ❌ 错误：使用 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'

   指令：
   js

   // ❌ 错误：缺少 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 方法速查

scrollTo({ top, left, velocity, duration, animated })

scrollIntoView(selector, options?)

triggerRefresh({ duration?, easingFunction? })

closeRefresh()

triggerTwoLevel({ duration?, easingFunction? })

closeTwoLevel({ duration?, easingFunction? })

ScrollViewContext 属性速查

场景决策表

ScrollViewContext.triggerRefresh()

ScrollViewContext.closeRefresh()

triggerTwoLevel()

closeTwoLevel()

ScrollViewContext.scrollTo({ top })

ScrollViewContext.scrollIntoView(selector)

DraggableSheetContext.scrollTo({ size })

worklet.scrollViewContext.scrollTo()

程序化刷新最小示例

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

相关技能

skyline-components

skyline-worklet

skyline-route

skyline-overview

References 目录结构

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