uni.pageScrollTo(options)

将页面滚动到目标位置

可以滚动到指定的scrollTop值处，也可以滚动到指定的目标元素处（通过css选择器selector）, 仅支持一级 class。

本API滚动的是栈顶的页面。

app-uvue下，其实没有页面级滚动。但本API做了一定兼容，当页面的根元素为scroll-view时，本API也会滚动该scroll-view。详见

pageScrollTo 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.91	4.11

参数

名称	类型	必填	默认值	兼容性	描述
options	PageScrollToOptions	是	-	-	-
名称 类型 必备 默认值 兼容性 描述 scrollTop number 否 - Web 微信小程序 Android iOS - 4.41 - - 滚动到页面的目标位置 selector string 否 - Web 微信小程序 Android iOS - 4.41 - - 选择器 offsetTop number 否 - Web 微信小程序 Android iOS 4.0 4.41 3.91 4.11 偏移距离，可以滚动到 selector 加偏移距离的位置 duration number 否 - Web 微信小程序 Android iOS - 4.41 - - 滚动动画的时长 success (result: AsyncApiSuccessResult) => void 否 - Web 微信小程序 Android iOS - 4.41 - - 接口调用成功的回调函数 fail (result: PageScrollToFail) => void 否 - Web 微信小程序 Android iOS - 4.41 - - 接口调用失败的回调函数 complete (result: AsyncApiResult) => void 否 - Web 微信小程序 Android iOS - 4.41 - - 接口调用结束的回调函数（调用成功、失败都会执行）

AsyncApiSuccessResult 的属性值

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

PageScrollToFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	-	设置页面滚动错误码 - 4: 框架内部异常
errSubject	string	是	-	-	统一错误主题（模块）名称
data	any	否	-	-	错误信息中包含的数据
cause	Error	否	-	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	-	-

AsyncApiResult 的属性值

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

scrollTop 和 selector 必须指定其中一个属性，否者触发 fail 回调

返回值

类型	必备
Promise<AsyncApiSuccessResult>	否
名称 类型 必备 默认值 兼容性 描述 errMsg string 是 - - -

示例

hello uni-app x

扫码体验（手机浏览器跳转到App直达页）

扫码体验

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1" scroll-with-animation="true">
  <!-- #endif -->
    <view class="uni-padding-wrap">
      <page-head :title="title"></page-head>
      <button type="default" class="btn-scrollTo" @click="scrollTo">
        scrollTo
      </button>
      <button type="default" class="btn-scrollToElement" @click="scrollToElement">
        scrollToElement
      </button>
      <view class="uni-list" v-for="(_, index) in 10" :key="index">
        <view class="uni-list-cell list-item">{{ index }}</view>
      </view>
      <view class="custom-element">scrollTo-custom-element</view>
      <view class="uni-list" v-for="(_, index2) in 10" :key="index2">
        <view class="uni-list-cell list-item">{{ index2 }}</view>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>



<style>
  .list-item {
    height: 100px;
    padding-left: 30px;
  }
</style>

参见

• 相关 Bug
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

selector 语法

selector类似于 CSS 的选择器，但仅支持下列语法。

• ID选择器：#the-id
• class选择器（可以连续指定多个）：.a-class.another-class
• 子元素选择器：.the-parent > .the-child
• 后代选择器：.the-ancestor .the-descendant
• 跨自定义组件的后代选择器：.the-ancestor >>> .the-descendant
• 多选择器的并集：#a-node, .some-other-nodes

uni-app x 注意事项

1. app-uvue支持的选择器较少，不支持ID选择器，详见
2. app-uvue的页面滚动，是由页面最外层的scroll-view模拟的，如果页面最外层不是scroll-view，无法使用本api。详见
3. app-uvue的scroll-view滚动时，如需动画，则需要在scroll-view的属性中配置 scroll-with-animation="true"，详见
4. scroll-view的滚动，设置其scrollTop即可。详见

示例

uni.pageScrollTo({
	scrollTop: 0,
	duration: 300
});

通用类型

GeneralCallbackResult

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	Web 微信小程序 Android iOS - 4.41 - -	错误信息