chrome.hid

說明

使用 chrome.hid API 與已連線的 HID 裝置互動。這個 API 可在應用程式環境中存取 HID 作業。應用程式可使用這個 API 做為硬體裝置的驅動程式。如要回報這個 API 產生的錯誤，請設定 runtime.lastError 並執行函式的常規回呼。在這種情況下，回呼的常規參數會是未定義。

權限

hid

類型

DeviceFilter

屬性

  • productId

    號碼 選填

    裝置產品 ID，僅在供應商 ID 相符時檢查。

  • 用量

    號碼 選填

    HID 使用量 ID，只有在 HID 使用量頁面相符時才會檢查。

  • usagePage

    號碼 選填

    HID 使用量頁面 ID。

  • vendorId

    號碼 選填

    裝置供應商 ID。

GetDevicesOptions

屬性

  • 篩選器

    DeviceFilter[] 選用

    系統會傳回符合任何指定篩選條件的裝置。如果篩選條件清單為空白，系統會傳回應用程式有權存取的所有裝置。

  • productId

    號碼 選填

    已淘汰

    相當於設定 DeviceFilter.productId。

  • vendorId

    號碼 選填

    已淘汰

    相當於設定 DeviceFilter.vendorId。

HidCollectionInfo

屬性

  • reportIds

    number[]

    回報屬於集合及其子項的 ID。

  • 用量

    數字

    網頁定義的使用 ID。

  • usagePage

    數字

    HID 使用量頁面 ID。

HidConnectInfo

屬性

  • connectionId

    數字

    不透明 ID，用於在所有其他函式中識別這個連線。

HidDeviceInfo

屬性

  • 來自這個裝置報表描述元的頂層集合。

  • deviceId

    數字

    不透明的裝置 ID。

  • maxFeatureReportSize

    數字

    頂層集合的特徵報告大小上限。

  • maxInputReportSize

    數字

    頂層集合的輸入報告大小上限。

  • maxOutputReportSize

    數字

    頂層集合的輸出報表大小上限。

  • productId

    數字

    產品 ID。

  • productName

    字串

    Chrome 46 以上版本

    從裝置讀取的產品名稱 (如有)。

  • reportDescriptor

    ArrayBuffer

    原始裝置報告描述元 (不適用於 Windows)。

  • serialNumber

    字串

    Chrome 46 以上版本

    從裝置讀取的序號 (如有)。

  • vendorId

    數字

    供應商 ID。

方法

connect()

Promise 
chrome.hid.connect(
  deviceId: number,
  callback?: function,
): Promise<HidConnectInfo>

開啟與 HID 裝置的連線，以便進行通訊。

參數

傳回

  • Promise<HidConnectInfo>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

disconnect()

Promise 
chrome.hid.disconnect(
  connectionId: number,
  callback?: function,
): Promise<void>

中斷與裝置的連線。呼叫此函式後，在裝置上叫用作業是安全的，但不會產生任何效果。

參數

  • connectionId

    數字

    connect 傳回的 connectionId。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getDevices()

Promise 
chrome.hid.getDevices(
  options: GetDevicesOptions,
  callback?: function,
): Promise<HidDeviceInfo[]>

列舉已連線的 HID 裝置。

參數

傳回

  • Promise<HidDeviceInfo[]>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

receive()

chrome.hid.receive(
  connectionId: number,
  callback: function,
): void

接收裝置的下一個輸入報告。

參數

  • connectionId

    數字

    connect 傳回的 connectionId。

  • callback

    函式

    callback 參數如下： 

    (reportId: number, data: ArrayBuffer) => void

    • reportId

      數字

      報表 ID，如果沒有則為 0。

    • 資料

      ArrayBuffer

      系統會移除報表資料和報表 ID 前置字串 (如有)。

receiveFeatureReport()

Promise 
chrome.hid.receiveFeatureReport(
  connectionId: number,
  reportId: number,
  callback?: function,
): Promise<ArrayBuffer>

要求裝置提供功能報告。

參數

  • connectionId

    數字

    connect 傳回的 connectionId。

  • reportId

    數字

    報告 ID，如果沒有則為 0。

  • callback

    函式 選用

    callback 參數如下： 

    (data: ArrayBuffer) => void

    • 資料

      ArrayBuffer

      報告資料，包括裝置傳送的報告 ID 前置字元 (如有)。

傳回

  • Promise<ArrayBuffer>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

send()

Promise 
chrome.hid.send(
  connectionId: number,
  reportId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<void>

將輸出報告傳送至裝置。

注意：請勿在 data 中加入報表 ID 前置字串。系統會視需要新增。

參數

  • connectionId

    數字

    connect 傳回的 connectionId。

  • reportId

    數字

    要使用的報表 ID，或 0 (如果沒有)。

  • 資料

    ArrayBuffer

    報表資料。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

sendFeatureReport()

Promise 
chrome.hid.sendFeatureReport(
  connectionId: number,
  reportId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<void>

將功能報告傳送至裝置。

注意：請勿在 data 中加入報表 ID 前置字串。系統會視需要新增。

參數

  • connectionId

    數字

    connect 傳回的 connectionId。

  • reportId

    數字

    要使用的報表 ID，或 0 (如果沒有)。

  • 資料

    ArrayBuffer

    報表資料。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onDeviceAdded

chrome.hid.onDeviceAdded.addListener(
  callback: function,
)

裝置新增至系統時產生的事件。只有具備裝置存取權的應用程式和擴充功能，才能接收事件廣播。權限可能是在安裝時授予，或是使用者接受選用權限時授予 (請參閱 permissions.request)。

參數

onDeviceRemoved

chrome.hid.onDeviceRemoved.addListener(
  callback: function,
)

裝置從系統中移除時產生的事件。請參閱 onDeviceAdded，瞭解系統會傳送哪些事件。

參數

  • callback

    函式

    callback 參數如下： 

    (deviceId: number) => void

    • deviceId

      數字