一、$q.when()的定义与作用
1. 方法定义
$q.when(value);
2. 核心作用
$q.when() 是 AngularJS 中极为实用的工具函数，专门用于将各种值——无论是同步还是异步——统一封装为一个 $q Promise 对象，从而简化异步流程管控。
它要解决的核心问题非常清晰：
让调用方永远无需关心拿到的值是同步返回的，还是来自某个异步任务——统一采用 Promise 的方式处理即可。
二、$q.when()的参数与返回值
1. 参数类型
value 的灵活性极高，几乎可以接收任何类型：
| 参数类型 | 行为 |
|---|---|
| 普通值（number、string、object 等） | 立即 resolve |
$q Promise | 直接返回（或状态跟随） |
thenable 对象（含 then 方法） | 按 Promise 规则解析 |
| 原生 ES6 Promise | 自动桥接为 $q Promise |
2. 返回值
$q.when(...) → Promise
返回的始终是一个 $q Promise 对象，至于状态是 fulfilled 还是 rejected，取决于你传入的参数类型和内容。
三、不同输入情况下的具体行为
1. 传入普通同步值
$q.when(100).then(function (value) {
console.log(value); // 100
});
行为说明：
- Promise 状态：
fulfilled - 回调会在 下一轮 digest 周期 中触发
- 注意：即便传入的是普通数字，也并非同步执行
2. 传入$qPromise
var p = $q.defer().promise;
$q.when(p).then(function (value) {
console.log(value);
});
行为说明：
- 不会额外创建新的异步操作
- 返回的 Promise 状态和原 Promise 完全绑定
- 实际上相当于直接使用
p.then(...)
3. 传入 thenable 对象
var thenable = {
then: function (resolve, reject) {
resolve('ok');
}
};
$q.when(thenable).then(function (value) {
console.log(value); // ok
});
行为说明：
$q.when()会自动识别并调用它的then方法- 完全遵循 Promises/A+ 的解析流程
- 非常适合用来兼容第三方库的 Promise 场景
4. 传入原生 ES6 Promise
var nativePromise = Promise.resolve('hello');
$q.when(nativePromise).then(function (value) {
console.log(value); // hello
});
行为说明：
$q会监听原生 Promise 的最终结果- 自动触发 AngularJS 的
$digest - 从而有效解决了许多人常遇到的“视图不刷新”问题
四、$q.when()与$q.resolve()的关系
1. 等价性说明
在 AngularJS 1.4+
$q.when(value) === $q.resolve(value)
$q.resolve()是后来添加的语义更清晰的 API$q.when()则是为了向后兼容而保留的“老名字”
2. 推荐实践
- 新项目里：优先使用
$q.resolve() - 旧项目里：继续使用
$q.when()也完全可行
五、$q.when()的执行时机与 Digest 机制
1. 回调执行模型
$q.when(value).then(callback);
callback永远是异步的- 具体执行时机：当前调用栈跑完后才会触发
- 并且一定在
$digest环境下运行
2. 与原生 Promise 的关键区别
| 对比项 | $q.when() | Promise.resolve() |
|---|---|---|
触发 $digest | 是 | 否 |
| Angular 视图更新 | 自动 | 需手动 $apply |
| 框架集成 | 深度集成 | 无 |
六、典型使用场景（重点）
场景一：统一同步与异步接口
function getConfig() {
if (cache) {
return $q.when(cache);
}
return $http.get('/config').then(function (res) {
return res.data;
});
}
调用方：
getConfig().then(function (config) {
// 管它是缓存还是网络请求，反正拿到结果就行
});
✅ 这是 $q.when() 用得最多的场景，没有之一
场景二：函数返回值 Promise 化
function normalize(value) {
return $q.when(value).then(function (v) {
return v.trim();
});
}
场景三：桥接第三方 Promise
function wrapThirdParty(promise) {
return $q.when(promise);
}
这样做的好处很明显：
- 状态变得可控
- digest 也能正常触发
场景四：与$q.all()配合
$q.all([
$q.when(1),
$http.get('/api'),
maybePromise
]).then(function (results) {
console.log(results);
});
七、$q.when()与$q.defer()的对比
| 维度 | $q.when() | $q.defer() |
|---|---|---|
| 是否创建新 Promise | 是（轻量） | 是（完整） |
| 是否控制 resolve | 否 | 是 |
| 适用场景 | 包装、统一接口 | 主动控制异步流程 |
| 推荐程度 | 高 | 谨慎使用 |
能用
$q.when()搞定的事情，通常就别用$q.defer()了
八、常见误区与注意事项
1. 误区：认为$q.when()是同步执行
❌ 许多人误以为传入普通值会同步触发回调
✔️ 实际上它永远是异步的，即使值本身是同步的
2. 误区：用$q.when()代替业务逻辑判断
// 这样写可读性不太好 return $q.when(flag ? value1 : value2);
建议还是把条件判断逻辑拆分清楚。
3. 注意：异常处理规则
$q.when(value).then(function () {
throw new Error('error');
}).catch(function (e) {
console.error(e);
});
throw会自动转换为reject状态
九、总结
$q.when() 的核心价值用一句话就能概括：
将一切“可能是异步的东西”，统一成为一个可控、可组合、可追踪的
$qPromise。
它在工程上的实际优势体现在：
- 接口设计更加简洁
- 代码可维护性更高
- 同步 / 异步分支不再令人头疼
- 与 AngularJS 的变更检测机制能够无缝配合
