wechat-miniprogram/skyline-skills

skyline-scroll-api

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

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/wechat-miniprogram/skyline-skills --skill skyline-scroll-api

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

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
del mismo repositorio

Más Skills

Todos los Skills