WebHID API

WebIDL[SecureContext] partial interface Navigator {
    [SameObject] readonly attribute HID hid;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker), SecureContext]
partial interface WorkerNavigator {
    [SameObject] readonly attribute HID hid;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HID : EventTarget {
    attribute EventHandler onconnect;
    attribute EventHandler ondisconnect;
    Promise<sequence<HIDDevice>> getDevices();
    [Exposed=Window] Promise<sequence<HIDDevice>> requestDevice(
        HIDDeviceRequestOptions options);
};

HID 的实例带有下表所述的内部槽创建：

onconnect 属性

onconnect 是用于 connect 事件类型的 事件处理程序 IDL 属性。

ondisconnect 属性

ondisconnect 是用于 disconnect 事件类型的 事件处理程序 IDL 属性。

当系统上某个 HID 接口变为可用时，执行以下步骤：

1. 令 device 为一个 HIDDevice。
2. 将 device.[[vendorId]] 设为暴露该接口的设备的 厂商 ID。
3. 将 device.[[productId]] 设为暴露该接口的设备的 产品 ID。
4. 将 device.[[productName]] 设为暴露该接口的设备的 产品名称。
5. 将 device.[[collections]] 设为 解析报告描述符 的结果。
6. 若 device 的 相关全局对象 是 Window 对象，则令 hid 为调用该对象的 hid getter 的结果；否则令其为调用 WorkerNavigator 对象的 hid getter 的结果。
7. 将 device 追加到 hid.[[devices]]。
8. 如果由于之前调用 requestDevice()，用户已允许站点访问 device，则在 hid 的 相关全局对象 上， 使用 HID 设备任务源 触发一个名为 connect 的事件到 hid，并使用 HIDConnectionEvent， 其 device 属性初始化为 device。

要解析报告 描述符，执行以下步骤：

1. 令 items 为将 report descriptor 的 字节序列 转换为一个 列表 的结果， 该列表由 Main items、Global items 和 Local items 组成。
2. 将 collections 初始化为空的 sequence，元素类型为 HIDCollectionInfo。
3. 将 ancestors 初始化为空 列表。
4. 将 localState 初始化为空 有序映射。
5. 将 usages 初始化为空的 sequence（unsigned long）。
6. 将 stringIndices 初始化为空 列表。
7. 将 globalStack 初始化为空 栈。
8. 将 initialGlobalState 初始化为空 有序映射。
9. 将 reportId 设为 0。
10. 将 initialGlobalState["unitSystem"] 设为 "none"。
11. 将 initialGlobalState["unitExponent"] 设为 0。
12. 将 initialGlobalState["unitFactorLengthExponent"] 设为 0。
13. 将 initialGlobalState["unitFactorMassExponent"] 设为 0。
14. 将 initialGlobalState["unitFactorTimeExponent"] 设为 0。
15. 将 initialGlobalState["unitFactorTemperatureExponent"] 设为 0。
16. 将 initialGlobalState["unitFactorCurrentExponent"] 设为 0。
17. 将 initialGlobalState["unitFactorLuminousIntensityExponent"] 设为 0。
18. 将 initialGlobalState["logicalMinimum"] 设为 0。
19. 将 initialGlobalState["logicalMaximum"] 设为 0。
20. 将 initialGlobalState["physicalMinimum"] 设为 0。
21. 将 initialGlobalState["physicalMaximum"] 设为 0。
22. 压入 initialGlobalState 到 globalStack。
23. 对每个 item（属于 items）：
    Note

    Main items 在 [USBIF-HID-CLASS] 第 6.2.2.4 至 6.2.2.6 节中描述。带有 Input tag、 Output tag 或 Feature tag 的条目定义输入、输出或功能报文中的一个字段。 具有 Input tag、 Output tag 或 Feature tag 的 Main item 的 item data field 是一个位字段，包含若干布尔参数用于描述该数据字段。带有 Collection tag 的条目会在当前集合内定义一个新集合， 若不存在当前集合则定义一个新的 顶级集合。 带有 Collection tag 的 Main item 的 item data field 包含 collection type。带有 End Collection tag 的条目会关闭当前集合。

    • 如果 item 是 Main item：
      1. 如果 item 具有 Input tag、 Output tag 或 Feature tag：
         1. 令 globalState 为 globalStack 的最后一个 条目。
         2. 令 reportId 为 globalState["reportId"]。
         3. 令 reportItem 为 创建 HID 报告项 的结果， 传入 item、localState、globalState、usages 和 strings。
         4. 对每个 属于 ancestors 的 collection：
            1. 令 reports 为：
               • 若 item 具有 Input tag，则为 collection["inputReports"]
               • 若 item 具有 Output tag，则为 collection["outputReports"]
               • 若 item 具有 Feature tag，则为 collection["featureReports"]

            2. 如果 reports 含有其 reportId 属性等于 reportId 的条目，则令 report 为该条目。

               否则：

               1. 令 report 为 新的 HIDReportInfo 字典。
               2. 将 report["reportId"] 设为 reportId。
               3. 将 report["items"] 设为空的 sequence， 元素类型为 HIDReportItem。
               4. 追加 report 到 reports。
            3. 追加 item 到 report["items"]。
      2. 如果 item 具有 Collection tag：
         1. 令 collection 为 新的 HIDCollectionInfo 字典。
         2. 令 usage 为 usages 的第一个 条目。
         3. 如果 usages 的 大小 大于 1， 则移除 usages 的第一个 条目。
         4. 将 collection["usagePage"] 设为 globalState["usagePage"]。
         5. 将 collection["usage"] 设为 usage。
         6. 将 collection["type"] 设为表示集合类型的值。
         7. 将 collection["children"] 设为 空的 sequence， 元素类型为 HIDCollectionInfo。
         8. 将 collection["inputReports"] 设为空的 sequence， 元素类型为 HIDReportInfo。
         9. 将 collection["outputReports"] 设为空的 sequence， 元素类型为 HIDReportInfo。
         10. 将 collection["featureReports"] 设为空的 sequence， 元素类型为 HIDReportInfo。

         11. 如果 ancestors 为空， 追加 collection 到 collections。

             否则：

             1. 令 parent 为 ancestors 的最后一个 条目。
             2. 追加 collection 到 parent["children"]。
         12. 追加 collection 到 ancestors。
      3. 如果 item 具有 End Collection tag，则 移除 ancestors 的最后一个 条目。
      4. 将 localState 设为空 有序映射。
      5. 将 usages 设为空的 sequence（unsigned long）。
         Note

         Global items 在第 6.2.2.7 节中描述。 带有 Usage Page tag、 Logical Minimum tag、Logical Maximum tag、 Physical Minimum tag、 Physical Maximum tag、Unit Exponent tag、 Unit tag、Report Size tag、 Report ID tag 或 Report Count tag 的条目会修改全局条目状态表的相应字段。 带有 Push tag 的条目会将当前全局条目状态表的副本压入条目状态栈。 带有 Pop tag 的条目会将全局条目状态表替换为条目状态栈的栈顶。 在操作条目状态栈时，全局 Report ID 值不受影响。

      6. 如果 item 是 Global item：
         1. 令 globalState 为 globalStack 的最后一个 条目。
         2. 令 value 为 item data field 作为 unsigned long 解释的结果。
         3. 如果 item 具有 Usage Page tag，则将 globalState["usagePage"] 设为 value。
         4. 如果 item 具有 Logical Minimum tag，则将 globalState["logicalMinimum"] 设为 value。
         5. 如果 item 具有 Logical Maximum tag，则将 globalState["logicalMaximum"] 设为 value。
         6. 如果 item 具有 Physical Minimum tag，则将 globalState["physicalMinimum"] 设为 value。
         7. 如果 item 具有 Physical Maximum tag，则将 globalState["physicalMaximum"] 设为 value。
         8. 如果 item 具有 Report Size tag，则将 globalState["reportSize"] 设为 value。
         9. 如果 item 具有 Report ID tag，则将 globalState["reportId"] 设为 value。
         10. 如果 item 具有 Report Count tag，则将 globalState["reportCount"] 设为 value。
         11. 如果 item 具有 Unit tag：
             1. 令 nibbles 为将 value 自低位起按 8 个 4 位有符号二进制补码整数解释得到的 sequence。
             2. 如果 nibbles[0] 为：
                • 0，则将 globalState["unitSystem"] 设为 "none"
                • 1，则将 globalState["unitSystem"] 设为 "si-linear"
                • 2，则将 globalState["unitSystem"] 设为 "si-rotation"
                • 3，则将 globalState["unitSystem"] 设为 "english-linear"
                • 4，则将 globalState["unitSystem"] 设为 "english-rotation"
                • -1，则将 globalState["unitSystem"] 设为 "vendor-defined"
                • 否则，将 globalState["unitSystem"] 设为 "reserved"
             3. 将 globalState["unitFactorLengthExponent"] 设为 nibbles[1]。
             4. 将 globalState["unitFactorMassExponent"] 设为 nibbles[2]。
             5. 将 globalState["unitFactorTimeExponent"] 设为 nibbles[3]。
             6. 将 globalState["unitFactorTemperatureExponent"] 设为 nibbles[4]。
             7. 将 globalState["unitFactorCurrentExponent"] 设为 nibbles[5]。
             8. 将 globalState["unitFactorLuminousIntensityExponent"] 设为 nibbles[6]。
         12. 如果 item 具有 Unit Exponent tag，则将 globalState["unitExponent"] 设为将 item data field 的最低 4 位作为有符号二进制补码整数解释的结果。
         13. 如果 item 具有 Push tag，则 将 globalState 的副本压入 globalStack。
         14. 如果 item 具有 Pop tag，则从 globalStack 弹出。
      Note

      Local items 在第 6.2.2.8 节中描述。 带有 Usage tag、Usage Minimum tag、 Usage Maximum tag、String Index tag、 String Minimum tag 或 String Maximum tag 的条目会修改本地条目状态表的相应字段。每个 Main item 之后，本地条目状态会被清空。

    • 如果 item 是 Local item：
      1. 令 value 为 item data field 作为 unsigned long 解释的结果。
      2. 如果 item 具有 Usage tag：
         1. 如果 item 的 bSize field 为 1 或 2：
            1. 令 usageId 为一个 unsigned short，包含 value 的低 16 位。
            2. 令 globalState 为 globalStack 的最后一个 条目。
            3. 将 value 设为一个由 globalState["usagePage"] 位于高位、usageId 位于低位组成的 HID usage。
         2. 追加 value 到 usages。
      3. 如果 item 具有 Usage Minimum tag，则将 localState["usageMinimum"] 设为 value。
      4. 如果 item 具有 Usage Maximum tag，则将 localState["usageMaximum"] 设为 value。
      5. 如果 item 具有 String Index tag，则 追加 value 到 stringIndices。
      6. 如果 item 具有 String Minimum tag，则将 localState["stringMinimum"] 设为 value。
      7. 如果 item 具有 String Maximum tag，则将 localState["stringMaximum"] 设为 value。

要使用 item、localState、globalState、usages 和 stringIndices 创建 HID 报告项，执行以下步骤：

1. 令 reportItem 为 新的 HIDReportItem 字典。
2. 令 value 为 item data field 作为 unsigned long 解释的结果。
3. 令 bitfield 为一个 列表，其布尔值自低位起表示 value 的各位。
4. 将 reportItem["isConstant"] 设为 bitfield[0]。
5. 将 reportItem["isArray"] 设为 !bitfield[1]。
6. 将 reportItem["isAbsolute"] 设为 !bitfield[2]。
7. 将 reportItem["wrap"] 设为 bitfield[3]。
8. 将 reportItem["isLinear"] 设为 !bitfield[4]。
9. 将 reportItem["hasPreferredState"] 设为 bitfield[5]。
10. 将 reportItem["hasNull"] 设为 bitfield[6]。
11. 将 reportItem["isVolatile"] 设为 bitfield[7]。
12. 将 reportItem["isBufferedBytes"] 设为 bitfield[8]。
13. 将 reportItem["usages"] 设为 usages。
14. 将 reportItem["reportSize"] 设为 globalState["reportSize"]。
15. 将 reportItem["reportCount"] 设为 globalState["reportCount"]。
16. 将 reportItem["unitExponent"] 设为 globalState["unitExponent"]。
17. 将 reportItem["unitSystem"] 设为 globalState["unitSystem"]。
18. 将 reportItem["unitFactorLengthExponent"] 设为 globalState["unitFactorLengthExponent"]。
19. 将 reportItem["unitFactorMassExponent"] 设为 globalState["unitFactorMassExponent"]。
20. 将 reportItem["unitFactorTimeExponent"] 设为 globalState["unitFactorTimeExponent"]。
21. 将 reportItem["unitFactorTemperatureExponent"] 设为 globalState["unitFactorTemperatureExponent"]。
22. 将 reportItem["unitFactorCurrentExponent"] 设为 globalState["unitFactorCurrentExponent"]。
23. reportItem["unitFactorLuminousIntensityExponent"] 设为 globalState["unitFactorLuminousIntensityExponent"]。
24. 将 reportItem["logicalMinimum"] 设为 globalState["logicalMinimum"]。
25. 将 reportItem["logicalMaximum"] 设为 globalState["logicalMaximum"]。

26. 如果 usageMinimum 存在于 localState 中，则将 reportItem["usageMinimum"] 设为 localState["usageMinimum"]。

27. 如果 usageMaximum 存在于 localState 中，则将 reportItem["usageMaximum"] 设为 localState["usageMaximum"]。

28. 当 reportItem["usageMinimum"] 小于 reportItem["usageMaximum"] 时， 将 reportItem["isRange"] 设为 true， 否则设为 false。
29. 如果 "stringMinimum" 与 "stringMaximum" 同时存在于 localState 中：
    1. 追加 范围 从 localState["stringMinimum"] 到 localState["stringMaximum"] 的 条目到 stringIndices。
30. 对每个 属于 stringIndices 的 stringIndex：
    1. 令 string 为读取索引 stringIndex 处字符串描述符的结果。
    2. 追加 string 到 reportItem["strings"]。
31. 返回 reportItem。

当系统上某个 HID 接口变为不可用时，执行以下步骤：

1. 令 device 为 hid.[[devices]] 中表示该接口的 HIDDevice。
2. 若 device 的 相关 全局对象 是 Window 对象，则令 hid 为调用该对象的 hid getter 的结果；否则令其为调用 WorkerNavigator 对象的 hid getter 的结果。
3. 从 hid.[[devices]] 移除 device。
4. 如果由于之前调用 requestDevice()，用户已允许站点访问 device，则在 hid 的 相关全局对象 上， 使用 HID 设备任务源 触发一个名为 disconnect 的事件到 hid， 并使用 HIDConnectionEvent， 其 device 属性初始化为 device。

WebIDLdictionary HIDDeviceRequestOptions {
    required sequence<HIDDeviceFilter> filters;
    sequence<HIDDeviceFilter> exclusionFilters;
};

WebIDLdictionary HIDDeviceFilter {
    unsigned long vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDDevice : EventTarget {
    attribute EventHandler oninputreport;
    readonly attribute boolean opened;
    readonly attribute unsigned short vendorId;
    readonly attribute unsigned short productId;
    readonly attribute DOMString productName;
    readonly attribute FrozenArray<HIDCollectionInfo> collections;
    Promise<undefined> open();
    Promise<undefined> close();
    Promise<undefined> forget();
    Promise<undefined> sendReport([EnforceRange] octet reportId, BufferSource data);
    Promise<undefined> sendFeatureReport(
        [EnforceRange] octet reportId,
        BufferSource data);
    Promise<DataView> receiveFeatureReport([EnforceRange] octet reportId);
};

此接口上的方法通常异步完成，在 HID 设备任务源 上排队工作。

HIDDevice 的实例带有下表所述的内部槽创建：

oninputreport 属性

oninputreport 是 事件处理程序 IDL 属性， 用于 inputreport 事件类型。

opened 属性

指示 HIDDevice 已准备好传输数据的标志。

opened getter 的步骤为：

1. 如果 this.[[state]] 为 opened，则返回 true。
2. 返回 false。

vendorId 属性

vendor ID 是由厂商 ID 来源分配的 unsigned short 值，用于标识设备制造商。

vendorId 属性是设备的 vendor ID。如果设备没有 vendor ID 或无法访问该 vendor ID，则该属性 必须（MUST） 为 0。

vendorId getter 的步骤为：

1. 返回 this.[[vendorId]]。

productId 属性

product ID 是由设备制造商分配的 unsigned short 值，用于标识产品。

productId 属性是设备的 product ID。如果设备没有 product ID 或无法访问该 product ID，则该属性 必须（MUST） 为 0。

productId getter 的步骤为：

1. 返回 this.[[productId]]。

productName 属性

标识产品的字符串。

对于 USB HID 设备，product name 应当（SHOULD） 包含设备描述符中 iProduct 索引处字符串描述符的值。对于蓝牙 HID 设备，product name 应当（SHOULD） 包含设备名称（Device Name）特征的值。 如果设备没有 product name，或 product name 为空或无法访问，则该属性 必须（MUST） 返回空字符串。

productName 字符串 不应（SHOULD NOT） 包含任何可用于唯一标识设备的标识符，如序列号或蓝牙设备地址。

productName getter 的步骤为：

1. 返回 this.[[productName]]。

collections 属性

一个 sequence（元素类型为 HIDCollectionInfo），表示 report descriptor 中的 顶级集合。

collections getter 的步骤为：

1. 返回 this.[[collections]]。

Note

顶级集合 用于分组设备内用途相似的条目。 应用会查看应用于 顶级集合 的 HID usage 来识别设备。 如果设备未遵循特定设备类型的惯例，应用可能无法识别该设备。有关标准 HID 设备的常规行为的更多信息，请参阅 [USBIF-HID-USAGE]。

当从一个 device 收到输入报告时，执行以下步骤：

1. 如果该输入报告是一个 被阻止的报告（blocked report），则中止这些步骤。
2. 令 reportId 为此报告的报告 ID；如果该 HID 接口不 使用报告 ID， 则为 0。
3. 令 data 为在表示该输入报告的 字节序列 之上创建的 DataView。 如果该 HID 接口 使用报告 ID，则该 字节序列 不得（MUST NOT） 包含报告 ID 字节。
4. 在相关全局对象上队列一个全局任务（属于 this）， 使用 HID 设备任务源 触发事件 名为 inputreport，目标为 device， 事件类型为 HIDInputReportEvent，其 device 属性初始化为 device， reportId 属性初始化为 reportId，data 属性初始化为 data。

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDConnectionEvent : Event {
    constructor(DOMString type, HIDConnectionEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
};

device 属性

表示已连接或已断开设备的 HIDDevice 实例。

WebIDLdictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDInputReportEvent : Event {
    constructor(DOMString type, HIDInputReportEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
    readonly attribute octet reportId;
    readonly attribute DataView data;
};

device 属性

表示发送输入报告的 HIDDevice 实例，对应的 HID 接口。

reportId 属性

此报告的一字节标识前缀；如果 HID 接口 不 使用报告 ID，则为 0。

data 属性

一个 DataView，包含输⼊报告的数据。 如果 HID 接口 使用报告 ID，则排除 reportId 字节。

WebIDLdictionary HIDInputReportEventInit : EventInit {
    required HIDDevice device;
    required octet reportId;
    required DataView data;
};

WebIDLdictionary HIDCollectionInfo {
    unsigned short usagePage;
    unsigned short usage;
    octet type;
    sequence<HIDCollectionInfo> children;
    sequence<HIDReportInfo> inputReports;
    sequence<HIDReportInfo> outputReports;
    sequence<HIDReportInfo> featureReports;
};

当设备首次连接到系统时，系统必须（MUST）为设备所暴露的每个HID 接口获取报告描述符（report descriptor）。报告描述符是一个字节序列，可以展开为描述设备支持的每个报告布局的分层数据结构。该数据结构的元素称为 item。具有某种关系的一组 item 称为 collection。

HIDCollectionInfo 对象表示 报告描述符 中的一个集合（collection）。当集合中包含嵌套集合时，嵌套集合会作为 children 的元素被包含在内。

inputReports、 outputReports 和 featureReports 属性包含 序列（sequence）， 元素类型为 HIDReportInfo，用于描述本集合中的每一个报告。对于顶级集合（top-level collection）， HIDReportInfo 表示该报告所有组成项的扁平视图。该视图会将嵌套集合中的 item 与顶级集合本身包含的 item 混合列出。 对于嵌套集合，HIDReportInfo 仅包含该集合及其内部嵌套集合中的 item。

usagePage 成员

本集合关联的 HID usage 的 usage page 部分。

HID usage 是应用可用于识别某个 item 或 collection 目的和含义的常量。 HID usage 是一个 unsigned long，高位为 unsigned short 的 usage page，低位为 unsigned short 的 usage ID。标准 HID usage 值见 [USBIF-HID-CLASS] 和 USB 实现者论坛等文档。

设备暴露的 顶级集合 的 HID usage 用于标识设备的大致类型。

usage 成员

本集合关联的 HID usage 的 usage ID 部分。

usage ID 用于在 usage page 上选中某个具体 HID usage。惯例上，0x01~0x1F 号 usage ID 预留给 顶级集合。

type 成员

表示集合类型（collection type）的值。

集合类型	值
物理（Physical）	0x00
应用（Application）	0x01
逻辑（Logical）	0x02
报告（Report）	0x03
命名数组（Named Array）	0x04
用法切换（Usage Switch)	0x05
用法修改（Usage Modified）	0x06
保留以后扩展	0x07 到 0x7F
厂商自定义（Vendor-defined）	0x80 到 0xFF

每种集合类型代表分组 item 间不同的关系。 更多集合类型内容见 [USBIF-HID-CLASS] 6.2.2.6 节。

children 成员

一个 序列（sequence），元素类型为 HIDCollectionInfo，表示本集合内的嵌套集合。

inputReports 成员

一个 序列（sequence）， 元素类型为 HIDReportInfo，表示本集合内描述的输入报告。

outputReports 成员

一个 序列（sequence）， 元素类型为 HIDReportInfo，表示本集合内描述的输出报告。

featureReports 成员

一个 序列（sequence）， 元素类型为 HIDReportInfo，表示本集合内描述的功能报告（feature report）。

WebIDLdictionary HIDReportInfo {
    octet reportId;
    sequence<HIDReportItem> items;
};

HIDReportInfo 表示报告描述符中的一个输入、输出或功能报告。

reportId 成员

如果HID 接口使用报告 ID（use report IDs）， 则每个报告传输会加上一字节标识前缀。reportId 成员就是该报告的前缀，否则为 0。

items 成员

一个 序列（sequence）， 元素类型为 HIDReportItem，表示该报告的所有字段。

WebIDLdictionary HIDReportItem {
    boolean isAbsolute;
    boolean isArray;
    boolean isBufferedBytes;
    boolean isConstant;
    boolean isLinear;
    boolean isRange;
    boolean isVolatile;
    boolean hasNull;
    boolean hasPreferredState;
    boolean wrap;
    sequence<unsigned long> usages;
    unsigned long usageMinimum;
    unsigned long usageMaximum;
    unsigned short reportSize;
    unsigned short reportCount;
    byte unitExponent;
    HIDUnitSystem unitSystem;
    byte unitFactorLengthExponent;
    byte unitFactorMassExponent;
    byte unitFactorTimeExponent;
    byte unitFactorTemperatureExponent;
    byte unitFactorCurrentExponent;
    byte unitFactorLuminousIntensityExponent;
    long logicalMinimum;
    long logicalMaximum;
    long physicalMinimum;
    long physicalMaximum;
    sequence<DOMString> strings;
};

isAbsolute 成员

如果数据是绝对值（基于固定原点），则为 true，如果数据是相对值（表示与上一个报告数值的变化量），则为 false。

isArray 成员

如果该项在报告中创建了数组数据域（每个数据域包含对应按下按钮或键的索引），则为 true； 如果该项创建了变量数据域（每个数据域包含一个数值），则为 false。

isBufferedBytes 成员

如果该项发射固定字节流，则为 true，如果该项是一个数值类型，则为 false。

isConstant 成员

如果该项是静态只读字段并且不可修改，则为 true，如果该项为可修改设备数据的报告字段，则为 false。

isLinear 成员

如果该项表示测量结果与报告结果之间是线性关系，则为 true；如果数据经过处理则为 false。

isRange 成员

如果该项为由 usageMinimum 与 usageMaximum 定义的 HID 用法范围赋予用法，则为 true； 如果该项有一个 用法值序列 usages，则为 false。

isVolatile 成员

如果项的数值可在主机无交互时改变，则为 true； 如果仅能被主机改变则为 false。

仅用于功能项（Feature）和输出项（Output）。

hasNull 成员

如果该项存在空状态（即不发送有意义数据），则为 true；若无空状态则为 false。 处于空状态时，该项会上报超出 logicalMinimum 和 logicalMaximum 指定范围的值。

hasPreferredState 成员

如果该项有一个偏好状态，当用户未对控件操作时会回到该状态，则为 true；没有偏好状态则为 false。

wrap 成员

如果项的数值在达到最大或最小极值时会回卷，则为 true；若不会回卷则为 false。

usages 成员

若 isRange 为 true，或此项无关联 HID 用法值，则 usages 必须（MUST） 为 undefined。

若 isRange 为 false， usages 是一个 值序列，元素为关联到此项的 HID 用法值。

usageMinimum 成员

若 isRange 为 true， usageMinimum 包含本项的用法范围的最小 HID 用法值。

若 isRange 为 false， usageMinimum 必须（MUST） 为 undefined。

usageMaximum 成员

若 isRange 为 true， usageMaximum 包含本项的用法范围的最大 HID 用法值。

若 isRange 为 false， usageMaximum 必须（MUST） 为 undefined。

reportSize 成员

每个报告数据域的位数，reportSize 必须（MUST） 大于 0。

reportCount 成员

本项在报告中包含的字段数，reportCount 必须（MUST） 大于 0。

unitExponent 成员

单位指数值，如果该项没有单位定义则为 0。

unitSystem 成员

HIDUnitSystem 枚举值，指定单位定义的单位制。 若无单位定义，则为 "none"。

unitFactorLengthExponent 成员

单位定义中长度单位（厘米、弧度、英寸或度）的指数值，没有单位定义则为 0。

unitFactorMassExponent 成员

单位定义中质量单位（克或 slug）的指数值，没有单位定义则为 0。

unitFactorTimeExponent 成员

单位定义中时间单位（秒）的指数值，没有单位定义则为 0。

unitFactorTemperatureExponent 成员

单位定义中温度单位（开尔文或华氏度）的指数值，没有单位定义则为 0。

unitFactorCurrentExponent 成员

单位定义中电流单位（安培）的指数值，没有单位定义则为 0。

unitFactorLuminousIntensityExponent 成员

单位定义中光强单位（坎德拉）的指数值，没有单位定义则为 0。

logicalMinimum 成员

该项在逻辑单位中的最小范围。这是变量项或数组项可能上报的最小值。

logicalMaximum 成员

该项在逻辑单位中的最大范围。这是变量项或数组项可能上报的最大值。

physicalMinimum 成员

该项的物理范围最小值，这表示应用了单位后的 logicalMinimum。

physicalMaximum 成员

该项的物理范围最大值，这表示应用了单位后的 logicalMaximum。

strings 成员

与该项有关的字符串数组。如果无字符串则为一个空的 序列。

[USBIF-HID-CLASS] 第 6.2.2.7 节定义了四种标准单位制：SI 线性、SI 旋转、英制线性和英制旋转。每个条目使用这四种单位制之一、厂商自定义单位制或无单位制。

WebIDLenum HIDUnitSystem {
    "none", "si-linear", "si-rotation", "english-linear",
    "english-rotation", "vendor-defined", "reserved"
};

"none"

无单位制。表示该项没有单位定义。

"si-linear"

SI 线性单位制，采用厘米、克、秒、开尔文、安培、坎德拉。

"si-rotation"

SI 旋转单位制，采用弧度、克、秒、开尔文、安培、坎德拉。

"english-linear"

英制线性单位制，采用英寸、slug、秒、华氏度、安培、坎德拉。

"english-rotation"

英制旋转单位制，采用度、slug、秒、华氏度、安培、坎德拉。

"vendor-defined"

厂商自定义的单位制。

"reserved"

表示设备对于单位制使用了保留值。

本规范依赖于 https://github.com/WICG/webhid 仓库的阻止列表文件来限制网站可访问的HID设备范围。

对于 URL url，解析阻止列表 的结果是获取 url 内容并作为 JSON 解析后得到的一系列字典对象。

HID 阻止列表 即对 解析阻止列表 https://github.com/WICG/webhid/blob/main/blocklist.txt 的结果。

报告满足以下步骤则为 被阻止的报告（blocked report），步骤返回 true：

1. 遍历 HID 阻止列表 中每个 rule：
   1. 如果报告 被阻止规则 rule 阻止则 返回 true。
2. 返回 false。

报告被 阻止规则阻止（blocked by a blocklist rule） rule 满足下列步骤返回 true：

1. 令 reportId 为此报告的报告 ID，如 HID 接口不 使用报告 ID 则为 0。
2. 令 reportType 为 "input"（输入报告）、"output"（输出报告）或 "feature"（功能报告）。
3. 令 collection 为包含该报告的 顶级集合。
4. 若 rule 包含 "vendor" 且 rule["vendor"] 不等于 device.vendorId，则返回 false。
5. 若 rule 包含 "product" 且 rule["product"] 不等于 device.productId，则返回 false。
6. 若 rule 包含 "reportId" 且 rule["reportId"] 不等于 reportId，则返回 false。
7. 若 rule 包含 "reportType" 且 rule["reportType"] 不等于 reportType，则返回 false。
8. 若 rule 包含 "usagePage" 且 rule["usagePage"] 不等于 collection["usagePage"]，则返回 false。
9. 若 rule 包含 "usage" 且 rule.["usage"] 不等于 collection["usage"]，则返回 false。
10. 返回 true。

除了被标记为非规范性（non-normative）的章节，所有文档规范中的作者指导、图例、示例和注释均为非规范性内容。除此以外，规范的其它内容均为规范性内容。

本文档中的关键字 MAY、MUST、MUST NOT、SHOULD 和 SHOULD NOT 应按照 BCP 14 [RFC2119]，[RFC8174] 的定义方式进行解释，仅当这些词汇完全大写时才适用本文定义。