skyline-scroll-api

Q: How do I install skyline-scroll-api?

Run npx skills add https://github.com/wechat-miniprogram/skyline-skills --skill skyline-scroll-api in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/skyline-scroll-api/ (personal) or .claude/skills/skyline-scroll-api/ (project).

by wechat-miniprogramBackend & APIs

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

Installs: 916
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/wechat-miniprogram/skyline-skills --skill skyline-scroll-api

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads skyline-scroll-api automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Skyline 滚动控制 API

适用场景

程序化触发 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

获取实例

// 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（必须遵守）

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

<!-- ❌ 错误：未开启 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 不支持小程序插件

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 属性速查

属性	类型	说明
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()`

程序化刷新最小示例

// 获取 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`	渲染引擎概览、兼容性

References 目录结构

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

FAQ

What does the skyline-scroll-api skill do?

How do I install skyline-scroll-api?

Run npx skills add https://github.com/wechat-miniprogram/skyline-skills --skill skyline-scroll-api in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/skyline-scroll-api/ (personal) or .claude/skills/skyline-scroll-api/ (project).

Which AI agents can use skyline-scroll-api?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is skyline-scroll-api safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains skyline-scroll-api?

It is published by wechat-miniprogram in wechat-miniprogram/skyline-skills. It has 916 recorded installs.