Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Backtop 回到顶部
页面滚动到一定距离后,在右下角显示一个按钮,点了滚回顶部。
引入
import { NsBacktop } from '@ns/ui'
基础用法
不传 target 时监听页面滚动。滚过 visibility-height(默认 200px)后按钮出现,点击平滑滚回顶部。按钮用 position: fixed 定位,默认在浏览器窗口右下角,离右边、下边各 40px。
为了方便看效果,本页的示例都放在固定高度的滚动容器里,用 target 指向这个容器(用法见下面的“自定义滚动容器”);外层示例框加了 transform,让按钮显示在示例框的右下角,实际使用时不用写。在框里往下滚:
<script setup lang="ts">
import { NsBacktop } from '@ns/ui'
</script>
<template>
<div class="demo">
<div id="backtop-demo-basic" class="box">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop target="#backtop-demo-basic" :right="24" :bottom="16" />
</div>
</template>
<style scoped>
/* transform 让按钮相对示例框定位,实际使用时不用写 */
.demo {
transform: translateZ(0);
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
自定义滚动容器
内容在某个可以滚动的元素里时,用 target 指定这个元素,可以传 CSS 选择器或元素。target 必须是真正滚动的那个元素(设了固定高度和 overflow: auto 或 scroll),不能是它外面的包裹元素;选择器找不到时退回监听页面滚动。
<script setup lang="ts">
import { NsBacktop } from '@ns/ui'
</script>
<template>
<div
class="backtop-demo"
style="height: 300px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<div style="height: 1000px; padding: 16px">在这个区域里往下滚动</div>
<NsBacktop target=".backtop-demo" :visibility-height="100" />
</div>
</template>
按钮始终用 position: fixed 定位在浏览器窗口的右下角,不会跟着容器走:上面这个示例的按钮出现在窗口右下角。容器不在右下角时,用 right、bottom 把按钮挪到容器旁边。
位置和显示阈值
right、bottom 是按钮离窗口右边和下边的距离(px),visibility-height 是滚过多少像素后显示按钮。下面三个按钮的阈值分别是 100、300、600px,往下滚时依次出现:
<script setup lang="ts">
import { NsBacktop } from '@ns/ui'
</script>
<template>
<div class="demo">
<div id="backtop-demo-threshold" class="box">
<p v-for="i in 40" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop
target="#backtop-demo-threshold"
:visibility-height="100"
:right="24"
:bottom="16"
text="100px"
/>
<NsBacktop
target="#backtop-demo-threshold"
:visibility-height="300"
:right="24"
:bottom="72"
text="300px"
/>
<NsBacktop
target="#backtop-demo-threshold"
:visibility-height="600"
:right="24"
:bottom="128"
text="600px"
/>
</div>
</template>
<style scoped>
/* transform 让按钮相对示例框定位,实际使用时不用写 */
.demo {
transform: translateZ(0);
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
滚动方式
behavior 可选 smooth(平滑滚动,默认)和 auto(直接跳到顶部)。分别滚下去再点按钮对比:
<script setup lang="ts">
import { NsBacktop, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start">
<div class="demo">
<div id="backtop-demo-smooth" class="box">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop
target="#backtop-demo-smooth"
behavior="smooth"
text="smooth"
:visibility-height="100"
:right="24"
:bottom="16"
/>
</div>
<div class="demo">
<div id="backtop-demo-auto" class="box">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop
target="#backtop-demo-auto"
behavior="auto"
text="auto"
:visibility-height="100"
:right="24"
:bottom="16"
/>
</div>
</NsSpace>
</template>
<style scoped>
/* transform 让按钮相对示例框定位,实际使用时不用写 */
.demo {
width: 260px;
transform: translateZ(0);
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
图标和文字
icon 换按钮的图标(NsIcon 的 name),默认 arrow-up;text 在图标右边加上文字,按钮变成两头半圆的胶囊。
<script setup lang="ts">
import { NsBacktop } from '@ns/ui'
</script>
<template>
<div class="demo">
<div id="backtop-demo-icon" class="box">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop target="#backtop-demo-icon" :visibility-height="100" :right="24" :bottom="16" />
<NsBacktop
target="#backtop-demo-icon"
icon="top"
:visibility-height="100"
:right="80"
:bottom="16"
/>
<NsBacktop
target="#backtop-demo-icon"
icon="chevron-up"
:visibility-height="100"
:right="136"
:bottom="16"
/>
<NsBacktop
target="#backtop-demo-icon"
icon="top"
text="回到顶部"
:visibility-height="100"
:right="24"
:bottom="72"
/>
</div>
</template>
<style scoped>
/* transform 让按钮相对示例框定位,实际使用时不用写 */
.demo {
transform: translateZ(0);
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
自定义内容
默认插槽替换按钮里的全部内容(图标和文字)。组件的根元素本身就是 <button>,插槽里不要再放按钮。
<script setup lang="ts">
import { NsBacktop } from '@ns/ui'
</script>
<template>
<div class="demo">
<div id="backtop-demo-slot" class="box">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop target="#backtop-demo-slot" :visibility-height="100" :right="24" :bottom="16">
<span style="color: var(--ns-color-primary); font-weight: bold">UP</span>
</NsBacktop>
</div>
</template>
<style scoped>
/* transform 让按钮相对示例框定位,实际使用时不用写 */
.demo {
transform: translateZ(0);
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
用 v-model:show 获取显示状态
没传 show 时,按钮是否显示由组件按滚动位置决定(非受控)。滚动越过阈值时,组件会触发 update:show,所以可以用 v-model:show 拿到现在是否显示。按钮实际显示或隐藏时还会触发 show-change;点击按钮时先触发 click,再开始滚动。
<script setup lang="ts">
import { ref } from 'vue'
import { NsBacktop, NsMessage } from '@ns/ui'
const show = ref(false)
const changeCount = ref(0)
const handleShowChange = () => {
changeCount.value += 1
}
const handleClick = () => {
NsMessage.info('点了回到顶部')
}
</script>
<template>
<div class="demo">
<div id="backtop-demo-model" class="box">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop
v-model:show="show"
target="#backtop-demo-model"
:visibility-height="100"
:right="24"
:bottom="16"
@show-change="handleShowChange"
@click="handleClick"
/>
</div>
<p style="margin-top: 12px">
按钮{{ show ? '显示中' : '已隐藏' }},show-change 触发了 {{ changeCount }} 次
</p>
</template>
<style scoped>
/* transform 让按钮相对示例框定位,实际使用时不用写 */
.demo {
transform: translateZ(0);
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
受控显示
只传 :show(不处理 update:show)时是受控模式,按钮显示不显示完全由 show 决定,滚动不会改变它。比如只在某些条件下才允许显示:
<script setup lang="ts">
import { ref } from 'vue'
import { NsBacktop, NsSpace, NsSwitch } from '@ns/ui'
const enabled = ref(false)
const passed = ref(false)
const handleUpdate = (value: boolean) => {
passed.value = value
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsSwitch v-model="enabled" active-text="允许显示回到顶部" />
<span>滚过阈值:{{ passed ? '是' : '否' }}</span>
</NsSpace>
<div class="demo">
<div id="backtop-demo-controlled" class="box">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsBacktop
target="#backtop-demo-controlled"
:visibility-height="100"
:right="24"
:bottom="16"
:show="enabled && passed"
@update:show="handleUpdate"
/>
</div>
</NsSpace>
</template>
<style scoped>
/* transform 让按钮相对示例框定位,实际使用时不用写 */
.demo {
transform: translateZ(0);
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
上面的例子里 update:show 告诉外面有没有滚过阈值,是否显示由 enabled && passed 决定。
键盘操作
按钮是原生的 <button>,可以用 Tab 键聚焦,按回车或空格等同于点击。读屏软件读出的名称是 text,没传 text 时是“回到顶部”。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| target | string | HTMLElement | Window | - | 监听滚动的容器,字符串按 CSS 选择器查找。不传、或选择器找不到时监听页面滚动(window) |
| visibilityHeight | number | 200 | 滚动距离大于等于这个值(px)时显示按钮 |
| right | number | 40 | 按钮离浏览器窗口右边的距离(px) |
| bottom | number | 40 | 按钮离浏览器窗口下边的距离(px) |
| behavior | 'smooth' | 'auto' | 'smooth' | 回到顶部时的滚动方式 |
| show | boolean | - | 是否显示按钮,支持 v-model:show。传了就是受控,显示完全由它决定;不传时按滚动位置自动显示 |
| icon | string | 'arrow-up' | 按钮图标,NsIcon 的 name |
| text | string | - | 图标右边的文字,同时用作按钮的可读名称 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| click | (event: MouseEvent) | 点击按钮(或聚焦后按回车、空格)时触发,在开始滚动之前 |
| update:show | (value: boolean) | 滚动越过 visibilityHeight(从下到上或从上到下)时触发,参数是按滚动位置算出来该不该显示。受控和非受控时都会触发 |
| show-change | (value: boolean) | 按钮实际显示或隐藏时触发。非受控时随滚动触发,受控时随 show 变化触发;挂载时不触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 按钮里的内容,替换默认的图标和文字 |
类型
import type { BacktopProps, BacktopEmits, BacktopTarget, ScrollBehavior } from '@ns/ui'
type BacktopTarget = string | HTMLElement | Window
type ScrollBehavior = 'smooth' | 'auto'
interface BacktopProps {
target?: BacktopTarget
visibilityHeight?: number
right?: number
bottom?: number
behavior?: ScrollBehavior
show?: boolean
icon?: string
text?: string
}
interface BacktopEmits {
click: [event: MouseEvent]
'update:show': [value: boolean]
'show-change': [value: boolean]
}
注意事项
- 受控和非受控的区别:没传
show(或传undefined)是非受控,组件按滚动位置自己显示和隐藏;传了true或false就是受控,滚动只触发update:show,不会改变显示。v-model:show是受控写法,但因为它会接收update:show,效果和非受控一样。 update:show只在滚动位置越过阈值时触发,不会每次滚动都触发。页面加载时已经滚过阈值,挂载后会立即显示(非受控时)并触发一次update:show(true)。- 按钮隐藏时不渲染(
v-if),这时拿不到它的 DOM。 - 按钮的层级是
var(--ns-z-index-fixed)。 - 运行时修改
target,滚动监听会跟着换。 - 服务端渲染时不访问
window,滚动监听在挂载后才绑定,卸载时自动移除。