AngularJS中$q.when()方法详细用法实例解析与实战代码演示

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

1. 方法定义

$q.when(value);

2. 核心作用

$q.when() 是 AngularJS 中极为实用的工具函数，专门用于将各种值——无论是同步还是异步——统一封装为一个 $q Promise 对象，从而简化异步流程管控。

它要解决的核心问题非常清晰：

让调用方永远无需关心拿到的值是同步返回的，还是来自某个异步任务——统一采用 Promise 的方式处理即可。

二、$q.when()的参数与返回值

1. 参数类型

value 的灵活性极高，几乎可以接收任何类型：

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 的关键区别

六、典型使用场景（重点）

场景一：统一同步与异步接口

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() 了

八、常见误区与注意事项

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 的变更检测机制能够无缝配合