实现支持立即执行和取消功能的 JS 增强版节流防抖

常规的防抖（Debounce）和节流（Throttle）实现通常只解决“延迟触发”和“稀释频率”的基础问题，但在实际前端业务中经常遇到两个痛点：用户首次点击提交按钮时若存在数百毫秒的迟滞会极大削弱界面响应感；而在用户切页、弹窗关闭或组件卸载时，积压在事件循环队列中的定时器若未被回收，容易引发内存泄漏乃至组件卸载后的非法状态赋值。本文直接提供支持首触立即执行（Immediate / Leading）与实例手动取消（Cancel）的增强版防抖和节流函数，并剖析其执行逻辑与生命周期治理方案。

一、防抖与节流机制的核心差异与增强诉求

防抖和节流虽然都是针对高频触发事件（如 input、resize、scroll、mousemove）的降频方案，但两者的本质策略截然不同：

• 防抖（Debounce）：在连续触发期间不断重置等待倒计时，只有当最后一次触发后保持一段完整的静默期，目标回调才会真正执行。典型场景是输入框联想搜索与窗口尺寸缩放完成检测。
• 节流（Throttle）：在持续触发期间，将回调的执行频率锁定在一个固定的时间跨度（wait 毫秒）内，无论事件触发得多么密集，都以恒定速率输出结果。典型场景是页面滚动触底加载与拖拽位移计算。

基础版本的防抖函数总是必须等待 wait 毫秒才会有首次反应，这在某些需要立即给用户视觉反馈的按钮点击（防止手抖误连击）上体验很差；同时，如果函数排在 setTimeout 队列中时宿主组件已经被销毁，由于闭包依然持有上下文变量，容易产生内存泄漏。增强版实现正是为了赋予开发者对“前沿控制”与“主动熔断”的掌控力。

二、增强版防抖（Debounce）设计与实现

实现增强版防抖的核心逻辑在于拆解三个核心职责：维持内部计时器引用、处理立即触发判定分支、以及提供解构在函数对象上的 cancel 方法。

1. 执行决策流程分析

当外层包装函数被调用时，需要根据 immediate 参数做出分流：

• 如果配置了 immediate === true：在没有活跃定时器（!timer）时，说明当前处于冷启动或前一个静默周期已完整结束，此时立即同步调用目标函数；与此同时开启定时器，该定时器的唯一职责是在 wait 毫秒后将 timer 重新置为 null，以解除“静默冷却状态”。
• 如果配置了 immediate === false（默认行为）：任何一次触发都会先通过 clearTimeout(timer) 抹平历史计时，并重新挂载一个 wait 毫秒后的执行回调。
• 不论处于何种模式，挂载在返回函数上的 debounced.cancel() 方法都可以直接调用 clearTimeout(timer) 并将 timer = null，瞬间将防抖器还原到初始待机状态。

2. 增强防抖的完整源码实现

下面是包含 immediate 支持和 cancel 方法的完整函数实现：

/**
 * 增强版防抖函数 (Enhanced Debounce)
 * @param {Function} fn 需要被防抖的目标函数
 * @param {number} wait 等待时间（毫秒），默认为 300ms
 * @param {boolean} immediate 是否在静默期开始前立即执行一次，默认为 false
 * @returns {Function} 带有 .cancel() 方法的包装函数
 */
function debounce(fn, wait = 300, immediate = false) {
  let timer = null;
  let result;

  // 包装后的执行函数，必须使用普通函数以正确透传 this
  const debounced = function (...args) {
    const context = this;

    // 每次新触发到达，先清除已有计时器
    if (timer) {
      clearTimeout(timer);
    }

    if (immediate) {
      // 判断当前是否正处于完全空闲状态（无定时器）
      const callNow = !timer;

      // 设置定时器，负责在等待期满后释放状态
      timer = setTimeout(() => {
        timer = null;
      }, wait);

      // 如果是静默后的初次触发，立即执行目标函数
      if (callNow) {
        result = fn.apply(context, args);
      }
    } else {
      // 常规防抖：倒计时结束后执行回调
      timer = setTimeout(() => {
        timer = null;
        fn.apply(context, args);
      }, wait);
    }

    return result;
  };

  // 挂载取消方法：清理定时器并重置闭包变量
  debounced.cancel = function () {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
  };

  return debounced;
}

三、增强版节流（Throttle）双机制与取消实现

传统的简单节流通常分为两派实现：一种是纯时间戳计算（响应敏捷、具备前沿触发，但最后一次停止触发后不会补发尾音），另一种是纯定时器延迟（具备尾音触发，但第一次触发会有固定的延迟等待）。

在生产级增强实现中，我们需要结合时间戳与定时器，支持灵活的配置项：leading（是否允许首次触发立即执行）和 trailing（是否在触发停止后补发一次最后状态的调用），并同样挂载 cancel 销毁机制。

1. 增强节流的完整源码实现

/**
 * 增强版节流函数 (Enhanced Throttle)
 * @param {Function} fn 目标函数
 * @param {number} wait 节流时间跨度（毫秒），默认 300ms
 * @param {Object} options 配置对象
 * @param {boolean} [options.leading=true] 是否允许前沿立即执行
 * @param {boolean} [options.trailing=true] 是否在停止触发后执行末尾补发
 * @returns {Function} 带有 .cancel() 方法的包装函数
 */
function throttle(fn, wait = 300, options = {}) {
  let timer = null;
  let previous = 0;
  let result;

  const { leading = true, trailing = true } = options;

  const throttled = function (...args) {
    const context = this;
    const now = Date.now();

    // 如果配置禁用首触立即执行，且处于首次进入，则将起始点固定为当前时刻
    if (!previous && leading === false) {
      previous = now;
    }

    // 计算当前与上次执行的时间差额
    const remaining = wait - (now - previous);

    // 条件 1：时间差额耗尽（满足固定节流周期）或用户调整了本地时间
    if (remaining <= 0 || remaining > wait) {
      if (timer) {
        clearTimeout(timer);
        timer = null;
      }
      previous = now;
      result = fn.apply(context, args);
    } 
    // 条件 2：处于等待期内，且开启了末尾补发，且当前没有已挂起的补发定时器
    else if (!timer && trailing !== false) {
      timer = setTimeout(() => {
        // 如果禁用了 leading，则定时器执行后将 previous 重置为 0；否则记录当前时间
        previous = leading === false ? 0 : Date.now();
        timer = null;
        fn.apply(context, args);
      }, remaining);
    }

    return result;
  };

  // 挂载取消方法：清理定时器并将状态机变量彻底归零
  throttled.cancel = function () {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
    previous = 0;
  };

  return throttled;
}

四、实战选型决策与前端框架生命周期安全

在现代前端单页应用（React / Vue 等）中，组件会频繁挂载（mount）与卸载（unmount）。如果防抖或节流的回调函数涉及 setState 或响应式数据修改，在组件销毁后被触发会导致严重的内存泄漏与控制台警告。通过显式调用 cancel()，可以在销毁钩子中形成完美的闭环清理。

1. 在 React 组件中的规范应用

在 React 中，为避免组件每次重新渲染（re-render）都创建全新的防抖实例，需配合 useCallback 或 useMemo 固化函数引用，并在 useEffect 的清理函数中调用 .cancel()：

import React, { useState, useEffect, useMemo } from 'react';

function SearchInput({ onSearch }) {
  const [query, setQuery] = useState('');

  // 保持单一防抖函数引用
  const debouncedSearch = useMemo(() => {
    return debounce((value) => {
      onSearch(value);
    }, 400, false);
  }, [onSearch]);

  // 组件销毁时立刻取消挂起的异步定时器，阻断卸载后的回调
  useEffect(() => {
    return () => {
      debouncedSearch.cancel();
    };
  }, [debouncedSearch]);

  const handleChange = (e) => {
    setQuery(e.target.value);
    debouncedSearch(e.target.value);
  };

  return <input value={query} onChange={handleChange} placeholder="请输入搜索内容..." />;
}

2. 在 Vue 3 组合式 API 中的规范应用

<script setup>
import { onMounted, onBeforeUnmount } from 'vue';

const handleScroll = throttle(() => {
  const scrollTop = document.documentElement.scrollTop || document.body.scrollTop;
  console.log('当前滚动高度:', scrollTop);
}, 200, { leading: true, trailing: true });

onMounted(() => {
  window.addEventListener('scroll', handleScroll);
});

// 页面切出或组件销毁前，移除监听器并销毁未执行的定时器
onBeforeUnmount(() => {
  window.removeEventListener('scroll', handleScroll);
  handleScroll.cancel();
});
</script>

五、特性对照与实测注意事项

在实际工程使用中，读者可直接将上述两段增强实现纳入项目的基础 utils 库中。通过对 this 与剩余参数 args 的严谨传递，包装函数对普通函数、异步函数及各类事件监听签名均具备 100% 的向下兼容性，辅以完善的 cancel() 调用，即可兼顾交互响应的敏捷度与生产系统的稳定性。