## ScrollViewContext 滚动组件的上下文对象,用于控制滚动位置、滚动行为、下拉刷新和下拉二级面板。 ### ScrollViewContext 兼容性 Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 ### 适用组件 - App 蒸汽模式:[scroll-view](../component/scroll-view.md)、[list-view](../component/list-view.md)、[waterflow](../component/waterflow.md)。 - 微信小程序:[scroll-view](../component/scroll-view.md)。 ### 获取方式 通过 [uni.createSelectorQuery()](./create-selector-query.md) 选中滚动组件,调用 `NodesRef.node()` 并执行 `exec()`,在回调结果的 `node` 属性中获取 `ScrollViewContext` 对象。 在组件渲染完成后获取,例如在页面的 `onReady` 中获取 id 为 `scroll-view` 的组件: ```ts onReady(() => { uni.createSelectorQuery() .select('#scroll-view') .node((result) => { if (result != null) { const scrollViewContext = result.node as ScrollViewContext scrollViewContext.scrollTo({ top: 100, animated: true }) } }) .exec() }) ``` ### ScrollViewContext 的属性值 @scrollviewcontext-values | 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | bounces | boolean | 是 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS: x | 设置滚动边界弹性 (仅在 iOS 下生效) | | showScrollbar | boolean | 是 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 是否显示滚动条。 | | scrollEnabled | boolean | 是 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 是否允许手势滚动;关闭后仍可调用滚动方法。 | | pagingEnabled | boolean | 是 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 是否按页停靠。 | | fastDeceleration | boolean | 是 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 设置滚动减速速率。仅微信小程序 iOS 下生效。 | | decelerationDisabled | boolean | 是 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 取消滚动惯性。仅微信小程序 iOS 下生效。 | ### ScrollViewContext 的方法 @scrollviewcontext-methods #### scrollTo(options: ScrollViewScrollToOptions): void @scrollto scrollTo 滚动到指定位置,越界时钳制到可滚动范围。 ##### scrollTo 兼容性 Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 ##### 参数 | 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | options | **ScrollViewScrollToOptions** | 是 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | scrollTo 的目标坐标和动画配置。未指定的坐标保持当前位置。 | #### options 的属性描述 | 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | top | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 垂直滚动位置,单位 px。 | | left | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 水平滚动位置,单位 px。 | | animated | boolean | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 未指定且未传 duration、velocity 时,使用组件的 scroll-with-animation 配置。 | | duration | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 动画时长,单位 ms;显式启用动画时默认 300,小于或等于 0 时立即定位。
微信小程序:WebView 仅 iOS,Skyline 需基础库 3.14.3+。 | | velocity | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 动画初始速度,单位 px/s;负值按 0 处理。
微信小程序:WebView 仅 iOS,Skyline 需基础库 3.14.3+。 | #### scrollIntoView(selector: string, options?: ScrollViewScrollIntoViewOptions): void @scrollintoview scrollIntoView 滚动到当前容器内的目标节点。App 平台 `list-view` 和 `waterflow` 中的目标需已渲染。 微信小程序 options 仅支持 Skyline(基础库 3.1.0+)。 ##### scrollIntoView 兼容性 Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 ##### 参数 | 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | selector | string | 是 | Web: x; 支付宝小程序: x | 元素选择器 | | options | **ScrollViewScrollIntoViewOptions** | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 滚动至容器内目标节点时的配置。 微信小程序仅支持 Skyline(基础库 3.1.0+)。 | #### options 的属性描述 | 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | alignment | string | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 目标与容器视口的对齐方式;默认从起始位置对齐。
微信小程序仅支持 Skyline(基础库 3.1.0+)。 | | offset | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 对齐位置的偏移量,单位 px,默认 0。
微信小程序仅支持 Skyline(基础库 3.1.0+)。 | | animated | boolean | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 | 是否启用滚动动画,默认 true。
微信小程序仅支持 Skyline(基础库 3.1.0+)。 | | withinExtent | boolean | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 是否仅跳转到 cacheExtent 范围内的目标节点,默认 false。
仅微信小程序 Skyline 支持(基础库 3.1.0+)。 | ##### alignment 的属性描述 | 合法值 | 兼容性 | | :- | :-: | | "start" | Web: x; 支付宝小程序: x | | "center" | Web: x; 支付宝小程序: x | | "end" | Web: x; 支付宝小程序: x | | "nearest" | Web: x; 支付宝小程序: x | #### triggerRefresh(options?: ScrollViewRefreshOptions): void @triggerrefresh triggerRefresh 触发下拉刷新。 ##### triggerRefresh 兼容性 Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 ##### 参数 | 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | options | **ScrollViewRefreshOptions** | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画配置。 | #### options 的属性描述 | 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | duration | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画时长,单位 ms;刷新默认 300,二级面板默认 500。 | | easingFunction | string | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画曲线,默认 ease。 | ##### easingFunction 的属性描述 | 合法值 | 兼容性 | | :- | :-: | | "linear" | Web: x; 支付宝小程序: x | | "ease" | Web: x; 支付宝小程序: x | | "ease-in" | Web: x; 支付宝小程序: x | | "ease-out" | Web: x; 支付宝小程序: x | | "ease-in-out" | Web: x; 支付宝小程序: x | #### closeRefresh(): void @closerefresh closeRefresh 关闭下拉刷新。 ##### closeRefresh 兼容性 Web: x; 微信小程序: √; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.36; iOS(VDOM): x; iOS(Vapor): 5.36; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.36 #### triggerTwoLevel(options?: ScrollViewRefreshOptions): void @triggertwolevel triggerTwoLevel 打开下拉二级面板。 ##### triggerTwoLevel 兼容性 Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x ##### 参数 | 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | options | **ScrollViewRefreshOptions** | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画配置。 | #### options 的属性描述 | 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | duration | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画时长,单位 ms;刷新默认 300,二级面板默认 500。 | | easingFunction | string | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画曲线,默认 ease。 | ##### easingFunction 的属性描述 | 合法值 | 兼容性 | | :- | :-: | | "linear" | Web: x; 支付宝小程序: x | | "ease" | Web: x; 支付宝小程序: x | | "ease-in" | Web: x; 支付宝小程序: x | | "ease-out" | Web: x; 支付宝小程序: x | | "ease-in-out" | Web: x; 支付宝小程序: x | #### closeTwoLevel(options?: ScrollViewRefreshOptions): void @closetwolevel closeTwoLevel 关闭下拉二级面板。 ##### closeTwoLevel 兼容性 Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x ##### 参数 | 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | options | **ScrollViewRefreshOptions** | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画配置。 | #### options 的属性描述 | 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | duration | number | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画时长,单位 ms;刷新默认 300,二级面板默认 500。 | | easingFunction | string | 否 | Web: x; 微信小程序: √; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 动画曲线,默认 ease。 | ##### easingFunction 的属性描述 | 合法值 | 兼容性 | | :- | :-: | | "linear" | Web: x; 支付宝小程序: x | | "ease" | Web: x; 支付宝小程序: x | | "ease-in" | Web: x; 支付宝小程序: x | | "ease-out" | Web: x; 支付宝小程序: x | | "ease-in-out" | Web: x; 支付宝小程序: x | ### 示例 示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/component/scroll-view/scroll-view-context/scroll-view.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/component/scroll-view/scroll-view-context/scroll-view.uvue) > > 该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验 ::: preview > appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/component/scroll-view/scroll-view-context/scroll-view ```uvue ``` :::