Angular Signals 防抖指南：用 `debounced` 将去抖信号无缝接入 `Resource` 异步数据流

2026-09-06 18:56:55作者：袁立春Spencer

导读

debounced 是 Angular 在 v22 起以实验性 API 形式提供（源码标注为 @experimental 22.0）的信号防抖工具。它把"停止变化之后再过一段时间才生效"这一经典需求直接内建进响应式体系：只需一行 debounced(this.query, 300)，就能得到一个始终持有最后已生效值、并暴露加载状态的 Resource，天然适合与 resource() 或 httpResource 组合，处理搜索联想、自动补全、价格筛选这类高频输入场景。阅读本文后，你将掌握 debounced 的完整用法（毫秒等待、自定义等待函数、相等性比较、注入上下文），并理解其底层基于 linkedSignal、effect 与 resourceFromSnapshots 的状态机实现原理。

为什么需要 `debounced`

Angular 的信号（signal）是同步响应式的：computed 与 effect 会在依赖变化的同一轮就重新求值。对于打字搜索这类场景，如果每次按键都立刻触发一次昂贵的异步请求，会产生大量无效调用。传统做法是自己用 setTimeout 包裹逻辑，但手动管理计时器很容易出错，尤其是组件销毁时的清理与竞态处理。

debounced 把这段复杂度封装好：它会延迟对源信号值的响应，直到源信号停止变化满 wait 毫秒（或满足自定义条件），并返回一个类型为 Resource<T> 的结果对象，其 value() 始终是"已敲定（settled）"的去抖值。它属于 Angular signals 生态中的实验性能力，随时可能变化，详见 Experimental 说明。

核心用法：搜索联想输入的完整示例

debounced 的最常见组合方式是：先对用户输入做防抖，再把防抖后的值作为 resource() 的 params 驱动数据加载。官方文档给出的示例即可直接作为模板：

import {debounced, resource, signal} from '@angular/core';

@Component({
  template: `
    <input (input)="query.set($event.target.value)" />

    @if (results.isLoading()) {
      <p>Searching…</p>
    }
    @for (item of results.value(); track item.id) {
      <li>{{ item.name }}</li>
    }
  `,
})
export class Search {
  query = signal('');

  debouncedQuery = debounced(this.query, 300);

  results = resource({
    params: () => this.debouncedQuery.value(),
    loader: ({params}) => fetchResults(params),
  });
}

需要注意两个设计要点：

debounced 消费的是信号本身，而不是返回值。它接收源信号（一个返回 T 的读取函数），返回一个新的 Resource<T>。模板与 @if / @for 中直接读取的是 results 这个最终数据资源。
value() 只在防抖完成后才更新。因此 resource 的 params 计算只有在用户停顿 300ms 后才会产生新值，进而触发一次 fetchResults；输入期间不会发出请求。results.isLoading() 负责展示"Searching…"占位。

从签名看（见 debounce.ts 实现）：

export function debounced<T>(
  source: () => T,
  wait: NoInfer<DebounceTimer<T>>,
  options?: NoInfer<DebouncedOptions<T>>,
): Resource<T>

source：被防抖的源信号；
wait：等待时长（毫秒数或自定义等待函数）；
options：可选的相等性函数与 Injector。

debounced 由 resource/index.ts 统一导出到 @angular/core，可直接从 @angular/core 导入。

防抖期间的状态：`status()` 与 `value()` 的语义

debounced 返回的 Resource 内部运行着一套精小的状态机，核心行为如下：

阶段	`status()`	`value()`
创建/源信号未变化	`'resolved'`	立即携带当前源值（初始即同步生效，不会强制先等一个计时周期）
计时器倒计时中	`'loading'`	返回上一次已生效的值（旧值不丢失，模板不会闪烁）
计时结束、值已生效	`'resolved'`	更新为最新的去抖值
源信号抛错	`'error'`	立即进入错误状态，不运行计时器

官方文档对这套语义的概括是：当去抖计时器倒计时时 status() 为 'loading'、value() 返回此前已解析的值；计时器到期后资源转为 'resolved'；若源信号抛出异常，资源立即进入 'error'，此时没有计时器在运行。

由于初始状态是同步解析的，debounced 在实践中不会产生 'idle'；它主要在这几个状态之间迁移：resolved → loading（倒计时） → resolved，或 resolved → error。被 debounce 单元测试覆盖的时序事实包括：

初始即为 resolved：should start in resolved state 验证了创建后无需等待即可读到 'initial'；
更新后进入 loading 但保留旧值：should debounce updates 在 source.set('updated') 后断言 status() === 'loading' 且 value() === 'initial'，等待超过阈值后才变为 'resolved' 并返回 'updated'。

自定义等待函数：从毫秒数到任意 Promise 门控

wait 参数的类型是 DebounceTimer<T>（定义见 api.ts）：

export type DebounceTimer<T> =
  | number
  | ((value: T, lastValue: ResourceSnapshot<T>) => Promise<void> | void);

也就是说除了固定毫秒数，还可以传入一个函数。它接收当前新值 value 和上一次状态快照 lastValue（ResourceSnapshot<T>），返回一个 Promise<void>——该 Promise resolve 的时刻即"去抖完成"的时刻。若源信号在 Promise 尚未 settle 前再次变化，Angular 会丢弃旧的 Promise 并启动新一轮等待（机制见下文源码解析）。

官方文档给出的按需策略示例是：出错后立即重试、短查询给予更长延迟：

debouncedQuery = debounced(query, (value, lastSnapshot) => {
  // Retry immediately after an error rather than making the user wait again.
  if (lastSnapshot.status === 'error') return;
  // Short queries get a longer delay—the user is likely still typing.
  const ms = value.length < 3 ? 500 : 200;
  return new Promise<void>((resolve) => setTimeout(resolve, ms));
});

这段示例还揭示了一个文档中未单独展开、但源码明确支持的同步返回分支：回调返回 undefined（而非 Promise）时，等待函数被视为"同步完成"，新值立即生效、直接落到 'resolved'，不会出现 'loading' 中间态。这正是"出错后立即重试"的实现原理——错误态下直接返回，跳过等待。对应测试 should support a custom wait function returning void (synchronous) 断言了这种同步 () => {} 等待函数会让更新立即 resolved。

利用 lastSnapshot（类型为 ResourceSnapshot<T>，其联合形态与 status/error/value 定义见 api.ts），等待函数可以做到依赖当前状态的动态策略，例如在 'error' 时同步放行、在 'resolved' 时按内容长短分档等待，或者实现指数退避。

相等性比较：`Object.is` 与 `equal`

默认情况下，debounced 使用 Object.is 比较值。这里有两个由测试锁定的关键行为：

新值与当前已生效值相等 → 不重新开始防抖（测试 should not reload if value is equal to current resolved value）；
新值与尚在等待中的待生效值相等 → 不重置计时器（测试 should not restart debounce if value is equal to current pending value）。

当默认的同一性判断过严时（例如每次 set 都产生新对象引用、但业务上认为相同），可以用 equal 选项提供自定义相等函数：

debouncedFilter = debounced(filter, 200, {
  equal: (a, b) => a.category === b.category && a.minPrice === b.minPrice,
});

DebouncedOptions<T> 只有两个字段（见 api.ts）：

export interface DebouncedOptions<T> {
  /** The `Injector` to use for the debounced resource. */
  injector?: Injector;
  /** The equality function to use for comparing values. */
  equal?: ValueEqualityFn<T>;
}

测试 should use custom equality function 验证了自定义相等语义：源信号从 {id: 1, val: 'a'} 变成 {id: 1, val: 'b'} 后，由于 equal 只比较 id，资源保持 'resolved' 且仍持有旧对象，不触发新的防抖周期。

注入上下文、生命周期与自动清理

debounced 内部创建了 effect 与 linkedSignal，因此必须在注入上下文（injection context）中调用。关于注入上下文的完整定义与判断条件，可阅读依赖注入上下文指南。

一个关键的生命周期保障：debounced 会获取注入器的 DestroyRef，并在销毁时取消仍在运行的计时器、清空活动 Promise（源码见 debounce.ts）。因此当组件/指令所属的注入器被销毁时，挂起的防抖计时器不会泄漏，也不会在销毁后再去更新已卸载的状态。测试 should cleanup timer when injector is destroyed 与 timer cleanup 分组的 should clear the pending timer when the injector is destroyed 均通过 spy 验证了 clearTimeout 确实被调用、资源不会再迁移到 'resolved'。

如果在非注入上下文（例如普通 service 方法、工具函数）中调用，必须显式传入 Injector：

@Injectable()
export class SearchService {
  private injector = inject(Injector);

  createDebouncedQuery(query: Signal<string>): Resource<string> {
    return debounced(query, 300, {injector: this.injector});
  }
}

注意：若既不在注入上下文又未提供 injector，开发模式下会触发 assertInInjectionContext 断言错误。

源码级原理：linkedSignal + effect + resourceFromSnapshots

debounced 的全部逻辑集中在 debounce.ts，实现可拆解为四块：

内部 linkedSignal 承载状态快照：源信号在 linkedSignal 的 source 中被同步读取；若读取抛错，则封装为 {error, thrown: true}，否则为 {value, thrown: false}。首次求值时同步确定初始状态（抛错 → 'error'，否则 → 'resolved' 并携带当前值），这解释了"创建即 resolved、不等待计时器"的测试结论。
一个 effect 负责全部时序：effect 每轮重新读取源信号并持有状态转换的"最终解释权"。它在 linkedSignal.computation 之上的设计是：只要已有前一状态就原样保留，避免旁路状态被覆盖——即"effect 负责计时与状态迁移，普通读取不参与迁移"。
相等性短路：effect 用 untracked(state) 读取当前快照，与 Object.is 或自定义 equal 比对；若与已生效值或待生效值相等，直接 return，不取消现有计时器。
等待与生效：值确实变化后先 cancelTimer() 作废旧计时器；随后区分两种 wait 分支：
- 数字 wait 被包成 setTimeout Promise；
- 自定义函数返回 undefined 则同步置为 'resolved'；返回 Promise 则：若当前不是 loading/error，先把状态置为 'loading' 但保留当前旧值（state.set({status: 'loading', value: currentState.value})），随后在 Promise resolve 时通过 active === result 判定是否为最新一次等待——只有最新等待能更新到 'resolved'。

active 变量的存在使"旧 Promise 迟到"失效：测试 should cancel previous promise when new value arrives 先触发 update1 的等待、再触发 update2 的等待，随后手动 resolve 第一个 Promise，断言状态仍为 'loading' 且值不变；只有第二个 Promise resolve 后值才更新。同理，timer 相关测试（should clear the previous timer when a newer value supersedes it 等）验证快速连续 set('a') → set('b') → set('c') 时旧计时器被逐个 clearTimeout，始终只保留最新的一个在排队。

最后，debounced 通过 from_snapshots 的 resourceFromSnapshots 把内部状态快照包装成对外暴露的 Resource<T>（统一提供 value()、status()、error() 等信号），从而能与 resource() / httpResource 共享同一套基于快照的资源组合模型（见 Resource composition with snapshots）。

边界行为与易错点

结合 debounce 单元测试的覆盖范围，有几点值得在实际项目中留意：

错误恢复是"迟到生效"的：源信号抛错进入 'error' 后，即使源恢复为正常值，状态也不会立即回到 'resolved'，而会保持 'error' 直到新一轮防抖等待完成。测试 should remain in error state until successfully recovered 验证了这一点。配合前文的"错误态下自定义等待函数同步返回 undefined"可做到立即重试，这正是指南示例中 if (lastSnapshot.status === 'error') return; 注释所表达的意图。
源信号抛错会取消待定计时器：timer cleanup 分组的 should clear the pending timer when the source throws 验证：loading 中一旦源抛错，已排队的计时器会被清除并直接进入 'error'，不会残留到期的回调。
禁止嵌套在其它 resource 的 params 中创建：由于 debounced 本身就是一个资源，源码中通过 isInParamsFunction() 检查并抛出 Cannot create a resource inside the params of another resource。正确姿势是把它建在 params 之外，再用其结果驱动 params（如第一节示例）。
实验性 API 的版本风险：debounced、DebounceTimer、DebouncedOptions 在源码中均标注 @experimental 22.0。实验性 API 不受语义化版本承诺约束，可能在 minor/patch 版本中变化，是否采用需团队权衡（参见 Experimental 政策说明）。

小结

debounced 把"输入停顿后统一生效"这一常用交互原语做成了信号级一等公民：它以 Resource<T> 为返回契约，天然具备 'loading'/'resolved'/'error' 状态与旧值保留语义，可直接作为 resource 或其它异步加载逻辑的上游；毫秒数与自定义 DebounceTimer（Promise 或同步 void）两种等待方式覆盖了固定延迟、内容感知延迟、错误立即重试等策略；默认 Object.is 与可选的 equal 则精细控制"什么才算变化"。在源码层面，它由 linkedSignal 同步初始化、由单一 effect 驱动状态迁移、以 active 令牌丢弃过期 Promise、并通过 DestroyRef 保证计时器随注入器销毁而清理——这套实现同时解释了文档中所有状态语义与测试断言。若想深入探究 Resource 本身的状态机与快照组合能力，可继续阅读 Async reactivity with resources。