skyline-scroll-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skyline 滚动控制 API

适用场景

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

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

核心概念

三大 API 族群

API 族群	获取方式	线程	最低基础库
ScrollViewContext	`NodesRef.node()` + `enhanced` 属性	逻辑线程	2.14.4
DraggableSheetContext	`NodesRef.node()`	逻辑线程	3.2.0
worklet.scrollViewContext	`NodesRef.ref()` + SharedValue	UI 线程	3.3.0

API 族群	获取方式	线程	最低基础库
ScrollViewContext	`NodesRef.node()` + `enhanced` 属性	逻辑线程	2.14.4
DraggableSheetContext	`NodesRef.node()`	逻辑线程	3.2.0
worklet.scrollViewContext	`NodesRef.ref()` + SharedValue	UI 线程	3.3.0

获取实例

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

// 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`

根据需求快速定位（路径相对于

references/

）：

我想要...	查阅文档
查看 ScrollViewContext 全部方法和属性	`api/scroll-view-context.md`
了解 DraggableSheetContext.scrollTo 参数	`api/draggable-sheet-context.md`
在 worklet 中控制滚动	`api/worklet-scroll-context.md`
查看完整代码模式（刷新、二级、Sheet 控制）	`patterns.md`

强制规则

MUST（必须遵守）

scroll-view 必须开启
enhanced
属性才能获取 ScrollViewContext：

html

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

<!-- ✅ 正确 -->
<scroll-view type="list" scroll-y enhanced>

DraggableSheetContext.scrollTo 中 size 和 pixels 同时传入时，仅 size 生效：

// ❌ 错误：同时传入 size 和 pixels，pixels 被忽略
sheetContext.scrollTo({ size: 0.7, pixels: 200 })

// ✅ 正确：二选一
sheetContext.scrollTo({ size: 0.7 })   // 相对位置
sheetContext.scrollTo({ pixels: 200 }) // 绝对位置

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

调用 worklet.scrollViewContext.scrollTo 的函数必须声明
'worklet'
指令：

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

// ✅ 正确
onTap() {
  'worklet'
  scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
}

scroll-view 必须开启
enhanced
属性才能获取 ScrollViewContext：

html

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

<!-- ✅ 正确 -->
<scroll-view type="list" scroll-y enhanced>

DraggableSheetContext.scrollTo 中 size 和 pixels 同时传入时，仅 size 生效：

// ❌ 错误：同时传入 size 和 pixels，pixels 被忽略
sheetContext.scrollTo({ size: 0.7, pixels: 200 })

// ✅ 正确：二选一
sheetContext.scrollTo({ size: 0.7 })   // 相对位置
sheetContext.scrollTo({ pixels: 200 }) // 绝对位置

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

调用 worklet.scrollViewContext.scrollTo 的函数必须声明
'worklet'
指令：

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

// ✅ 正确
onTap() {
  'worklet'
  scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
}

NEVER（禁止行为）

NEVER 在逻辑线程中调用
```
worklet.scrollViewContext.scrollTo
```
——该 API 仅在 UI 线程（worklet 函数内）可用
NEVER 在小程序插件中使用
```
worklet.scrollViewContext.scrollTo
```
——该 API 不支持小程序插件

NEVER 在逻辑线程中调用
```
worklet.scrollViewContext.scrollTo
```
——该 API 仅在 UI 线程（worklet 函数内）可用
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

方法	说明	最低基础库
`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 属性速查

属性	类型	说明
scrollEnabled	boolean	滚动开关
bounces	boolean	边界弹性（仅 iOS）
showScrollbar	boolean	显示滚动条
pagingEnabled	boolean	分页滑动
fastDeceleration	boolean	快速减速（仅 iOS）
decelerationDisabled	boolean	取消滚动惯性（仅 iOS）

属性	类型	说明
scrollEnabled	boolean	滚动开关
bounces	boolean	边界弹性（仅 iOS）
showScrollbar	boolean	显示滚动条
pagingEnabled	boolean	分页滑动
fastDeceleration	boolean	快速减速（仅 iOS）
decelerationDisabled	boolean	取消滚动惯性（仅 iOS）

场景决策表

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

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

程序化刷新最小示例

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

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

场景	推荐技能	说明
scroll-view 组件属性和事件	`skyline-components`	scroll-view/draggable-sheet 组件详解
Worklet 动画系统	`skyline-worklet`	SharedValue、timing/spring、worklet 基础
页面转场路由	`skyline-route`	自定义路由、预设路由
Skyline 概览与迁移	`skyline-overview`	渲染引擎概览、兼容性

场景	推荐技能	说明
scroll-view 组件属性和事件	`skyline-components`	scroll-view/draggable-sheet 组件详解
Worklet 动画系统	`skyline-worklet`	SharedValue、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

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

skyline-scroll-api

Original

Translation

Skyline 滚动控制 API

Skyline 滚动控制 API

适用场景

适用场景

核心概念

核心概念

三大 API 族群

三大 API 族群

获取实例

获取实例

文档索引

文档索引

强制规则

强制规则

MUST（必须遵守）

MUST（必须遵守）

NEVER（禁止行为）

NEVER（禁止行为）

Quick Reference

Quick Reference

ScrollViewContext 方法速查

ScrollViewContext 方法速查

ScrollViewContext 属性速查

ScrollViewContext 属性速查

场景决策表

场景决策表

程序化刷新最小示例

程序化刷新最小示例

相关技能

相关技能

References 目录结构

References 目录结构