skyline-scroll-api

Imported from YYC-Cube/YYC3-Knowledge-Base (YYC3-J/Agent-Skills/skyline/references/scroll-api/SKILL.md). Install upstream with npx skills add YYC-Cube/YYC3-Knowledge-Base --skill scroll-api. Copyright stays with the author.

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/
│   ├── scroll-view-context.md     # ScrollViewContext 完整 API（属性+方法+参数）
│   ├── draggable-sheet-context.md  # DraggableSheetContext.scrollTo 详细参数
│   └── worklet-scroll-context.md   # worklet.scrollViewContext 详细参数与用法
└── patterns.md                     # 滚动 API 代码模式（刷新、二级、Sheet、worklet）