深入讲解如何使用原生JavaScript封装一个高可用、支持完成回调且具备防抖抗重叠能力的通用淡入淡出函数,解决display:none与opacity的协同问题,并提供完整生产级代码。
封装支持回调的JS通用淡入淡出函数
时间:2026-11-19
浏览:639
文章目录
requestAnimationFrame 机制,封装一套轻量、通用的淡入(fadeIn)与淡出(fadeOut)函数。该实现原生接管 display: none 与 opacity 的状态同步,杜绝高频连击时的动画冲突,并在补间结束时刻精准触发自定义回调函数。
为什么不能单纯依赖 CSS transition 显隐?
许多开发者在尝试使用纯 CSS 实现淡出隐藏时,会发现一个经典痛点:display 属性属于离散属性,不支持补间动画。一旦将元素的 display 设为 none,它会立刻从页面渲染树脱离,此时配置在 opacity 上的过渡动画将瞬间失效;而如果仅改变 opacity: 0 却保留默认文档流,虽然视觉透明,该元素仍然会阻挡下方按键的点击与事件响应。
虽然配合 transitionend 事件可以监听 CSS 过渡结束,但在实际工程中存在若干隐患:
- 事件丢失风险:若元素在隐藏瞬间处于父容器不可见状态,或
opacity初值已是目标值,浏览器可能不会派发transitionend事件,导致后续逻辑永久挂起。 - 连击竞争抽搐:当用户在淡入或淡出过程中快速反复点击切换按钮时,CSS 类名反复切换极易导致透明度跳跃和回调混乱触发。
- 依赖样式表耦合:纯样式方案需要额外维护对应的 CSS 类名,在组件化或独立嵌入式脚本中不够自包含。
核心设计思路与状态协同
要构建一个可靠的淡入淡出函数,核心在于严密的“时序管理”与“补间解耦”。如图 1 所示,我们需要区分两类操作的时序:
- 淡入(Fade In)时序:必须先将元素的
display恢复为布局所需的显示类型(如block、inline-block或flex),确保其在 DOM 树中拥有物理排版尺寸;紧接着将其opacity锁定为当前真实值(若初始为none则强制从 0 开始),随后在每一帧逐级递增,直至达到 1;达到目标后,将内联opacity固化或清理,并执行完成回调。 - 淡出(Fade Out)时序:保持元素当前布局属性不变,从当前实际透明度平滑递减至 0;在最后一帧确认透明度归零后,立即将
display改为none释放页面占位,并触发后续回调(如从 DOM 树移除节点或通知父组件)。
完整函数代码封装与实现
按照图 2 规划的五大执行步骤,我们使用 ES6 语法编写通用实现。函数内部维护一个 WeakMap 记录各节点当前活跃的动画句柄,确保无论用户点击多快,旧动画都会被安全截断,且新动画无缝承接当前残余透明度:
/**
* 记录正在运行动画帧的 WeakMap,键为 DOM 元素,值为 rAF 句柄
*/
const animRegistry = new WeakMap();
/**
* 通用淡入淡出底层补间驱动器
* @param {Object} options 核心配置参数
* @param {HTMLElement|string} options.element - 目标 DOM 节点或 CSS 选择器
* @param {'in'|'out'} [options.type='in'] - 动画类型:淡入 'in' 或 淡出 'out'
* @param {number} [options.duration=300] - 动画持续时间(毫秒)
* @param {string} [options.display='block'] - 淡入时恢复的 display 样式
* @param {Function} [options.callback] - 动画完成后的回调函数,参数为当前 DOM 元素
* @returns {Promise<HTMLElement>} 同时支持 Promise 链式调用
*/
function fadeCore({
element,
type = 'in',
duration = 300,
display = 'block',
callback = null
}) {
return new Promise((resolve) => {
// 1. 参数归一化与前置校验
const el = typeof element === 'string' ? document.querySelector(element) : element;
if (!el || !(el instanceof HTMLElement)) {
console.warn('[fade] 无效的目标 DOM 元素:', element);
if (typeof callback === 'function') callback(null);
resolve(null);
return;
}
// 2. 清理旧动画帧,避免高频点击下的并发竞态
if (animRegistry.has(el)) {
cancelAnimationFrame(animRegistry.get(el));
animRegistry.delete(el);
}
// 获取当前计算样式
const style = window.getComputedStyle(el);
const isFadeIn = type === 'in';
// 3. 准备起始与目标透明度
let currentOpacity = parseFloat(style.opacity);
if (isNaN(currentOpacity)) currentOpacity = isFadeIn ? 0 : 1;
// 若淡入且当前为隐藏态,强制从 0 开始
if (isFadeIn && style.display === 'none') {
currentOpacity = 0;
el.style.opacity = '0';
el.style.display = display;
}
const startOpacity = currentOpacity;
const targetOpacity = isFadeIn ? 1 : 0;
const opacityDiff = targetOpacity - startOpacity;
// 若已经达到目标值,直接收尾返回
if (Math.abs(opacityDiff) < 0.001) {
if (!isFadeIn) el.style.display = 'none';
if (typeof callback === 'function') callback(el);
resolve(el);
return;
}
let startTime = null;
// 4. 补间逐帧迭代
function step(timestamp) {
if (!startTime) startTime = timestamp;
const elapsed = timestamp - startTime;
const progress = Math.min(elapsed / duration, 1);
// 缓动映射(此处采用三次方缓出二次方缓入的平滑衰减,也可直接使用线性 progress)
const easeProgress = progress * (2 - progress);
const nextOpacity = startOpacity + (opacityDiff * easeProgress);
el.style.opacity = nextOpacity.toFixed(3);
if (progress < 1) {
// 未到达终点,继续申请下一帧
const handle = requestAnimationFrame(step);
animRegistry.set(el, handle);
} else {
// 5. 到达终点,收尾归位
animRegistry.delete(el);
el.style.opacity = targetOpacity.toString();
if (!isFadeIn) {
el.style.display = 'none';
}
// 执行用户回调
if (typeof callback === 'function') {
try {
callback(el);
} catch (err) {
console.error('[fade callback error]', err);
}
}
resolve(el);
}
}
const initialHandle = requestAnimationFrame(step);
animRegistry.set(el, initialHandle);
});
}
/**
* 常用快捷调用函数封装
*/
export function fadeIn(element, duration = 300, display = 'block', callback = null) {
if (typeof display === 'function') {
callback = display;
display = 'block';
}
return fadeCore({ element, type: 'in', duration, display, callback });
}
export function fadeOut(element, duration = 300, callback = null) {
return fadeCore({ element, type: 'out', duration, callback });
}
export function fadeToggle(element, duration = 300, display = 'block', callback = null) {
const el = typeof element === 'string' ? document.querySelector(element) : element;
if (!el) return;
const isHidden = window.getComputedStyle(el).display === 'none';
return isHidden
? fadeIn(el, duration, display, callback)
: fadeOut(el, duration, callback);
}
实战应用场景示例
封装后的函数不仅满足传统的“传入回调函数”的调用形式,还返回标准 Promise 对象,因此可以完美融入 async/await 流程。以下列举两个高频业务场景:
场景一:模态弹窗关闭与 DOM 卸载
当弹窗淡出完毕后,通常需要通知状态机解除遮罩、注销键盘 ESC 监听,或者彻底将弹窗从页面移除:
// 传统回调函数形式
const modal = document.querySelector('#delete-modal');
fadeOut(modal, 250, (el) => {
console.log('弹窗已完全淡出,开始回收资源');
el.remove(); // 安全从 DOM 树移除
document.body.classList.remove('no-scroll');
});
// 或者使用 async/await 语意化调用
async function closeModalAsync() {
await fadeOut('#delete-modal', 250);
console.log('淡出完成,顺序执行后续操作');
}
场景二:通知条(Toast)自动淡入、悬停并在延时后淡出
多步骤动画往往需要前后衔接。借助回调函数或 Promise,链式串联变得非常简洁直观:
function showToast(message) {
const toast = document.querySelector('#global-toast');
toast.textContent = message;
// 1. 淡入显示
fadeIn(toast, 200, 'flex', (el) => {
// 2. 停留 2 秒后自动淡出
setTimeout(() => {
fadeOut(el, 300, () => {
console.log('Toast 已彻底关闭');
});
}, 2000);
});
}
display 进行了智能重载。如果调用 fadeIn(el, 300, callback) 时将回调函数放在第三个位置,内部逻辑会自动识别并安全替换,无需强制传递 'block'。
注意事项与容错边界
- 父容器 overflow 裁切:当元素淡入淡出时,如果祖先容器设置了
overflow: hidden且存在高度折叠,需确保父级容器在动画期间不会截断内容。 - 频繁切换下的动画平滑性:如果元素在淡出至一半(如
opacity: 0.5)时用户突然触发淡入,本实现会直接以0.5作为起始透明度平滑向1.0递增,绝不出现从0暴闪的视觉瑕疵。 - 后台标签页唤醒:
requestAnimationFrame在浏览器处于非激活标签页时会自动暂停以节约能耗。使用Math.min(elapsed / duration, 1)可以确保标签页再次激活时,第一帧就能立刻捕获累积时间并精准执行回调收尾,不会发生动画挂死。
总结
封装一个轻量、健壮的淡入淡出函数是日常前端开发中的高频基础需求。本文通过状态机思想将 display 与 opacity 进行时序解耦,使用 WeakMap 消除连续高频触发时的动画句柄冲突,并结合 requestAnimationFrame 实现物理刷新率对齐与平滑过渡。通过同时注入标准 callback 机制与 Promise 返回,使业务层在执行节点清理、状态同步或连续链式调用时获得了百分之百的完结确定性。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。