skyline-scroll-api

Skyline scroll control API

Applicable scenarios

• Programmatically trigger scroll-view pull-to-refresh or close refresh
• Programmatically trigger/close pull-down secondary ("second floor" page)
• Control scroll position and behavior via ScrollViewContext
• Control DraggableSheet half-screen panel to scroll to a specified position
• Directly control scroll-view scrolling in a worklet function (UI thread)

Core concepts

Three major API families

API family	How to obtain	Thread	Minimum base library
ScrollViewContext	NodesRef.node() + enhanced property	Logic thread	2.14.4
DraggableSheetContext	NodesRef.node()	Logic thread	3.2.0
worklet.scrollViewContext	NodesRef.ref() + SharedValue	UI thread	3.3.0

Obtain instance

// 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()

Documentation index

Quickly locate based on needs (path relative to references/）：

I want to...	Consult documentation
View all methods and properties of ScrollViewContext	api/scroll-view-context.md
Learn about DraggableSheetContext.scrollTo parameters	api/draggable-sheet-context.md
Control scrolling in a worklet	api/worklet-scroll-context.md
View complete code patterns (refresh, secondary, Sheet control)	patterns.md

Mandatory rules

MUST (must comply)

1. scroll-view must enable the enhanced property to obtain ScrollViewContext：

   <!-- ❌ 错误：未开启 enhanced，node() 返回的不是 ScrollViewContext -->
   <scroll-view type="list" scroll-y>
   
   <!-- ✅ 正确 -->
   <scroll-view type="list" scroll-y enhanced>
   

2. When both size and pixels are passed in DraggableSheetContext.scrollTo, only size takes effect：

   // ❌ 错误：同时传入 size 和 pixels，pixels 被忽略
   sheetContext.scrollTo({ size: 0.7, pixels: 200 })
   
   // ✅ 正确：二选一
   sheetContext.scrollTo({ size: 0.7 })   // 相对位置
   sheetContext.scrollTo({ pixels: 200 }) // 绝对位置
   

3. worklet.scrollViewContext must be obtained via NodesRef.ref to get a reference and store it in a 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. Functions that call worklet.scrollViewContext.scrollTo must declare the 'worklet' directive：

   // ❌ 错误：缺少 worklet 指令
   onTap() {
     scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
   }
   
   // ✅ 正确
   onTap() {
     'worklet'
     scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
   }
   

NEVER (prohibited actions)

1. NEVER Call worklet.scrollViewContext.scrollToon the logic thread—this API is only available on the UI thread (inside a worklet function)
2. NEVER Use worklet.scrollViewContext.scrollToin a Mini Program plugin—this API does not support Mini Program plugins

Quick Reference

ScrollViewContext method quick reference

Method	Description	Minimum base library
scrollTo({ top, left, velocity, duration, animated })	Scroll to a specified position	2.14.4
scrollIntoView(selector, options?)	Scroll to a specified element	2.14.4
triggerRefresh({ duration?, easingFunction? })	Trigger pull-to-refresh	3.0.0
closeRefresh()	Close pull-to-refresh	3.0.0
triggerTwoLevel({ duration?, easingFunction? })	Trigger pull-down secondary	3.0.0
closeTwoLevel({ duration?, easingFunction? })	Close pull-down secondary	3.0.0

ScrollViewContext property quick reference

Property	Type	Description
scrollEnabled	boolean	Scroll switch
bounces	boolean	Boundary elasticity (iOS only)
showScrollbar	boolean	Show scrollbar
pagingEnabled	boolean	Paging scroll
fastDeceleration	boolean	Fast deceleration (iOS only)
decelerationDisabled	boolean	Cancel scroll inertia (iOS only)

Scenario decision table

Scenario	Recommended API
Programmatically trigger pull-to-refresh	ScrollViewContext.triggerRefresh()
Close refresh after data loading completes	ScrollViewContext.closeRefresh()
Open/close pull-down secondary	triggerTwoLevel() / closeTwoLevel()
Scroll to a specified offset	ScrollViewContext.scrollTo({ top })
Scroll to a specified element	ScrollViewContext.scrollIntoView(selector)
Control DraggableSheet position	DraggableSheetContext.scrollTo({ size })
Control scrolling in the UI thread (with gestures)	worklet.scrollViewContext.scrollTo()

Minimal programmatic refresh example

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

Related skills

Scenario	Recommended skill	Description
scroll-view component properties and events	skyline-components	Detailed explanation of the scroll-view/draggable-sheet components
Worklet animation system	skyline-worklet	SharedValue, timing/spring, worklet basics
Page transition routing	skyline-route	Custom routing, preset routing
Skyline overview and migration	skyline-overview	Rendering engine overview, compatibility

References directory structure

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