## 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
属性
条目 {{ index }}
方法
scrollTo
条目 {{ index }}
scrollIntoView
{{ index == 2 ? '目标条目' : '条目 ' + index }}
triggerRefresh / closeRefresh
条目 {{ index }}
triggerTwoLevel / closeTwoLevel
:refresher-two-level-enabled="true"
refresher-default-style="none"
>
条目 {{ index }}
二级面板
```
:::