Skyline 滚动控制 API 技能面向微信小程序 Skyline 渲染引擎,提供滚动相关的程序化控制能力文档。
适用场景 该技能覆盖以下场景:程序化触发 scroll-view 下拉刷新或关闭刷新;程序化触发或关闭下拉二级(即“二楼”页面);通过 ScrollViewContext 控制滚动位置和行为;控制 DraggableSheet 半屏面板滚动到指定位置;在 worklet 函数(UI 线程)中直接控制 scroll-view 滚动。
核心概念 技能涉及三大 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() 获取;DraggableSheetContext 使用同样方式选择 .sheet 节点获取;worklet.scrollViewContext 需先通过 wx.worklet.shared() 创建 SharedValue,再用 createSelectorQuery().select().ref() 将 res.ref 存入其中。
主要能力 ScrollViewContext 提供方法包括 scrollTo(滚动至指定位置,支持 top、left、velocity、duration、animated)、scrollIntoView(滚动至指定元素)、triggerRefresh(触发下拉刷新)、closeRefresh(关闭下拉刷新)、triggerTwoLevel(触发下拉二级)、closeTwoLevel(关闭下拉二级)。属性包括 scrollEnabled、bounces(仅 iOS)、showScrollbar、pagingEnabled、fastDeceleration(仅 iOS)、decelerationDisabled(仅 iOS)。DraggableSheetContext 提供 scrollTo,可传入 size(相对位置)或 pixels(绝对位置)。worklet.scrollViewContext 提供 scrollTo,用于 UI 线程滚动控制。
强制规则 必须遵守的规则包括:scroll-view 必须开启 enhanced 属性才能获取 ScrollViewContext;DraggableSheetContext.scrollTo 中 size 和 pixels 同时传入时仅 size 生效,应二选一;worklet.scrollViewContext 必须通过 NodesRef.ref 获取引用并存入 SharedValue,而非使用 node();调用 worklet.scrollViewContext.scrollTo 的函数必须声明 'worklet' 指令。禁止行为包括:不得在逻辑线程中调用 worklet.scrollViewContext.scrollTo,该 API 仅在 UI 线程可用;不得在小程序插件中使用 worklet.scrollViewContext.scrollTo,该 API 不支持小程序插件。
场景决策参考 程序化触发下拉刷新使用 ScrollViewContext.triggerRefresh();数据加载完成后关闭刷新使用 closeRefresh();打开或关闭下拉二级使用 triggerTwoLevel() / closeTwoLevel();滚动到指定偏移量使用 scrollTo({ top });滚动到指定元素使用 scrollIntoView(selector);控制 DraggableSheet 位置使用 DraggableSheetContext.scrollTo({ size });UI 线程中配合手势控制滚动使用 worklet.scrollViewContext.scrollTo()。
示例 程序化刷新最小示例:通过 wx.createSelectorQuery().select('#sv').node().exec() 获取 ctx,调用 ctx.triggerRefresh({ duration: 300 }),数据加载完成后调用 ctx.closeRefresh()。
文档结构 技能文档包含 api/scroll-view-context.md、api/draggable-sheet-context.md、api/worklet-scroll-context.md 三个 API 文档及 patterns.md 完整代码模式文档。
相关技能 可配合 scroll-view 组件属性和事件(skyline-components)、Worklet 动画系统(skyline-worklet)、页面转场路由(skyline-route)、Skyline 概览与迁移(skyline-overview)使用。
限制 worklet.scrollViewContext 不支持小程序插件,且仅能在 UI 线程调用;部分属性仅 iOS 生效;各 API 有最低基础库版本要求。关于收费、价格等信息,资料中暂未提供。