接近传感器

1. 介绍

接近传感器扩展了通用传感器 API [GENERIC-SENSOR]，用于提供设备主接近传感器检测到的接近程度信息。接近程度以传感器到最近可见表面的距离（单位：厘米）报告。§ 9 接近传感器的局限性详细描述了潜在局限性，以及由于检测方法、传感器结构等差异，不同设备报告距离值可能不同的原因。此外，部分接近传感器可能只能提供一个布尔值，仅指示附近是否有物理对象，更类似于存在检测，而不是距离的绝对值。

2. 示例

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

sensor.onreading = () => console.log(sensor.distance);

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

3. 安全与隐私考虑

接近传感器提供关于传感器与邻近物体距离的信息，因此，可能泄露敏感隐私信息，导致用户识别和/或设备指纹识别攻击。

为降低这些风险，用户代理应采用以下一种或多种缓解策略：

降低传感器读数的精度
限制最大采样频率

这些缓解策略补充了通用传感器 API 中定义的通用缓解措施 [GENERIC-SENSOR]。

4. 权限策略集成

本规范定义了一个由字符串 "proximity-sensor" 标识的策略控制特性。其默认允许列表为 "self"。

5. 模型

接近传感器传感器类型具有如下关联数据：

扩展传感器接口: ProximitySensor
传感器权限名: "proximity"
传感器特性名: "proximity-sensor"
权限撤销算法: 用 "proximity" 调用通用传感器权限撤销算法。
默认传感器: 设备的主接近检测器。
虚拟传感器类型: "proximity"

最新读数对于 Sensor 的接近传感器类型包括三个条目，其键为 "distance"、"max"、"near"，其值为distance、max 和 near 值。

distance 表示设备与感应范围内最近可见物体表面间的距离，单位为厘米（cm）。

max 为主接近检测器最大感应范围，单位为厘米。

near 表示主接近检测器附近是否有可见物体表面。

6. API

6.1. ProximitySensor 接口

[SecureContext, Exposed=Window]
interface ProximitySensor : Sensor {
  constructor(optional SensorOptions sensorOptions = {});
  readonly attribute double? distance;
  readonly attribute double? max;
  readonly attribute boolean? near;
};

要构造 ProximitySensor 对象，用户代理必须调用构建 proximity sensor 对象抽象操作。

6.1.1. distance 属性

distance 属性返回用 this 和 "distance" 作为参数调用 get value from latest reading 的结果。

若物理对象超出感应范围，此属性必须返回 null。

6.1.2. max 属性

max 属性返回用 this 和 "max" 作为参数调用 get value from latest reading 的结果。

6.1.3. near 属性

near 属性返回用 this 和 "near" 作为参数调用 get value from latest reading 的结果。

若物理对象超出感应范围，此属性必须返回 null。

注意：如果实现无法直接提供 near 值，可以通过 distance 推断。例如，如果 distance 不等于 max，则表明感应范围内存在物体。

7. 抽象操作

7.1. 构建 proximity sensor 对象

input: options，一个 SensorOptions 对象。
output: 一个 ProximitySensor 对象。

令 allowed 为调用 check sensor policy-controlled features 并传入 ProximitySensor 的结果。
如果 allowed 为 false，则：
1. 抛出 SecurityError DOMException。
令 proximity_sensor 为新创建的 ProximitySensor 对象。
用 proximity_sensor 和 options 调用 initialize a sensor object。
返回 proximity_sensor。

8. 自动化

本节通过提供接近传感器专用的虚拟传感器元数据扩展了通用传感器 API § 9 自动化。

每种类型的虚拟传感器元数据 map 必须包含如下条目：

key: "proximity"
value: 一个虚拟传感器元数据，其读数解析算法为proximity 读数解析算法。

8.1. proximity 读数解析算法

input: parameters，一个 JSON Object
output: 一个传感器读数或undefined

令 reading 为一个新的传感器读数。
令 keys 为列表 « "distance", "max" »。
遍历 keys 中每个 key
1. 令 value 为用 parameters 和 key 调用 parse single-value number reading 的结果。
  1. 如果 value 为 undefined。
    1. 返回 undefined。
2. 设置 reading[key] 为 value[key]。
令 near 为用 "near" 从 parameters 取属性的结果。
1. 如果 near 类型不是布尔值
  1. 返回 undefined。
2. 设置 reading["near"] 为 near。
返回 reading。

9. 接近传感器的局限性

由于多数接近传感器依靠探测电磁辐射（如红外线或磁场），某些材料特性会影响传感器对物体的感应能力。可能影响传感器的因素包括但不限于材料的半透明性、反射性、颜色、温度、化学成分，以及物体反射辐射回传感器的角度。因此，接近传感器不应作为距离测量工具，唯一可以确定的是在最小至最大感应距离范围内一定有物体存在。

10. 致谢

Tobie Langel 为通用传感器 API 及本规范提供的贡献。 Doug Turner 提供初始原型， Marcos Caceres 贡献测试套件。

11. 一致性

一致性要求以描述性断言和 RFC 2119 术语结合表达。本规范规范性部分中的 "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"MAY" 和 "OPTIONAL" 的含义遵循 RFC 2119 规定。为便于阅读，这些词未全部大写。

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

一致性用户代理必须实现本规范中所有适用于用户代理的要求。

本规范中的 IDL 片段，需按照 Web IDL 规范的相关要求进行解释。[WEBIDL]