# Compute Pressure API

> PressureObserver 报告系统资源的高层压力变化。本页说明记录、采样、策略错误、停止观察，以及浏览器不支持时的回退。

Compute Pressure API 报告 CPU 等系统资源的高层压力变化。`PressureObserver` 调用 `observe()` 开始观察来源后，会把 `PressureRecord` 对象交给回调。

## 支持范围

BCD 记录桌面版 Chrome 125 起提供 `PressureObserver`，并将这项支持镜像到 Edge。Android 版 Chrome、Firefox 与 Safari 记为不支持（BCD `api.PressureObserver`）。

## 语法

```js
const observer = new PressureObserver(callback)

observer.observe(source)
observer.observe(source, options)
observer.unobserve(source)
observer.disconnect()
observer.takeRecords()
```

此接口可用于安全上下文中的窗口、专用 Worker 和共享 Worker，但不能用于 Service Worker。`observe()` 开始观察后，返回的 Promise 以 `undefined` 兑现。

## 参数

构造函数接收回调。回调参数包括记录数组和观察器本身；数组保存自上次回调或上次调用 `takeRecords()` 以后收集的记录。

| 参数或成员 | 类型 | 含义 |
|---|---|---|
| `source` | `string` | 要观察的压力来源。`PressureObserver.knownSources` 可提示浏览器认识哪些来源。 |
| `options.sampleInterval` | `number` | 请求的最短回调间隔，以毫秒表示，默认值为 `0`。 |
| `PressureRecord.source` | `string` | 记录所代表的来源。 |
| `PressureRecord.state` | `string` | 高层压力状态。 |
| `PressureRecord.time` | `DOMHighResTimeStamp` | 记录的时间戳。 |

`unobserve(source)` 停止观察指定来源。`disconnect()` 停止所有来源并清除队列；`takeRecords()` 返回队列中的记录并将队列清空。

## 异常

[`observe()`](https://w3c.github.io/compute-pressure/#dom-pressureobserver-observe) 会报告策略与来源错误。

| 异常 | 条件 |
|---|---|
| `TypeError` | 传给 `observe()` 的来源不是 `PressureSource` 枚举中的值。 |
| `NotAllowedError` | `compute-pressure` Permissions Policy 禁止使用此 API。 |
| `NotSupportedError` | 传给 `observe()` 的来源不受浏览器支持。 |

:::caution
`compute-pressure` Permissions Policy 的默认允许列表是 `self`。当所属文档不允许使用这项受策略控制的功能时，Compute Pressure 规范要求 `observe()` 返回以 `NotAllowedError` 拒绝的 Promise（Compute Pressure Level 1 的 [`PressureObserver.observe()` 方法步骤](https://w3c.github.io/compute-pressure/#dom-pressureobserver-observe)）。
:::

## 示例

构造观察器前检查 `PressureObserver`。无法观察时，保留固定的低负载模式。

### CPU 压力升高时减少工作

下面的代码把压力状态写入文档；遇到 `serious` 或 `critical` 记录时切换负载标签。回退分支固定采用低负载。

```js
const status = document.body.appendChild(document.createElement("p"));
const mode = document.body.appendChild(document.createElement("p"));

if (!("PressureObserver" in globalThis)) {
  status.textContent = "无法读取计算压力。";
  mode.textContent = "低负载";
} else {
  const observer = new PressureObserver((records) => {
    const latest = records.at(-1);
    status.textContent = `CPU 压力：${latest.state}`;
    mode.textContent = ["serious", "critical"].includes(latest.state)
      ? "低负载"
      : "完整负载";
  });

  observer.observe("cpu", { sampleInterval: 1000 }).catch((error) => {
    status.textContent = `压力观察失败：${error.name}`;
    mode.textContent = "低负载";
  });
}
```

接口缺失或观察请求遭拒时，代码都会选择低负载。

### 检查来源并停止观察

观察前可参考 `knownSources`，同时仍要处理拒绝。工作结束后调用 `disconnect()`。

```js
async function watchCpu(onRecords) {
  if (!("PressureObserver" in globalThis)) return null;
  if (!PressureObserver.knownSources.includes("cpu")) return null;

  const observer = new PressureObserver(onRecords);
  try {
    await observer.observe("cpu", { sampleInterval: 2000 });
    return observer;
  } catch {
    observer.disconnect();
    return null;
  }
}

const observer = await watchCpu((records) => console.log(records.at(-1)?.state));
document.addEventListener("visibilitychange", () => {
  if (document.hidden) observer?.disconnect();
});
```

接口缺失、来源未知或观察请求遭拒时，`null` 都能给调用方统一的回退信号。

## 另请参阅

- [Core Web Vitals](/zh/reference/performance/core-web-vitals/)，了解面向用户的加载与交互指标
- [Generic Sensor API](/zh/reference/capabilities/sensors/)，用于观察设备传感器
- [Compute Pressure Level 1](https://w3c.github.io/compute-pressure/)（w3c.github.io）
- [Compute Pressure API](https://developer.mozilla.org/en-US/docs/Web/API/Compute_Pressure_API)（MDN）