@samdy-chan/vue3-goto-top-or-bottom
@samdy-chan/vue3-goto-top-or-bottom 这个 vue3 自定义组件由作者 Samdy_Chan 独立开发。此组件的主要功能是根据父容器是否出现垂直滚动条来自动显示/隐藏 [滚动到顶部/底部] 图标，点击图标可直接或缓慢动画效果滚动到父容器或页面顶部/底部，其主要功能包括：
1)、本组件基于 Vite 5.3.1 + Vue 3.4.29 + TypeScript(TS) 5.2.2 构建打包，支持组件参数TS类型声明；
本组件的[滚动到顶部/底部]图标文件和所有css样式代码都已经全部打包到生成的 js 文件中，并正常引用和使用，所以不会额外生成单独的图标图片文件及css样式文件；
[滚动到顶部/底部]图标采用 png 透明图片，可通过组件参数如
<GotoTopOrBottom :cssObj="{backgroundColor: '#2c8ce6'}"
改变图标的颜色（默认为浅蓝色）。由于图片较小，为了方便，并在打包时将图片打包为 base64 编码格式，并在打包后的 js 文件中直接引用了此 base64 编码格式的图片；
2)、根据此组件父容器（HTML父标签元素）的内容如果超出了父容器的高度（需设置父容器css属性height或max-height），出现了垂直滚动条时（需设置父容器css属性overflow: auto或overflow-y: auto），会自动显示本组件（滚动到顶部/底部）箭头图标，点击图标可直接或缓慢动画效果滚动到父容器或页面顶部/底部；
3)、本组件会自动判断，如果滚动条已经滚动到父容器最顶部（包括手动拖动滚动条到顶部，或点击本组件[滚动到顶部]图标滚动到顶部），则会隐藏[滚动到顶部]图标，只显示[滚动到底部]图标。反之亦然，当滚动到底部时，只显示[滚动到顶部]图标；
4)、本组件的[滚动到顶部/底部]图标可以在父容器（当缺省 parentIsWindow 参数或值为 false）或页面（当 parentIsWindow 参数值为 true）范围内随意拖动移动，以便方便阅读父容器的内容，鼠标左键按住图标0.5秒，即可拖动移动图标；
5)、右击本组件的[滚动到顶部/底部]图标，在弹出的快捷菜单中点击[隐藏]菜单项，可在本次浏览中临时隐藏本组件的[滚动到顶部/底部]图标，以便方便阅读父容器的内容；
6)、使用本组件时，可设置传递 animateObj 对象参数是否开启缓慢滚动动效 animateObj.enable（默认true，开启），和滚动时长 animateObj.duration（默认300毫秒，建议保留此默认值，如果设置不当，可能会引起滚动卡顿不流畅），使用方法，例如：
<GotoTopOrBottom :animateObj="{enable:true, duration: 300}" />
缺省不设置，默认就是开启滚动动效和滚动时长300毫秒；
a）、For npm：
npm install @samdy-chan/vue3-goto-top-or-bottom --save
b）、For yarn：
yarn add @samdy-chan/vue3-goto-top-or-bottom
c）、For pnpm：
pnpm add @samdy-chan/vue3-goto-top-or-bottom --save
在 main.js / main.ts 中全局注册本组件，这样在其它所有组件及.vue页面中直接使用本组件标签即可，无需再导入，全局注册代码如下：
// main.js or main.ts
import { createApp } from 'vue';
import App from './App.vue';
// 1、导入本组件（必须用默认导入方式）
import GotoTopOrBottom from '@samdy-chan/vue3-goto-top-or-bottom';
// 根据 App.vue 组件创建 Vue app 实例
const app = createApp(App);
// 2、全局注册本组件
app.use(GotoTopOrBottom);
// 挂载 Vue app 实例到 id 为 'app' 的 DOM 节点中
app.mount('#app');
-
方法二：按需导入注册本组件（及组件Props参数说明）
更详细的组件 Props 和 Events 使用说明，详见：Props & Events Instructions（参数及自定义事件使用说明） 部分
在每个需要使用本组件的.vue文件中都要导入本组件（必须用分别导入方式）：
// 1、导入本组件
<script setup lang="ts">
// 必须用分别导入方式（在 main.js or main.ts 中全局注册，则要用默认导入方式）
import { GotoTopOrBottom } from '@samdy-chan/vue3-goto-top-or-bottom';
/**** 组件参数及支持的自定义事件设置 ****/
/** 本组件目前支持配置及传递 2 个可选的自定义事件，分别是：@topFinished、@bottomFinished，说明如下：
@topFinished：点击[回到顶部]图标或滚动条滚动到顶部后，要调用的自定义事件回调函数；
@bottomFinished：点击[回到底部]图标或滚动条滚动到底部后，要调用的自定义事件回调函数；
**/
/** 本组件目前支持配置及传递 7 个 Props 参数，分别是：timeout、parentIsWindow、showIconTips、showWhichIcon、scrollDistance、cssObj、animateObj，其中 cssObj、animateObj 为对象式配置参数，这些参数的作用及说明如下（也可详见本组件的TS类型声明文件<<goto-top-or-bottom.vue.d.ts>>，如果是在 vite + ts 环境中使用本组件，import 导入本组件后，按住Ctrl+鼠标左击本组件名，会自动弹出类型声明或跳转到类型声明文件）
**/
// 参数一（timeout）：可选参数，加载或刷新页面时，延迟显示本组件滚动图标的时间，默认值为2000毫秒（2秒）。因为父容器的内容有可能是异步获取的（如读取文件或请求后端 api 接口），这样的话，一开始父容器还没有内容，是不会有滚动条的，待获取到异步数据填充到父容器并超过其允许的高度后，才会出现滚动条，此时，才判断需要显示滚动图标，可根据你的系统及网络状况，调节该延迟参数，单位为毫秒，一般使用默认值2000毫秒应该足够。
const timeout = 2000;
// 参数二（parentIsWindow）：可选参数，父容器是否为顶级元素（window/document/body），默认值为false，将本组件放在哪个HTML标签容器内，就是使用本组件控制哪个HTML标签容器（父容器）的滚动。
const parentIsWindow = false;
/** 如果需要为某个块级父容器（如 div/main/section/article/aside/display:block等）添加本滚动图标组件，只需要将本组件放在父容器一级子级别中即可，如下：
<div class="parent-container">
......
<GotoTopOrBottom />
</div>
**/
/** 如果需要把本滚动图标组件控制顶级对象（window/document/body）的滚动，即滚动整个页面窗口的滚动条时，显示和使用本组件，侧可将本组件放在页面任何HTML标签内，但需要指定 parentIsWindow 参数或设置为 true，如下：
......
<GotoTopOrBottom :parentIsWindow="true" />
**/
// 参数三（showIconTips）：可选参数，鼠标放在[回到顶部/底部]图标是否显示标签 title 属性的提示内容，默认值 true
const showIconTips = true;
// 参数四（showWhichIcon）：可选参数，根据当前滚动情况，显示哪个滚动图标：
// 'both'：显示[回到顶/底部]两个图标（默认值），
// 'top'：只显示[回到顶部]图标，
// 'bottom'：只显示[回到底部]图标
const showWhichIcon = 'both';
// 参数五（scrollDistance）：可选参数，滚动多少距离后才显示[回到顶/底部]图标，默认值 1
const scrollDistance: 1;
// 参数六（cssObj）：可选参数，组件 css 样式设置参数的对象，以下均为默认值，如不传该参数，各属性将使用默认值，
// 如果只想修改某些 css 属性，只需要设置需要修改的属性即可，如：
// <GotoTopOrBottom :cssObj="{width: '30px', height: '30px'}" />
// cssObj 样式设置对象参数各属性默认值如下：
const cssObj = {
// 本组件滚动图标距离父容器或页面顶部的距离，默认值是50%，top: '50%' + translateY: '-50%' 为垂直居中
top: '50%',
// 本组件滚动图标距离父容器或页面右边距的距离，默认值30px
right: '30px',
// 本组件滚动图标向上移动自身距离的一半（-50%，默认）
translateY: '-50%',
// [回到底部]图标盒子顶部距离[回到顶部]图标底部的距离，默认值10px
marginTop: '10px',
// 本组件滚动图标的宽高大小设置，默认值40px
width: '40px',
height: '40px',
// 本组件滚动图标的四边角圆弧度设置，50%为正圆形，默认值50%
borderRadius: '50%',
// 本组件滚动图标的颜色，默认为浅蓝色#2c8ce6
backgroundColor: '#2c8ce6',
// 本组件滚动图标的透明度设置，默认值为 0.6
opacity: '.6',
// 拖拽滚动图标到上下左右边界时保留的间距值，默认值为0px
sideMargin: '0px'
}
// 参数七（animateObj）：可选参数，组件滚动动画效果参数设置，以下均为默认值，如不传该参数，将使用以下默认值：
const animateObj = {
// 是否开启滚动动画，不开启则立即一次性滚动到顶部/底部，默认开启true
enable: true,
// 动画时长，单位毫秒，默认值300毫秒，需开启动画才生效(animateObj.enable=true)。数字越大，滚动越慢，建议保留默认值即可
duration: 300,
// 定时器控制多久滚动一次，单位毫秒，默认值15毫秒，需开启动画才生效(animateObj.enable=true)。数字越大，滚动越卡顿，建议保留默认值即可
interval: 15
}
// 说明：animateObj.duration 和 animateObj.interval 参数可产生滚动次数（滚动多少次才能滚动到顶/底部）；滚动次数 = animateObj.duration / animateObj.interval
</script>
// 2、使用本组件
// 2.1、在 div 等块状盒子父容器中使用本组件（控制div等块状父容器的滚动）
<template>
<div class="parent-container">
<!-- 使用方式1：最基本使用，无需传递任何参数，使用默认值一般足够了，本组件必须放在父容器标签一级层次内 -->
<GotoTopOrBottom />
<!-- 使用方式2：传递如上设置的指定参数 -->
<!--
<GotoTopOrBottom
:timeout="2000"
:parentIsWindow="false"
:showIconTips="true"
showWhichIcon="both"
:scrollDistance="1"
:cssObj="cssObj"
:animateObj="animateObj" />
-->
<!-- 使用方式3：传递设置参数的非默认值 -->
<!--
<GotoTopOrBottom
:timeout="1500"
showWhichIcon="top"
:scrollDistance="50"
:cssObj="{width: '30px', height: '30px', backgroundColor: '#00ff00'}"
:animateObj="{duration: 500}" />
-->
</div>
</template>
// 2.2、在 window/document/body 顶级父容器中使用本组件（控制顶级父容器的滚动）
<template>
<!-- 必须要指定 parentIsWindow 参数或设置其为布尔类型值 true，其它的参数设置同上2.1所说的。
要将 window/document/body 作为父容器时，可将本组件放在任意HTML标签内
-->
<GotoTopOrBottom :parentIsWindow="true" />
</template>
| 参数名 | 类型 | 是否可选 | 说明 | 默认值 |
|---|---|---|---|---|
| timeout | number | 是 | 加载或刷新页面时，延迟显示本组件滚动图标的时间（单位毫秒ms），因为父容器的内容有可能是异步获取的（如读取文件或请求后端 api 接口），这样的话，一开始父容器还没有内容，是不会有滚动条的，待获取到异步数据填充到父容器并超过其允许的高度后，才会出现滚动条，此时，才判断需要显示滚动图标（手动滚动时也会显示滚动图标），可根据你的系统及网络状况，调节该延迟参数，单位为毫秒，一般使用默认值2000毫秒应该足够。 | 2000 |
| parentIsWindow | boolean | 是 | 父容器是否为顶级（window/document/body）元素，将本组件放在哪个HTML标签容器内，就是使用本组件控制哪个HTML标签容器（父容器）的滚动。当此参数值为true时，表示将整个页面窗口设置为父容器，控制整个页面的滚动，此时将本组件放在任意HTML标签内都可以。 | false |
| showIconTips | boolean | 是 | 鼠标放在[回到顶部/底部]图标是否显示标签 title 属性的提示内容 | true |
| showWhichIcon | enum: 'both'|'top'|'bottom' | 是 | 显示哪个滚动图标，根据当前滚动距离情况：
| 'both' |
| scrollDistance | number | 是 | 滚动多少距离后才显示[回到顶/底部]图标 | 1 |
| cssObj | object | 是 | 组件 css 样式设置参数的对象，如不传该参数，所有属性使用默认值，如果只想修改某些 css 属性，只需要设置需要修改的属性即可，如： <GotoTopOrBottom :cssObj="{width: '30px', height: '30px'}" /> | { top: '50%', right: '30px', translateY: '-50%', marginTop: '10px', width: '40px', height: '40px', borderRadius: '50%', backgroundColor: '#2c8ce6', opacity: '.6', sideMargin: '0px' } |
| cssObj.top | string | 是 | 滚动图标距离页面顶部的距离，默认值50%，top: '50%' + translateY: '-50%' 为垂直居中 | '50%' |
| cssObj.right | string | 是 | 滚动图标距离父容器或页面右边距的距离 | '30px' |
| cssObj.translateY | string | 是 | 滚动图标向上移动自身距离的一半 | '-50%' |
| cssObj.marginTop | string | 是 | [回到底部]图标盒子顶部距离[回到顶部]图标底部的距离 | '10px' |
| cssObj.width | string | 是 | [回到顶/底部]单个滚动图标的宽度大小设置 | '40px' |
| cssObj.height | string | 是 | [回到顶/底部]单个滚动图标的高度大小设置 | '40px' |
| cssObj.borderRadius | string | 是 | 滚动图标的四边角圆弧度设置，50%为正圆形 | '50%' |
| cssObj.backgroundColor | string | 是 | 滚动图标的颜色，默认为浅蓝色 | '#2c8ce6' |
| cssObj.opacity | string | 是 | 滚动图标的透明度设置 | '0.6' |
| cssObj.sideMargin | string | 是 | 拖拽滚动图标到上下左右边界时保留的间距值 | '0px' |
| animateObj | object | 是 | 组件滚动动画效果参数设置，如不传该参数，所有属性使用默认值，如果只想修改某些属性，只需要设置需要修改的属性即可，如： <GotoTopOrBottom :animateObj="{duration: 500}" /> | { enable: true, duration: 300, interval: 15, } |
| animateObj.enable | boolean | 是 | 是否开启缓慢滚动动画，不开启则立即一次性滚动到顶部/底部，默认开启 | true |
| animateObj.duration | number | 是 | 动画时长，单位毫秒，默认值300毫秒，需开启动画才生效(animateObj.enable=true)。数字越大，滚动越慢，建议保留默认值即可 | 300 |
| animateObj.interval | number | 是 | 定时器控制多久滚动一次，单位毫秒，默认值15毫秒，需开启动画才生效(animateObj.enable=true)。数字越大，滚动越卡顿，建议保留默认值即可 | 15 |
| 备注 | animateObj.duration 和 animateObj.interval 参数可产生滚动次数（滚动多少次才能滚动到顶/底部）； 滚动次数 = animateObj.duration / animateObj.interval | |||
| 事件名 | 类型 | 是否可选 | 说明 |
|---|---|---|---|
| @topFinished | Function | 是 | 点击[回到顶部]图标或滚动条滚动到顶部后，要调用的自定义事件回调函数 |
| @bottomFinished | Function | 是 | 点击[回到底部]图标或滚动条滚动到底部后，要调用的自定义事件回调函数 |
- 组件会根据当前浏览器使用的语言环境，如果是中文环境 ，则显示中文提示，否则显示英文提示，如下图：
1243
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
