skyline-scroll-api（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