uView Pro X

简体中文

English

简体中文

English

主题

BackTop 返回顶部 ​

17:06

说明 ​

滚动超过 top 阈值后出现的返回顶部按钮，点击以 duration 指定的时长平滑滚回顶部。App / H5 端组件自跟踪页面滚动，无需绑定 scrollTop；微信小程序自定义组件拿不到页面 onPageScroll，需在页面监听后手动传入 scrollTop。支持 square / circle 两档形状、自定义图标与提示文字。

兼容性 ​

平台支持情况
App✅ 支持（额外支持 parentId 指定 scroll-view 容器内返回顶部）
H5✅ 支持
微信小程序✅ 支持（组件内不监听页面滚动，需在页面 onPageScroll 中把滚动距离传给 scroll-top）

示例 ​

基础用法 ​

滚动页面后，右下角会出现返回顶部按钮。点击按钮平滑滚动回顶部。

查看源码
vue
<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <!-- 页面滚动超过 200px 后显示返回顶部按钮 -->
        <ux-back-top :scroll-top="scrollTop" :top="200" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

自定义形状 shape ​

shape="square" 小圆角（4px，默认），shape="circle" 正圆。需要真直角时用 custom-style 内联 border-radius: 0。

查看源码
vue
<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <!-- 两档形状全演示：square 小圆角（4px，不传即此档） / circle 正圆；
             组件为 position:fixed，靠 bottom/right 错开才能并排看到两个 -->
        <ux-back-top :scroll-top="scrollTop" :top="200" shape="square" tips="小圆角" :bottom="210" :right="20" />
        <ux-back-top :scroll-top="scrollTop" :top="200" shape="circle" tips="正圆" :bottom="210" :right="70" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

提示文字 tips ​

通过 tips 属性设置按钮下方的提示文字。

查看源码
vue
<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <ux-back-top :scroll-top="scrollTop" :top="200" tips="顶部" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

自定义位置 bottom / right ​

通过 bottom 和 right 属性调整按钮的位置，单位 px。

查看源码
vue
<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <ux-back-top :scroll-top="scrollTop" :top="200" :bottom="150" :right="100" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

自定义图标样式 icon-style ​

通过 icon-style 属性自定义图标的颜色和大小。

查看源码
vue
<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <ux-back-top
            :scroll-top="scrollTop"
            :top="200"
            :bottom="150"
            :right="150"
            :icon-style="{ color: '#2979ff', fontSize: '21px' }"
        />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

滚动测试 ​

向下滚动页面，观察返回顶部按钮的显示和隐藏动画。

API ​

Props ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
shape按钮形状（词表见 types/global.uts 的 BackTopShape）：square-小圆角(4px，默认) | circle-正圆BackTopShape'square'-
icon自定义图标string'arrow-upward'-
tips提示文字string''-
duration返回顶部滚动时间number | string100-
scrollTop滚动距离number | string0-
top距离顶部多少距离显示，单位pxnumber | string200-
bottom返回顶部按钮到底部的距离，单位pxnumber | string100-
right返回顶部按钮到右边的距离，单位pxnumber | string20-
parentIdApp 端 scroll-view 容器的 id，用于容器内返回顶部；缺省时用 uni.pageScrollTo（页面滚动）string''-
zIndex层级number | string'9'-
iconStyle图标的样式，对象形式UTSJSONObject--

Events ​

事件名说明回调参数版本
click点击按钮时触发--

Slots ​

插槽名说明版本
default自定义按钮内容（默认显示图标与提示文字）-

注意事项 ​

  • 显示阈值：滚动距离需大于 top（默认 200px）才出现按钮；top / bottom / right 单位均为 px。
  • 微信小程序端自定义组件不支持页面 onPageScroll，必须在页面里监听滚动并把距离传给 scroll-top；App / H5 端组件自跟踪页面滚动，无需传。
  • parentId 仅在 App 端生效，用于滚动发生在 scroll-view 容器内（如演示页容器）时；页面级滚动无需传，走 uni.pageScrollTo。
  • 形状只有 square（小圆角 4px）/ circle（正圆）两档；直角或其它圆角用 custom-style 内联 border-radius（内联优先级高于形状类）。
  • 组件为 position: fixed，同时使用多个实例需用 bottom / right 错开，否则会重叠。
  • icon-style 可设 fontSize 调整图标大小；未指定 color 时图标回退到主题 tips 色。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5