AngularJS中$q.when()的用法

一、$q.when() 的定义与作用

1. 方法定义

$q.when(value);

2. 核心作用

$q.when() 用于将一个值（同步或异步）统一包装为 $q Promise 对象。

其本质目标是：

屏蔽同步值与异步 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 对象，其状态由传入参数决定。

---

三、不同输入情况下的具体行为

1. 传入普通同步值

$q.when(100).then(function (value) {
  console.log(value); // 100
});

行为说明：

• Promise 状态：fulfilled
• 回调在 下一轮 digest 周期中执行
• 不会同步立即执行回调

---

2. 传入 $q Promise

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() 的本质可以概括为一句话：

将一切"可能是异步的东西"，统一为一个可控、可组合、可追踪的 $q Promise。

其工程价值体现在：

• 简化接口设计
• 提升可维护性
• 消除同步 / 异步分支
• 与 AngularJS 变更检测机制完美协同