n-back-top 返回顶部

页面或滚动容器下滑超过阈值后出现的返回顶部按钮：页面滚动时组件自动回顶，滚动容器场景由调用方控制回顶；图标、文字、形状、尺寸、位置与外观均可配置。

平台兼容性

App	Web	微信小程序
✓	✓	✓

自动模式依赖页面滚动（onPageScroll）；scroll-view 等容器滚动不触发页面滚动回调，此类场景请传入容器滚动位置。默认形态为图标 + 提示文字（文字跟随语言），显式传空字符串可只保留图标。组件根据当前滚动位置和阈值实时计算显隐，修改阈值或切换自动/受控模式会立即更新。组件可自动避让 n-page 的固定 footer；其他固定底栏或 tabbar 请通过 bottom 设置距离。

基本用法

页面级场景零接线，组件自动监听页面滚动，超过阈值出现、点击回顶：

<template>
　　<n-back-top />
</template>

scroll-view 等容器滚动场景，把容器的滚动位置受控传入，点击回调里自行控制容器回顶：

<template>
　　<scroll-view :scroll-top="scrollTop" @scroll="onScroll">
　　　　<!-- 长内容 -->
　　</scroll-view>
　　<n-back-top :scroll-top="scrollTop" @click="scrollTop = 0" />
</template>
<script setup lang="uts">
　　const scrollTop = ref(0);
　　function onScroll(event: UniScrollEvent): void {
　　　　scrollTop.value = event.detail.scrollTop;
　　}
</script>

自定义内容用默认插槽整钮替换（出现时机、定位与点击回顶仍由组件负责）：

<n-back-top>
　　<image src="/static/top.png" style="width:24px;height:24px" />
</n-back-top>

API

属性

属性	类型	默认值	说明
scroll-top	number | string | null	null	滚动位置受控值（scroll-view 等容器滚动场景，由容器滚动回调传入）；null 时自动监听页面滚动
threshold	number | string	320	显示阈值：滚动位置大于该值时显示按钮；字符串须为数字
top	number | string | null	null	显示阈值别名，兼容 top 命名；同时设置 top 与 threshold 时以 top 为准
duration	number | string	100	回到顶部的滚动动画时长（毫秒），0 表示立即到位；字符串须为数字
shape	string	"circle"	按钮形状，合法值 circle / square，非法值按 circle 处理；参考源已标注废弃的 mode 由此属性承接
icon	string	"up"	图标名（n-icon 内置表或 registerIconFont 注册名）或图片路径（含 / 时按图片渲染）；空字符串不渲染图标
text	string | null	null	图标下方的文字；null 使用内置文案（跟随语言），空字符串不渲染；与图标纵排
size	number | string	-1	按钮最小宽高，数字或 px/rpx 字符串；-1 使用主题尺寸（48px），文字较宽时宽度自适应撑开
width	number | string	-1	固定宽度；-1 使用 size 作为最小宽度，文字较宽时仍可撑开
height	number | string	-1	固定高度；-1 使用 size 作为最小高度
bottom	number | string	100	距视口底部的距离，数字或 px/rpx 字符串；n-page 有固定 footer 时取该值与 footer 预留高度的较大值
right	number | string	20	距视口右侧的距离，数字或 px/rpx 字符串
background	string	""	背景色；参考源同功能属性名为 bgColor，本库采用 background 命名；空字符串使用主题表面色（深浅自适应）
icon-color	string	""	图标颜色；空字符串使用主题文字色
text-color	string	""	文字颜色；空字符串使用主题次要文字色
icon-size	number | string	-1	图标尺寸，数字或 px/rpx 字符串；-1 使用主题尺寸（19px）
text-size	number | string	-1	文字字号，数字或 px/rpx 字符串；-1 使用主题字号（12px）
z-index	number | string	100	层级；字符串须为整数
custom-class	string	""	挂到根节点的额外 class（类须在组件样式表内定义，页面 class 打不进组件）
custom-style	string	""	根节点行内样式

事件

事件	参数	说明
click	UniEvent	点击按钮时触发，参数为原生事件；自动页面模式已执行 pageScrollTo，受控模式由调用方处理容器回顶
error		配置非法时触发，参数为 {prop, message}；非法期间按钮不渲染，修正后按当前滚动位置立即恢复

插槽

名称	说明	参数
default	整钮替换按钮内容（任意节点形态）；点击统一回顶，定位与出现时机仍由组件承担	—

实现说明（机制对照）

机制	参考做法	本库做法	分歧理由
显隐来源	两参考为受控值 + 阈值（页面回调传值）；另一参考为容器上下文自动 / 受控值双通道	scrollTop=null 自动监听页面滚动（官方页面生命周期，组件内合法），传值后受控	与参考双通道语义一致；自动通道不依赖页面容器体系，页面级场景零接线
显隐与滚动值	两家参考用 scrollTop 表示受控滚动值，分别用 top / threshold 表示阈值；另一家的 top 表示受控滚动值，阈值为屏高减 100	scrollTop 统一表示受控滚动值；threshold 为阈值，并提供 top 阈值别名；同时设置 top 与 threshold 时 top 优先	解决参考中 top 命名冲突：保留前者的 top 阈值语义，后者同类受控滚动能力由 scrollTop 承接；阈值默认采用前者的 320
回顶动作	内部 pageScrollTo + duration / 固定 120ms；另一参考走容器上下文	自动页面模式调用 uni.pageScrollTo({scrollTop:0, duration})，duration 默认 100 可调；受控模式只发 click，由调用方操作容器	页面和容器滚动目标不同，避免容器模式误滚页面
形状	一家参考 shape 取 circle / square（mode 已标注废弃）；另两家固定圆形	shape 取 circle / square	跟随未废弃的官方属性名
按钮	width/height 独立 / 固定宽度	size 最小宽高，width/height 可选覆盖；文字较宽时宽度自适应	保留参考独立尺寸能力，同时支持文字内容自然撑开
位置	bottom / right 属性；一家参考根据自有 tabbar / footer 上下文偏移，另两家使用固定默认值	bottom/right 数字或 px/rpx 字符串；位于 n-page 内时自动避开其固定 footer，其他固定底栏由 bottom 调整	自动测量复用本库 n-page 的 footer 上下文；不依赖或猜测调用方自建 tabbar/footer 的尺寸
外观	图标/文字尺寸颜色与背景逐项 prop	background / iconColor / textColor / iconSize / textSize，空值走主题令牌（深浅自适应）	同参对齐；空值令牌化承接深浅主题
进出场	参考直接显隐	阈值控制挂载与卸载，不附加动画	对齐参考直接显隐，隐藏态不留透明节点拦截页面触摸
事件	click	click	另一参考的 backTop 改名对齐库内统一命名
默认值口径	duration 100 / 一家参考 top=400 / 另一家 threshold=320 / bottom 100 / right 20 / width/height 48 / zIndex 100 / iconSize 19	duration 100；threshold=320 取第二家默认，top 默认 null 为阈值别名（显式 top 优先）；bottom 100 / right 20 / size 48 / zIndex 100 / iconSize 主题 19	冲突默认值择用 threshold=320 一方；其余默认跟随另一参考官方值
提示文字默认	text 默认"返回"（图标+文字默认形态）	text 默认 null 走语言包内置文案（跟随语言切换），显式空串只保留图标	同一默认形态；文案经 locale 承接多语言
图标来源	图标名或图片路径	同支持：值含路径分隔符按图片渲染，其余按图标字体名	与参考一致的判别口径
插槽语义	default 自定义按钮的所有内容	default 整钮替换；点击统一回顶（返回顶部是按钮唯一语义）	与参考一致；不提供按钮组形态（那是悬浮动作按钮组件的场景）