Vue3封装一个丝滑的自动滚动列表指令(含网页缩放滚动问题解决)
长列表自动滚动跟banner自动切换一样,是一个C端展示页面经常遇到的需求。不过网上各类组件库基本都对“幻灯片”(banner使用的组件)组件有封装,自带好自动切换的功能,而长列表(或表格等)自动滚动的功能则涉及甚少。
这里分享一个我项目中封装的自动滚动指令,且附带期间解决了页面缩放导致滚动失效的解决思路与方案:
需求定义
首先,我们需要理清这个通用指令的需求点,方便进行下一步设计。这里需要的需求点有:
-
支持任意组件/标签的滚动。
-
可控制滚动速度。
-
可设置鼠标移入后停止滚动。
大致思路设计
首先,满足第一点,即指令可以在任意组件(包括原生的与自己封装的Vue组件)上使用,考虑到滚动相关的API,初步确定,我们需要使用到:
scrollTo
, scrollHeight
, clientHeight
分别用来设置滚动高度,获取最大滚动高度 与 可视区域高度。
这一点很好满足,任何通过我们上述的组件获取到的DOM(HTMLElement)都支持这三个接口/属性。
其次是速度控制,使用数字来控制每帧滚动的距离(px),我们可以将速度作为指令的参数。
最后是可选的鼠标移入暂停功能,boolean类型的选项,很容易就能想到使用指令修饰符。
综上,我们的指令调用方式需要满足以下:
<element v-scroll.mouse="1.5"></element>
编码实现
1. 指令注册和整体“架构”代码
/**
* main.ts
*/
import scrollDirective from '@/directive/scroll.ts';
...
const app = createApp(App);
// 注册指令
app.directive(scrollDirective.name, scrollDirective);
...
/**
* scroll.ts
*/
import { DirectiveBinding } from 'vue';
export default {
name: 'scroll',
mounted: (el: HTMLElement, binding: DirectiveBinding) => {},
unmounted: (el: HTMLElement, binding: DirectiveBinding) => {}
}
2. 速度控制以及滚动
JS编写动画,本能的就想到RAF
能够最好的实现动画效果,RAF
并在性能与视觉效果之间自动做好权衡,就是你了。
将速度speed
作为指令参数,在动画函数中,用当前 scrollTop
累加 speed
来实现滚动效果。
/**
* scroll.ts
*/
import { DirectiveBinding } from 'vue';
// 我们会在DOM上拓展一些属性用于滚动动画的执行,这里拓展一下类型,方便编码
interface AnimationElement extends HTMLElement {
speed: number;
}
const DEFAULT_SPEED = 1;
const RAF = window.requestAnimationFrame;
const CancelRAF = window.cancelAnimationFrame;
const elementScroll = (el: AnimationElement) => {
const maxScrollTop = el.scrollHeight - el.clientHeight;
// 根据当前滚动高度与滚动速度,计算出新的滚动高度
const scrollTop =
el.scrollTop + el.speed >= maxScrollTop // 超过最大滚动高度重置 --〉 从头再来
? 0
: el.scrollTop + el.speed;
// 执行滚动
el.scrollTo({
top: scrollTop
});
// 继续执行下一帧动画
RAF(elementScroll.bind(null, el));
}
export default {
name: 'scroll',
mounted: (el: AnimationElement, binding: DirectiveBinding) => {
const maxScrollTop = el.scrollHeight - el.clientHeight;
// 没有滚动空间的时候,无需滚动,直接返回。
if (maxScrollTop <= 0) {
return;
}
// 将速度变量存到DOM中,方便后续动画函数取用
el.speed = binding.value || DEFAULT_SPEED;
// 使用RAF调用动画函数
RAF(elementScroll.bind(null, el));
},
unmounted: (el: HTMLElement, binding: DirectiveBinding) => {}
}
我们随便写一个列表来试试
<template>
<ul v-scroll class="w-[300px] h-[400px] overflow-auto bg-[darkcyan]">
<li>1</li>
<li>2</li>
...
</ul>
</template>
看看效果,perfect!
可以修改一下速度,让他滚快点儿
<ul v-scroll="2" ...>
Nice,没毛病。
3. 鼠标移入暂停滚动,移出恢复滚动
要实现这个功能有两个要点:
一是事件监听,鼠标移入/移出容器时,将动画暂停/重启;
二是获取到当前容器滚动动画id(RAF
返回的),鼠标移入时,使用 window.cancelAnimationFrame
暂停动画。
/**
* scroll.ts
*/
interface AnimationElement extends HTMLElement {
speed: number;
animationId: number;
}
...
const elementScroll = (el: AnimationElement) => {
...
// 继续执行下一帧,并更新动画id
el.animationId = RAF(elementScroll.bind(null, el));
}
// 鼠标移入暂停
const mouseEnterHandler = (el: AnimationElement) => {
if (el.animationId) {
// 取消动画
CancelRAF(el.animationId);
el.animationId = undefined;
}
};
// 鼠标移出继续运行动画
const mouseLeaveHandler = (el: AnimationElement) =>
(el.animationId = RAF(scrollElement.bind(null, el)));
export default {
name: 'scroll',
mounted: (el: AnimationElement, binding: DirectiveBinding) => {
...
// 修改原来初始化运行动画的语句,将RAF结果存到el中,方便暂停动画时使用
el.animationId = RAF(scrollElement.bind(null, el));
// 检测是否传递修饰符,传递了监听鼠标移入移出动画
if (binding.modifiers.mouse) {
el.addEventListener('mouseenter', mouseEnterHandler.bind(null, el));
el.addEventListener('mouseleave', mouseLeaveHandler.bind(null, el));
}
},
unmounted: (el: HTMLElement, binding: DirectiveBinding) => {
// 别忘了DOM解绑时解除事件监听
if (binding.modifiers.mouse) {
el.removeEventListener(
'mouseenter',
mouseEnterHandler.bind(null, el)
);
el.removeEventListener(
'mouseleave',
mouseLeaveHandler.bind(null, el)
);
}
}
}
浅写个demo看看效果
<template>
<ul v-scroll.mouse class="w-[300px] h-[400px] overflow-auto bg-[darkcyan]">
<li>1</li>
<li>2</li>
...
</ul>
</template>
make scroll perfect again!
这样我们就实现了一个可以控制滚动速度,支持鼠标移入暂停滚动的通用滚动指令了。
存在问题
第一版就这样上线使用了,但很快哈,啪的一下,我就发现了一些问题:
-
传入小数时,列表不滚动。
-
页面缩放后,列表不滚动。
1. 问题原因探究
首先要想解决问题,在不存在魔法的情况下,我们要先寻找问题的原因。
既然小数速度无法滚动,那我们在浏览器上测试一二
让页面向下滚动 0.7
, 结果发现还是 0
(⊙o⊙),所以我们下次累加的时候还是 0 + 0.5
无限循环,一直是 0
。
随后,我翻阅了一遍 W3C
文档,找到 scrollTo
函数相关部分,不过文档并未直接说top
参数的处理会向下去整,反而 interface ScrollOptions
中的 top
正是 double
类型,这说明他实际上是支持小数的哇,那这是为什么?
扫视了好几遍之后,发现了一个频频出现的单词 pixels
,这些参数都是以像素为单位的。
像素,像素?像素...啊!道爷我悟了!
可不是嘛,这哪来的 0.5 个像素嘛,这可不得取整?
顺便,在翻阅文档时,也找到了,网页缩放后滚动失效(即使speed >= 1
)的原因:W3C
文档VisualViewport
中找到了这句话,滚动高度会随着页面缩放变小。
我们在Chrome
尝试一下,看看是否属实:
现在正常大小网页设置一下滚动高度,并没有什么问题
随后,缩放网页到90%,马上哈,Y轴的滚动量就变成 0
了
再尝试一下赋值其他的值,会发现,缩放后设置滚动高度后,其真实的滚动量确实减少了,但不是按照我们朴素思维等比例减少的(具体怎么个算法,没找到...)
不过知道这点就足够了,在当前情况下,想要实现我们要的小数级别的滚动速度,那么我们必然不能直接基于 el.scrollTop
来滚动了,必须有所变通。
2. 问题解决:缓存计算
在哐哐哐一通尝试下(css animation | 改用setTimeout,把间隔时间放长 | etc.),最终我想到了一个破费科特的办法,既能满足我们的需求,又很简单不需要大量改动现有代码:
—— 缓存计算滚动高度
顾名思义,即当el.scrollTop
不可靠的时候,那么就由我们自己来手动管理滚动高度,设置一个自定义的变量来对scrollTop
进行累加,这样就规避掉了el.scrollTop
“只会取整”(并不是),导致设置 0.5
速度后,el.scrollTop
一直是0
无法累加的问题了。
同时由于 scrollTop
是我们自己进行计算累加的,也不会受到网页缩放的影响了,缩放后也能正常地进行滚动了。
这样即使我们 speed = 0.5
也能够正常“慢速滚动”(本质上非整数的帧滚动高度相同,即达到了速度放慢的效果)
3. 修改后完整代码
PS:需要特别注意的是,将基准滚动高度改为我们的自定义缓存滚动高度后,用户自行滚动的事件是不会自动同步到我们的缓存滚动高度的,所以需要我们自己同步一下。
/**
* 自动滚动
*
* 修饰符:
* mouse 支持鼠标移入移出暂停动画
*/
import { DirectiveBinding } from 'vue';
interface AnimationElement extends HTMLElement {
speed: number;
animationId: number;
cacheScrollTop: number; // 存放我们缓存的scrollTop
}
const RAF = window.requestAnimationFrame;
const CancelRAF = window.cancelAnimationFrame;
const scrollElement = (el: AnimationElement) => {
const maxScrollTop = el.scrollHeight - el.clientHeight;
// 直接在缓存滚动高度上进行计算
el.cacheScrollTop =
el.cacheScrollTop + el.speed >= maxScrollTop
? 0
: el.cacheScrollTop + el.speed;
// 将缓存高度设置为当前滚动高度
el.scrollTo({
top: el.cacheScrollTop
});
// 执行下一帧
el.animationId = RAF(scrollElement.bind(null, el));
};
// 鼠标移入暂停
const mouseEnterHandler = (el: AnimationElement) => {
if (el.animationId) {
CancelRAF(el.animationId);
el.animationId = undefined;
}
};
// 鼠标移出继续运行
const mouseLeaveHandler = (el: AnimationElement) =>
(el.animationId = RAF(scrollElement.bind(null, el)));
// 处理用户的滚动事件
const elementScrollHandler = (el: AnimationElement) =>
(el.cacheScrollTop = el.scrollTop);
export default {
name: 'scroll',
mounted: (el: AnimationElement, binding: DirectiveBinding) => {
const maxScrollTop = el.scrollHeight - el.clientHeight;
// 无需滚动(这里 - 1因为scrollHeight会四舍五入)
if (maxScrollTop - 1 <= 0) {
return;
}
// 滚动速度
el.speed = binding.value || 1;
el.cacheScrollTop = 0;
el.animationId = RAF(scrollElement.bind(null, el));
// PS:因为我们使用 cacheScrollTop 来代替 el.scrollTop 处理滚动高度,所以这里需要同步一下用户滚动操作后的 scrollTop ==> 而为了保持动画连贯与流畅,这里千万不要去防抖/节流!
el.addEventListener('scroll', elementScrollHandler.bind(null, el));
// 鼠标移入暂停移出继续运动
if (binding.modifiers.mouse) {
el.addEventListener('mouseenter', mouseEnterHandler.bind(null, el));
el.addEventListener('mouseleave', mouseLeaveHandler.bind(null, el));
}
},
unmounted: (el: AnimationElement, binding: DirectiveBinding) => {
if (binding.modifiers.mouse) {
el.removeEventListener(
'mouseenter',
mouseEnterHandler.bind(null, el)
);
el.removeEventListener(
'mouseleave',
mouseLeaveHandler.bind(null, el)
);
}
}
};
总结
-
使用
RAF
作为滚动动画“框架” -
鼠标移入移出动画暂停/恢复,事件监听 +
cancelAnimationFrame
-
滚动的基础单位是像素(1px),正常网页缩放情况下,会向下取整,所以得自行管理滚动高度,对其缓存计算。
-
网页缩放的情况下,滚动高度会减少,同理也通过缓存计算来解决。
敢敢单单,86
行代码我们就实现了一个基本完美的通用列表滚动指令。
希望这篇文章能够对大家有帮助。
参考资料: W3C CSSOM View Module
转载自:https://juejin.cn/post/7234779572759658556