# Generic Sensor API 通用传感器

> Generic Sensor API 通过统一接口暴露 Accelerometer、Gyroscope 等设备传感器，需要安全上下文并经 Permissions API 授权。

**一句话：** 根据 MDN，Sensor APIs 是"一组遵循统一设计、以一致方式向 Web 平台暴露
设备传感器的接口"，其中包含 `Accelerometer`、`Gyroscope`、`Magnetometer` 和
`AmbientLightSensor` 等具体接口；开发者应使用这些子类，而非直接使用基类 `Sensor`。

## 支持情况

本站目前尚无该特性的兼容性数据集，因此请把下面的内容当作按"传感器 + 浏览器"逐一
给出的当前情况，而不是一句笼统的结论：

- 根据 MDN 的浏览器兼容性数据，Chrome 自 67 版起支持 `Accelerometer` 和
  `Gyroscope`，且无需任何标志位。
- 根据同一份兼容性数据，Chrome 自 56 版起支持 `Magnetometer` 和
  `AmbientLightSensor`，但仅在开启 `#enable-experimental-web-platform-features`
  标志位后才可用；Chrome for Android、Edge、Opera 以及 Samsung Internet for
  Android 对这两款传感器都镜像了同样的"需要标志位"状态。
- 根据 MDN 的浏览器兼容性数据，Firefox 和 Safari 均未实现上述四个接口中的任何一个。

## 如何使用

```js
const acl = new Accelerometer({ frequency: 60 });
acl.addEventListener('reading', () => {
  console.log(`Acceleration along the X-axis ${acl.x}`);
});
acl.start();
```

根据 MDN，使用传感器还需要用户通过
[Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API)
授权（不同传感器的权限名称不同，例如 `'accelerometer'`、`'magnetometer'`、
`'ambient-light-sensor'`），并且该特性"仅在安全上下文（HTTPS）中可用"。

## 如何在运行时检测

```js
function startAccelerometer(onReading) {
  if (!('Accelerometer' in window)) {
    // 回退：当前浏览器未暴露该接口。
    return null;
  }
  try {
    const sensor = new Accelerometer({ frequency: 60 });
    sensor.addEventListener('error', (event) => {
      console.error(`Sensor error: ${event.error.name}`);
    });
    sensor.addEventListener('reading', () => onReading(sensor));
    sensor.start();
    return sensor;
  } catch (error) {
    // 根据 MDN，当服务器端的 Permissions Policy 阻止该特性时，
    // Accelerometer() 构造函数会抛出 SecurityError。
    console.error(`Could not start sensor: ${error.name}`);
    return null;
  }
}
```

## 实用清单

- 针对具体接口做特性检测（如 `'Accelerometer' in window`），而不要假设四种传感器
  接口的可用性相同——根据 MDN 的浏览器兼容性数据，Chrome 对 `Accelerometer`/
  `Gyroscope`（无需标志位）与 `Magnetometer`/`AmbientLightSensor`（需要标志位）
  的标志位要求并不一致，不要假设所有 Chromium 传感器都需要同一个标志位。
- 处理传感器的 `error` 事件——根据 MDN，该事件触发后传感器会"进入空闲状态并停止
  读取数值"，直到重新启动。
- 构造函数抛出的 `SecurityError` 意味着 Permissions Policy 正在阻止该特性，这是
  MDN 为 `Accelerometer()` 记录的明确异常。
- Firefox 和 Safari 均未实现 `Accelerometer`、`Gyroscope`、`Magnetometer` 或
  `AmbientLightSensor`——请为这些浏览器设计真实可用的回退 UI，而不是留一个失效的
  功能入口。

## 相关参考

- [Geolocation API 地理位置](/zh/reference/capabilities/geolocation/) —— 另一个
  需要权限授权、同样要求安全上下文的设备能力。
- [Idle Detection API 空闲检测](/zh/reference/capabilities/idle-detection/) ——
  另一个受 Permissions API 限制、仅部分浏览器支持的能力。