wechat-miniprogram/skyline-skills

skyline-scroll-api

Skyline 滚动控制 API 技能。涵盖 ScrollViewContext(程序化下拉刷新、下拉二级、滚动定位)、DraggableSheetContext(半屏面板程序化滚动)、worklet.scrollViewContext(UI 线程直接控制滚动)。适用于程序化触发刷新/二级、控制 DraggableSheet 位置、在 worklet 中操作滚动。触发关键词:ScrollViewContext、DraggableSheetContext、scrollTo、triggerRefresh、trig…

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/wechat-miniprogram/skyline-skills --skill skyline-scroll-api

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Skyline 滚动控制 API

适用场景

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

核心概念

三大 API 族群

API 族群获取方式线程最低基础库
ScrollViewContextNodesRef.node() + enhanced 属性逻辑线程2.14.4
DraggableSheetContextNodesRef.node()逻辑线程3.2.0
worklet.scrollViewContextNodesRef.ref() + SharedValueUI 线程3.3.0

获取实例

js
// 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:
html
   <!-- ❌ 错误:未开启 enhanced,node() 返回的不是 ScrollViewContext -->
   <scroll-view type="list" scroll-y>

   <!-- ✅ 正确 -->
   <scroll-view type="list" scroll-y enhanced>
  1. 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 }) // 绝对位置
  1. 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()
  1. 调用 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 })滚动至指定位置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 属性速查

属性类型说明
scrollEnabledboolean滚动开关
bouncesboolean边界弹性(仅 iOS)
showScrollbarboolean显示滚动条
pagingEnabledboolean分页滑动
fastDecelerationboolean快速减速(仅 iOS)
decelerationDisabledboolean取消滚动惯性(仅 iOS)

场景决策表

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

程序化刷新最小示例

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

相关技能

场景推荐技能说明
scroll-view 组件属性和事件skyline-componentsscroll-view/draggable-sheet 组件详解
Worklet 动画系统skyline-workletSharedValue、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
같은 저장소의 Skills

더 많은 Skills

모든 Skills