封装支持回调的JS通用淡入淡出函数

作者:竹影时间:2026-11-19 12:16:46浏览:642

深入讲解如何使用原生JavaScript封装一个高可用、支持完成回调且具备防抖抗重叠能力的通用淡入淡出函数,解决display:none与opacity的协同问题,并提供完整生产级代码。

分类:前端开发 / JavaScript 实战 阅读时间:约 8 分钟 依赖环境:标准现代浏览器 (ES6+)
在前端界面交互中,元素的显示与隐藏若直接切换,容易造成生硬的视觉闪烁。本文通过纯原生 JavaScript 与 requestAnimationFrame 机制,封装一套轻量、通用的淡入(fadeIn)与淡出(fadeOut)函数。该实现原生接管 display: none 与 opacity 的状态同步,杜绝高频连击时的动画冲突,并在补间结束时刻精准触发自定义回调函数。
封装支持回调的JS通用淡入淡出函数
概览图:通用淡入淡出函数核心架构与三层协作模型

为什么不能单纯依赖 CSS transition 显隐?

许多开发者在尝试使用纯 CSS 实现淡出隐藏时,会发现一个经典痛点:display 属性属于离散属性,不支持补间动画。一旦将元素的 display 设为 none,它会立刻从页面渲染树脱离,此时配置在 opacity 上的过渡动画将瞬间失效;而如果仅改变 opacity: 0 却保留默认文档流,虽然视觉透明,该元素仍然会阻挡下方按键的点击与事件响应。

虽然配合 transitionend 事件可以监听 CSS 过渡结束,但在实际工程中存在若干隐患:

  • 事件丢失风险:若元素在隐藏瞬间处于父容器不可见状态,或 opacity 初值已是目标值,浏览器可能不会派发 transitionend 事件,导致后续逻辑永久挂起。
  • 连击竞争抽搐:当用户在淡入或淡出过程中快速反复点击切换按钮时,CSS 类名反复切换极易导致透明度跳跃和回调混乱触发。
  • 依赖样式表耦合:纯样式方案需要额外维护对应的 CSS 类名,在组件化或独立嵌入式脚本中不够自包含。
封装支持回调的JS通用淡入淡出函数
图 1:元素显隐状态转移与透明度生命周期协调

核心设计思路与状态协同

要构建一个可靠的淡入淡出函数,核心在于严密的“时序管理”与“补间解耦”。如图 1 所示,我们需要区分两类操作的时序:

  1. 淡入(Fade In)时序:必须先将元素的 display 恢复为布局所需的显示类型(如 block、inline-block 或 flex),确保其在 DOM 树中拥有物理排版尺寸;紧接着将其 opacity 锁定为当前真实值(若初始为 none 则强制从 0 开始),随后在每一帧逐级递增,直至达到 1;达到目标后,将内联 opacity 固化或清理,并执行完成回调。
  2. 淡出(Fade Out)时序:保持元素当前布局属性不变,从当前实际透明度平滑递减至 0;在最后一帧确认透明度归零后,立即将 display 改为 none 释放页面占位,并触发后续回调(如从 DOM 树移除节点或通知父组件)。
封装支持回调的JS通用淡入淡出函数
图 2:通用淡入淡出函数的五大执行步骤管线

完整函数代码封装与实现

按照图 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);
}
封装支持回调的JS通用淡入淡出函数
图 3:通用淡入淡出函数的系统解耦架构

实战应用场景示例

封装后的函数不仅满足传统的“传入回调函数”的调用形式,还返回标准 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) 可以确保标签页再次激活时,第一帧就能立刻捕获累积时间并精准执行回调收尾,不会发生动画挂死。
封装支持回调的JS通用淡入淡出函数
图 4:三大主流淡入淡出方案维度对比与选型总结

总结

封装一个轻量、健壮的淡入淡出函数是日常前端开发中的高频基础需求。本文通过状态机思想将 display 与 opacity 进行时序解耦,使用 WeakMap 消除连续高频触发时的动画句柄冲突,并结合 requestAnimationFrame 实现物理刷新率对齐与平滑过渡。通过同时注入标准 callback 机制与 Promise 返回,使业务层在执行节点清理、状态同步或连续链式调用时获得了百分之百的完结确定性。

作者最新文章
相关文章
更多