Skyline 滚动控制 API

适用场景

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

核心概念

三大 API 族群

API 族群	获取方式	线程	最低基础库
ScrollViewContext	NodesRef.node() + enhanced 属性	逻辑线程	2.14.4
DraggableSheetContext	NodesRef.node()	逻辑线程	3.2.0
worklet.scrollViewContext	NodesRef.ref() + SharedValue	UI 线程	3.3.0

获取实例

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

我想要...	查阅文档
查看 ScrollViewContext 全部方法和属性	api/scroll-view-context.md
了解 DraggableSheetContext.scrollTo 参数	api/draggable-sheet-context.md
在 worklet 中控制滚动	api/worklet-scroll-context.md
查看完整代码模式（刷新、二级、Sheet 控制）	patterns.md

强制规则

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 方法速查

方法	说明	最低基础库
scrollTo({ top, left, velocity, duration, animated })	滚动至指定位置	2.14.4
scrollIntoView(selector, options?)	滚动至指定元素	2.14.4
triggerRefresh({ duration?, easingFunction? })	触发下拉刷新	3.0.0
closeRefresh()	关闭下拉刷新	3.0.0
triggerTwoLevel({ duration?, easingFunction? })	触发下拉二级	3.0.0
closeTwoLevel({ duration?, easingFunction? })	关闭下拉二级	3.0.0

ScrollViewContext 属性速查

属性	类型	说明
scrollEnabled	boolean	滚动开关
bounces	boolean	边界弹性（仅 iOS）
showScrollbar	boolean	显示滚动条
pagingEnabled	boolean	分页滑动
fastDeceleration	boolean	快速减速（仅 iOS）
decelerationDisabled	boolean	取消滚动惯性（仅 iOS）

场景决策表

场景	推荐 API
程序化触发下拉刷新	ScrollViewContext.triggerRefresh()
数据加载完成后关闭刷新	ScrollViewContext.closeRefresh()
打开/关闭下拉二级	triggerTwoLevel() / closeTwoLevel()
滚动到指定偏移量	ScrollViewContext.scrollTo({ top })
滚动到指定元素	ScrollViewContext.scrollIntoView(selector)
控制 DraggableSheet 位置	DraggableSheetContext.scrollTo({ size })
UI 线程中控制滚动（配合手势）	worklet.scrollViewContext.scrollTo()

程序化刷新最小示例

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

相关技能

场景	推荐技能	说明
scroll-view 组件属性和事件	skyline-components	scroll-view/draggable-sheet 组件详解
Worklet 动画系统	skyline-worklet	SharedValue、timing/spring、worklet 基础
页面转场路由	skyline-route	自定义路由、预设路由
Skyline 概览与迁移	skyline-overview	渲染引擎概览、兼容性

References 目录结构

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