jQuery deferred.notifyWith() 方法（完整教程）

jQuery deferred.notifyWith() 方法详解：异步编程中的“实时进度提示”

在现代前端开发中，处理异步操作早已成为日常。无论是加载数据、上传文件，还是执行耗时任务，我们都需要一种机制来“监听”这些操作的进展。jQuery 的 Deferred 对象体系，正是为此而生。而其中，deferred.notifyWith() 方法，就像是一条贯穿异步流程的“进度播报通道”，让你可以实时向观察者传递中间状态。

如果你在使用 jQuery 时，曾遇到过“任务已经开始，但不知道它进行到哪一步”的尴尬场景，那么 deferred.notifyWith() 正是你需要的工具。它让异步操作不再“黑盒”，而是可以逐步反馈状态，提升用户体验。

什么是 Deferred 对象？理解异步编程的基石

在深入 notifyWith() 之前，先理解它的“母体”——Deferred 对象。你可以把 Deferred 看作一个“承诺”：它承诺在未来某个时刻完成某个任务，并返回结果。

// 创建一个 Deferred 对象
var deferred = $.Deferred();

// 模拟一个耗时任务
setTimeout(function() {
    deferred.resolve("任务完成！"); // 任务成功完成
}, 2000);

// 绑定成功回调
deferred.done(function(message) {
    console.log(message); // 输出：任务完成！
});

在这个例子中，resolve() 是任务完成的“收尾信号”。但现实中的任务往往不是“一蹴而就”的。比如文件上传，你希望在上传 10%、30%、50% 时都通知用户。这就需要一个“中间状态通知机制”——这正是 notifyWith() 的用武之地。

deferred.notifyWith() 方法的核心作用

notifyWith() 是 Deferred 对象提供的一个方法，用于在异步任务执行过程中，向所有注册的 progress 回调函数发送通知。它不改变任务的最终状态（成功或失败），只用于传递“当前进度”。

方法签名

deferred.notifyWith(context, [args])

• context：通知时的上下文（this 指向），可选。
• args：传递给 progress 回调的参数数组，可选。

与 resolve/reject 的区别

✅ 比喻：resolve() 和 reject() 是“终点线”，而 notifyWith() 是“沿途的路标”。

实际案例：文件上传进度条实现

让我们通过一个真实场景来理解 notifyWith() 的价值。假设你正在实现一个文件上传功能，需要实时显示进度。

// 创建一个 Deferred 对象，用于管理上传流程
var uploadDeferred = $.Deferred();

// 模拟上传过程（实际中可能是 XMLHttpRequest 或 fetch）
function simulateUpload(fileSize) {
    var uploaded = 0;
    var interval = setInterval(function() {
        uploaded += Math.random() * 10; // 模拟上传速度
        if (uploaded >= fileSize) {
            uploaded = fileSize;
            clearInterval(interval);
            uploadDeferred.resolve("上传成功！");
            return;
        }

        // 使用 notifyWith 发送进度通知
        // this 指向 window，参数是当前已上传百分比
        uploadDeferred.notifyWith(window, [Math.round((uploaded / fileSize) * 100)]);
    }, 300);
}

// 注册进度回调（在 UI 层显示进度条）
uploadDeferred.progress(function(percentage) {
    console.log("上传进度：" + percentage + "%");
    // 假设有一个 DOM 元素用于显示进度条
    // document.getElementById("progressBar").style.width = percentage + "%";
});

// 注册成功回调
uploadDeferred.done(function(message) {
    console.log(message);
});

// 注册失败回调
uploadDeferred.fail(function(error) {
    console.log("上传失败：" + error);
});

// 启动上传（模拟 100MB 文件）
simulateUpload(100);

代码解析

• uploadDeferred.progress()：注册一个进度回调函数，当 notifyWith() 被调用时触发。
• notifyWith(window, [percentage])：向所有 progress 回调发送当前进度（百分比）。
• this 指向 window，意味着在回调中可以通过 this 访问全局对象。
• Math.round((uploaded / fileSize) * 100)：计算百分比，避免浮点数问题。

📌 提示：在实际项目中，notifyWith() 可以结合 XMLHttpRequest.upload.onprogress 事件使用，实现真正意义上的文件上传进度反馈。

多个进度回调的注册与执行

notifyWith() 的一个强大之处在于：它可以同时通知多个监听者。你可以在不同模块注册各自的 progress 回调，实现解耦。

var task = $.Deferred();

// 回调 1：控制台输出进度
task.progress(function(percent) {
    console.log("【控制台】进度：" + percent + "%");
});

// 回调 2：更新 UI 进度条
task.progress(function(percent) {
    var progressBar = document.getElementById("progress");
    if (progressBar) {
        progressBar.style.width = percent + "%";
        progressBar.textContent = percent + "%";
    }
});

// 回调 3：记录日志
task.progress(function(percent) {
    console.log("【日志】上传到 " + percent + "%");
});

// 模拟任务执行
setInterval(function() {
    var current = Math.random() * 100;
    task.notifyWith(null, [Math.floor(current)]);
}, 500);

// 任务完成
setTimeout(function() {
    task.resolve("任务完成！");
}, 3000);

关键点说明

• task.progress() 可以被调用多次，每次注册一个回调。
• 所有注册的回调都会在 notifyWith() 被调用时依次执行。
• null 作为 context，表示回调中的 this 指向 undefined（或全局对象，取决于运行环境）。

与 .progress() 方法的配合使用

notifyWith() 必须配合 .progress() 使用，否则无法接收通知。这是 jQuery Deferred 的设计逻辑。

正确用法

var dfd = $.Deferred();

// 注册进度回调
dfd.progress(function(data) {
    console.log("收到进度通知：" + data);
});

// 发送通知
dfd.notifyWith(null, ["正在处理中"]);

错误用法（无效果）

var dfd = $.Deferred();

// 没有注册 progress 回调
// notifyWith 会静默失败，不会报错，但也不会触发任何回调
dfd.notifyWith(null, ["数据加载中"]);

⚠️ 警告：notifyWith() 不会抛出异常，如果忘记注册 progress 回调，你将无法收到任何通知。

实用技巧与最佳实践

1. 使用 notifyWith() 传递复杂数据

args 参数可以是任意类型，包括对象、数组、函数等。

var task = $.Deferred();

task.progress(function(info) {
    console.log("当前状态：", info.status);
    console.log("已处理：" + info.processed + " 个");
    console.log("总数量：" + info.total);
});

// 发送包含状态信息的对象
task.notifyWith(null, [{
    status: "processing",
    processed: 45,
    total: 100
}]);

2. 避免频繁调用导致性能问题

在高频率事件中（如滚动、鼠标移动），不要滥用 notifyWith()。建议使用防抖（debounce）或节流（throttle）控制频率。

var lastNotify = 0;
var notifyInterval = 100; // 每 100ms 最多通知一次

function safeNotify(percent) {
    var now = Date.now();
    if (now - lastNotify >= notifyInterval) {
        uploadDeferred.notifyWith(null, [percent]);
        lastNotify = now;
    }
}

3. 与 Promise 链结合使用

deferred.notifyWith() 可以在 Promise 链中无缝使用，适用于复杂流程控制。

function loadUserData() {
    var dfd = $.Deferred();

    // 模拟请求
    setTimeout(function() {
        dfd.notifyWith(null, ["开始加载用户数据"]);
        setTimeout(function() {
            dfd.notifyWith(null, ["数据加载完成"]);
            dfd.resolve({ name: "张三", age: 28 });
        }, 1000);
    }, 500);

    return dfd.promise();
}

// 使用
loadUserData()
    .progress(function(message) {
        console.log("进度：" + message);
    })
    .done(function(data) {
        console.log("用户数据：" + JSON.stringify(data));
    });

总结：让异步任务“有声有色”

jQuery deferred.notifyWith() 方法 是 jQuery 异步编程体系中的“进度广播器”。它让你不仅能知道任务“是否完成”，还能清晰地感知“进行到哪一步”。

在实际项目中，无论是文件上传、数据加载，还是复杂的动画流程，notifyWith() 都能显著提升用户体验。它让“黑盒”异步操作变得透明，让开发者和用户都能“看得见进展”。

掌握这一方法，意味着你已经迈入了高级异步编程的门槛。记住：好的异步体验，不在于“快”，而在于“可感知”。

现在，不妨在你的下一个项目中，尝试加入 notifyWith()，让进度条动起来，让用户不再“干等”。