AngularJS $q.when()用法实例解析

一、$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. 传入$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 的变更检测机制无缝配合