Page Scroll To

::: sourceCode

uni.pageScrollTo(options) @pagescrollto

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-pageScrollTo

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-pageScrollTo

:::

将页面滚动到目标位置

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

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

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

pageScrollTo 兼容性

参数

options 的属性描述

PageScrollToSuccess 的属性值 @pagescrolltosuccess-values

PageScrollToFail 的属性值 @pagescrolltofail-values

• 4: 框架内部异常 | | errSubject | string | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 统一错误主题（模块）名称 | | data | any | 否 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 错误信息中包含的数据 | | cause | Error | 否 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 源错误信息，可以包含多个错误，详见SourceError | | errMsg | string | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | |

PageScrollToComplete 的属性值 @pagescrolltocomplete-values

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

返回值

Promise<PageScrollToSuccess> 的属性描述

示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见 ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/page-scroll-to/page-scroll-to

appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/page-scroll-to/page-scroll-to

示例

<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>

<script setup lang="uts">
  const title = ref('pageScrollTo')

  const scrollTo = () => {
    uni.pageScrollTo({
      scrollTop: 100,
      duration: 300,
      success: () => {
        console.log('success')
      },
    })
  }

  const scrollToElement = () => {
    uni.pageScrollTo({
      selector: '.custom-element',
      duration: 300,
      success: () => {
        console.log('success')
      },
    })
  }

  defineExpose({
    scrollTo
  })

</script>

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

:::

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• 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