加速度计 (Accelerometer)

关于本文档

本节描述了本文件在发布时的状态。当前的 W3C 出版物列表和本技术报告的最新修订版可在 W3C 技术报告索引中找到。

本文档由设备与传感器工作组作为使用推荐路线的候选推荐草案发布。本文档旨在成为 W3C 推荐标准。

If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (订阅, 归档)。发送电子邮件时，请在主题中加入 “accelerometer”，最好写成这样：“[accelerometer] …评论摘要…”。欢迎所有评论。

作为候选推荐发布并不意味着得到W3C及其成员的认可。候选推荐草案会合并工作组计划在后续候选推荐快照中包含的上一版候选推荐的更改。此为草稿文件，可能随时被更新、替换或作废。引用时请将其视为进行中的工作。

该文档进入“拟定推荐”阶段的入口条件是至少有两个独立且可互操作的用户代理实现了本规范的全部特性，且通过工作组制定的测试套件中的用户代理测试。工作组将准备实现报告以跟踪进度。

本文档由一个遵守 W3C 专利政策的组织编写。W3C 维护一份公开的专利披露列表，列出与本工作组交付物相关的所有专利披露；该页面还包括披露专利的说明。任何实际了解某专利且认为该专利包含必要权利要求的个人，必须按照 W3C 专利政策第 6 节的要求进行披露。

本文件受 2025 年 8 月 18 日 W3C 流程文件的管辖。

本规范仅面向现有部署进行维护。多个浏览器引擎对本规范表达了顾虑。对于新项目，开发者应使用设备方向与运动，该规范拥有跨引擎支持。工作组计划在设备方向与运动中开发新的运动感知功能。

本文件随时维护和更新。本文件的某些部分正在完善中。

1. 引言

The Accelerometer, LinearAccelerationSensor and GravitySensor APIs extends the Generic Sensor API [GENERIC-SENSOR] interface to provide information about acceleration applied to device’s X, Y and Z axis in local coordinate system defined by device.

2. 示例

let sensor = new Accelerometer();
sensor.start();

sensor.onreading = () => {
    console.log("Acceleration along X-axis: " + sensor.x);
    console.log("Acceleration along Y-axis: " + sensor.y);
    console.log("Acceleration along Z-axis: " + sensor.z);
}

sensor.onerror = event => console.log(event.error.name, event.error.message);

以下示例演示了如何使用在屏幕坐标系中提供读取的 GravitySensor。该代码段将在 DOM screen 与地面垂直且渲染网页的底部朝下时，向控制台打印信息。

let sensor = new GravitySensor({frequency: 5, referenceFrame: "screen"});

sensor.onreading = () => {
  if (sensor.y >= 9.8) {
    console.log("Web page is perpendicular to the ground.");
  }
}

sensor.start();

以下示例检测设备在 X 轴方向的摇动手势，无论 DOM screen 的方向如何。

const shakeThreshold = 25;

let sensor = new LinearAccelerationSensor({frequency: 60});

sensor.addEventListener('reading', () => {
  if (sensor.x > shakeThreshold) {
    console.log("Shake detected.");
  }
});

sensor.start();

3. 用例和需求

这些用例和需求列在 Motion Sensors Explainer 与 Sensor use cases 文档中。

4. 安全与隐私考虑

传感器读取由惯性传感器（如加速度计）提供，可能被攻击者用于利用多种安全威胁，例如键盘记录、位置追踪、指纹识别与用户识别。

安全社区发表的研究论文，例如 [KEYSTROKEDEFENSE]，表明通过限制频率可以降低成功攻击的风险，但并未彻底消除风险，而频率限制会极大影响那些因正当理由需要使用传感器的 Web 应用的可用性。

[TOUCHSIGNATURES] 与 [ACCESSORY] 两篇论文提出，实现可以在惯性传感器被使用时提供可视化指示，或要求用户明确同意才能访问传感器读取。这些缓解策略与 Generic Sensor API 中定义的通用缓解措施相辅相成。

This specification defines an accelerometer reading quantization algorithm (called from the get value from latest reading operation) to mitigate sensor calibration fingerprinting [SENSORID] and attacks that rely on high precision sensor readings. The details of the quantization algorithm follow W3C Privacy Interest Group’s recommendation.

5. 权限策略集成

This specification utilizes the policy-controlled feature identified by the string "accelerometer" defined in [DEVICE-ORIENTATION].

6. 模型

6.1. Accelerometer（加速度计）

The Accelerometer sensor type has the following associated data

扩展传感器接口: 加速度计 (Accelerometer)
传感器权限名称: "accelerometer"
传感器特性名称: "accelerometer"
权限撤销算法: Invoke the generic sensor permission revocation algorithm with "accelerometer".
默认传感器: The device’s main accelerometer sensor.
虚拟传感器类型: "accelerometer"

A latest reading for a Sensor of Accelerometer sensor type includes three entries whose keys are "x", "y", "z" and whose values contain device’s acceleration about the corresponding axes.

The acceleration is the rate of change of velocity of a device with respect to time. Its unit is the metre per second squared (m/s²) [SI].

The frame of reference for the acceleration measurement must be inertial, such as, the device in free fall would provide 0 (m/s²) acceleration value for each axis.

The sign of the acceleration values must be according to the right-hand convention in a local coordinate system (see figure below).

Accelerometer coordinate system.

6.2. Linear Acceleration Sensor（线性加速度传感器）

The Linear Acceleration Sensor sensor type has the following associated data

扩展传感器接口: LinearAccelerationSensor
传感器权限名称: "accelerometer"
传感器特性名称: "accelerometer"
权限撤销算法: Invoke the generic sensor permission revocation algorithm with "accelerometer".
虚拟传感器类型: "linear-acceleration"

A latest reading for a Sensor of Linear Acceleration Sensor sensor type includes three entries whose keys are "x", "y", "z" and whose values contain device’s linear acceleration about the corresponding axes.

The linear acceleration is an acceleration that is applied to the device that hosts the sensor, without the contribution of a gravity force.

Note: The relationship between gravity and linear acceleration is discussed in Motion Sensors Explainer § gravity-and-linear-acceleration.

6.3. Gravity Sensor（重力传感器）

The Gravity Sensor sensor type has the following associated data

扩展传感器接口: GravitySensor
传感器权限名称: "accelerometer"
传感器特性名称: "accelerometer"
权限撤销算法: Invoke the generic sensor permission revocation algorithm with "accelerometer".
虚拟传感器类型: "gravity"

A latest reading for a Sensor of Gravity Sensor sensor type includes three entries whose keys are "x", "y", "z" and whose values contain the acceleration due to gravity about the corresponding axes.

The gravity is the component of the device’s acceleration that prevents its velocity from increasing toward nearby masses. Devices in free fall for more than a short period of time may compute incorrect values for the gravity.

Note: The relationship between gravity and linear acceleration is discussed in Motion Sensors Explainer § gravity-and-linear-acceleration.

6.4. 参考框架

The local coordinate system represents the reference frame for the Accelerometer, LinearAccelerationSensor, and the GravitySensor readings. It can be either the device coordinate system or the screen coordinate system.

The device coordinate system is defined as a three dimensional Cartesian coordinate system (x, y, z), which is bound to the physical device. For devices with a display, the origin of the device coordinate system is the center of the device display. If the device is held in its default position, the Y-axis points towards the top of the display, the X-axis points towards the right of the display and Z-axis is the vector product of X and Y axes and it points outwards from the display, and towards the viewer. The device coordinate system remains stationary regardless of the dom screen orientation (see figure below).

Device coordinate system.

The screen coordinate system is defined as a three dimensional Cartesian coordinate system (x, y, z), which is bound to the dom screen. The origin of the screen coordinate system in the center of the dom screen. The Y-axis always points towards the top of the dom screen, the X-axis points towards the right of the dom screen and Z-axis is the vector product of X and Y axes and it and it points outwards from the dom screen, and towards the viewer (see figure below).

Screen coordinate system.

The main difference between the device coordinate system and the screen coordinate system, is that the screen coordinate system always follows the dom screen orientation, i.e. it will swap X and Y axes in relation to the device if the current orientation type changes. In contrast, the device coordinate system will always remain stationary relative to the device.

7. API

7.1. Accelerometer 接口

[SecureContext, Exposed=Window]
interface Accelerometer : Sensor {
  constructor(optional AccelerometerSensorOptions options = {});
  readonly attribute double? x;
  readonly attribute double? y;
  readonly attribute double? z;
};

enum AccelerometerLocalCoordinateSystem { "device", "screen" };

dictionary AccelerometerSensorOptions : SensorOptions {
  AccelerometerLocalCoordinateSystem referenceFrame = "device";
};

The new Accelerometer(options) constructor steps are to invoke the construct an accelerometer object abstract operation with this and options.

Supported sensor options for Accelerometer are "frequency" and "referenceFrame".

7.1.1. Accelerometer.x

The x attribute of the Accelerometer interface returns the result of invoking get value from latest reading with this and "x" as arguments. It represents the acceleration along x-axis.

7.1.2. Accelerometer.y

The y attribute of the Accelerometer interface returns the result of invoking get value from latest reading with this and "y" as arguments. It represents the acceleration along y-axis.

7.1.3. Accelerometer.z

The z attribute of the Accelerometer interface returns the result of invoking get value from latest reading with this and "z" as arguments. It represents the acceleration along z-axis.

7.2. LinearAccelerationSensor 接口

[SecureContext, Exposed=Window]
interface LinearAccelerationSensor : Accelerometer {
  constructor(optional AccelerometerSensorOptions options = {});
};

The new LinearAccelerationSensor(options) constructor steps are to invoke the construct an accelerometer object abstract operation with this and options.

Supported sensor options for LinearAccelerationSensor are "frequency" and "referenceFrame".

7.2.1. LinearAccelerationSensor.x

The x attribute of the LinearAccelerationSensor interface returns the result of invoking get value from latest reading with this and "x" as arguments. It represents the linear acceleration along x-axis.

7.2.2. LinearAccelerationSensor.y

The y attribute of the LinearAccelerationSensor interface returns the result of invoking get value from latest reading with this and "y" as arguments. It represents the linear acceleration along y-axis.

7.2.3. LinearAccelerationSensor.z

The z attribute of the LinearAccelerationSensor interface returns the result of invoking get value from latest reading with this and "z" as arguments. It represents the linear acceleration along z-axis.

7.3. GravitySensor 接口

[SecureContext, Exposed=Window]
interface GravitySensor : Accelerometer {
  constructor(optional AccelerometerSensorOptions options = {});
};

The new GravitySensor(options) constructor steps are to invoke the construct an accelerometer object abstract operation with this and options.

Supported sensor options for GravitySensor are "frequency" and "referenceFrame".

7.3.1. GravitySensor.x

The x attribute of the GravitySensor interface returns the result of invoking get value from latest reading with this and "x" as arguments. It represents the effect of acceleration along x-axis due to gravity.

7.3.2. GravitySensor.y

The y attribute of the GravitySensor interface returns the result of invoking get value from latest reading with this and "y" as arguments. It represents the effect of acceleration along y-axis due to gravity.

7.3.3. GravitySensor.z

The z attribute of the GravitySensor interface returns the result of invoking get value from latest reading with this and "z" as arguments. It represents the effect of acceleration along z-axis due to gravity.

8. 抽象操作

8.1. 构造 Accelerometer 对象

input (输入): object, an Accelerometer, LinearAccelerationSensor or GravitySensor object.; options, a AccelerometerSensorOptions object.

Let allowed be the result of invoking check sensor policy-controlled features with object’s sensor type.
If allowed is false, then
1. Throw a SecurityError DOMException.
Invoke initialize a sensor object with object and options.
If options.referenceFrame is "screen", then
1. Set object’s local coordinate system to the screen coordinate system.
Otherwise, define object’s local coordinate system to the device coordinate system.

8.2. Accelerometer 读取量化算法

The Accelerometer sensor type defines the following reading quantization algorithm

input (输入): reading, a sensor reading
output: A sensor reading

Let quantizedReading be reading.
If quantizedReading["x"] is not null, set quantizedReading["x"] to the nearest 0.1 m/s².
If quantizedReading["y"] is not null, set quantizedReading["y"] to the nearest 0.1 m/s².
If quantizedReading["z"] is not null, set quantizedReading["z"] to the nearest 0.1 m/s².
Return quantizedReading.

9. 自动化

This section extends Generic Sensor API § 9 Automation by providing Accelerometer-specific virtual sensor metadata. Some of the virtual sensor types used by this specification are defined in [DEVICE-ORIENTATION].

10. 致谢

Tobie Langel for the work on Generic Sensor API.

W3C Privacy Interest Group and Paul Jensen for the sensor calibration fingerprinting mitigation proposal and discussion.

一致性

文档约定

一致性要求通过描述性断言和 RFC 2119 术语相结合来表达。本文档规范性部分中的关键词“MUST”（必须）、“MUST NOT”（不得）、“REQUIRED”（必需）、“SHALL”（应）、“SHALL NOT”（不应）、“SHOULD”（推荐）、“SHOULD NOT”（不推荐）、“RECOMMENDED”（建议）、“MAY”（可以）和“OPTIONAL”（可选）应按照 RFC 2119 中的描述进行解释。然而，为了可读性，这些词在本文档中不以全大写形式出现。

本规范的所有文本均为规范性文本，明确标记为非规范性的部分、示例和注释除外。 [RFC2119]

本规范中的示例均以“例如”一词引入，或者通过 class="example" 与规范性文本隔开，如下所示

这是一个说明性示例。

说明性注释以“Note”一词开头，并使用 class="note" 与规范性文本隔开，如下所示

注意，这是一个说明性注释。