chrome.bluetooth

說明

使用 chrome.bluetooth API 連線至藍牙裝置。所有函式都會透過 chrome.runtime.lastError 回報失敗。

資訊清單

如要使用這項 API，必須在資訊清單中宣告下列鍵。

"bluetooth"

類型

AdapterState

屬性

  • 地址

    字串

    介面的位址，格式為「XX:XX:XX:XX:XX:XX」。

  • 供應

    布林值

    指出轉接器是否可用 (即是否已啟用)。

  • 探索

    布林值

    指出轉接程式目前是否正在探索。

  • 名稱

    字串

    使用者可判讀的轉接器名稱。

  • powered

    布林值

    指出變壓器是否供電。

BluetoothFilter

Chrome 67 以上版本

屬性

  • filterType

    FilterType 選填

    要套用至裝置清單的篩選器類型。預設值為「全部」。

  • 限制

    號碼 選填

    要傳回的藍牙裝置數量上限。如未指定，預設值為 0 (無限制)。

Device

屬性

  • 地址

    字串

    裝置的位址，格式為「XX:XX:XX:XX:XX:XX」。

  • batteryPercentage

    號碼 選填

    Chrome 77 以上版本

    裝置的剩餘電量。

  • 可連線

    布林值 選填

    Chrome 48 以上版本

    指出裝置是否可連線。

  • 已連線。

    布林值 選填

    指出裝置目前是否已連上系統。

  • 轉機航班

    布林值 選填

    Chrome 48 以上版本

    指出裝置目前是否正在連線至系統。

  • deviceClass

    號碼 選填

    裝置類別，是由 http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband 定義的位元欄位。

  • deviceId

    號碼 選填

  • inquiryRssi

    號碼 選填

    Chrome 44 以上版本

    接收訊號強度，單位為 dBm。這個欄位僅在探索期間有效。探索以外的值未指定。

  • inquiryTxPower

    號碼 選填

    Chrome 44 以上版本

    傳輸功率等級。這個欄位僅適用於 AD 中包含這個欄位的 LE 裝置。這項資訊僅在探索期間有效。

  • 名稱

    字串 選填

    裝置的人類可讀名稱。

  • 已配對

    布林值 選填

    指出裝置是否已與系統配對。

  • productId

    號碼 選填

  • transport

    交通運輸 選填

    Chrome 76 以上版本

    藍牙裝置的傳輸類型。

  • 類型

    DeviceType 選填

    Chrome 辨識出的裝置類型。這項資訊是從 deviceClass 欄位取得，僅代表可能裝置類型的一小部分。如有疑慮，請直接使用 deviceClass 欄位。

  • uuids

    字串陣列 選用

    裝置宣傳的通訊協定、設定檔和服務 UUID。如果是傳統藍牙裝置，這份清單是從 EIR 資料和 SDP 表格取得。如果是低功耗裝置，這份清單會從 AD 和 GATT 主要服務取得。如果是雙模式裝置，則可從兩者取得。

  • vendorId

    號碼 選填

  • vendorIdSource

    VendorIdSource 選用

    裝置的裝置 ID 記錄 (如有)。

DeviceType

Chrome 可辨識的常見裝置類型。

列舉

「computer」

「phone」

「modem」

「audio」

「carAudio」

「video」

「peripheral」

「joystick」

「gamepad」

「keyboard」

「mouse」

「tablet」

「keyboardMouseCombo」

FilterType

Chrome 67 以上版本

用於篩選藍牙裝置的類型。

列舉

「all」

「已知」

Transport

Chrome 76 以上版本

藍牙裝置的傳輸類型。

列舉

「invalid」

「classic」

「le」

「dual」

VendorIdSource

供應商 ID 的分配授權單位。

列舉

「bluetooth」

"usb"

方法

getAdapterState()

Promise 
chrome.bluetooth.getAdapterState(
  callback?: function,
): Promise<AdapterState>

取得藍牙轉接器的相關資訊。

參數

  • callback

    函式 選用

    callback 參數如下： 

    (adapterInfo: AdapterState) => void

    • adapterInfo

      AdapterState

      包含轉接器資訊的物件。

傳回

  • Promise<AdapterState>

    Chrome 91 以上版本

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

getDevice()

Promise 
chrome.bluetooth.getDevice(
  deviceAddress: string,
  callback?: function,
): Promise<Device>

取得系統已知的藍牙裝置相關資訊。

參數

  • deviceAddress

    字串

    要取得的裝置地址。

  • callback

    函式 選用

    callback 參數如下： 

    (deviceInfo: Device) => void

    • deviceInfo

      裝置

      包含裝置資訊的物件。

傳回

  • Promise<Device>

    Chrome 91 以上版本

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

getDevices()

Promise 
chrome.bluetooth.getDevices(
  filter?: BluetoothFilter,
  callback?: function,
): Promise<Device[]>

取得系統已知的藍牙裝置清單，包括已配對和最近探索到的裝置。

參數

  • 篩選

    BluetoothFilter 選用

    Chrome 67 以上版本

    篩選傳回的藍牙裝置清單時，可使用的部分條件。如果未設定篩選器或設為 {}，傳回的裝置清單會包含所有藍牙裝置。目前僅支援 ChromeOS，其他平台則會傳回完整清單。

  • callback

    函式 選用

    callback 參數如下： 

    (deviceInfos: Device[]) => void

    • deviceInfos

      裝置[]

      包含裝置資訊的物件陣列。

傳回

  • Promise<Device[]>

    Chrome 91 以上版本

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

startDiscovery()

Promise 
chrome.bluetooth.startDiscovery(
  callback?: function,
): Promise<void>

開始探索。系統會透過 onDeviceAdded 事件傳回新發現的裝置。必須使用 getDevices 取得介面卡已知的先前探索到的裝置，且只有在裝置資訊變更時，才會使用 onDeviceChanged 事件更新裝置。

如果這個應用程式已呼叫 startDiscovery，探索作業將無法啟動。探索功能可能會耗用大量資源，因此請盡快呼叫 stopDiscovery。

參數

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

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

stopDiscovery()

Promise 
chrome.bluetooth.stopDiscovery(
  callback?: function,
): Promise<void>

停止探索。

參數

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

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

事件

onAdapterStateChanged

chrome.bluetooth.onAdapterStateChanged.addListener(
  callback: function,
)

藍牙配接器狀態變更時觸發。

參數

onDeviceAdded

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

有新的藍牙裝置資訊時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (device: Device) => void

onDeviceChanged

chrome.bluetooth.onDeviceChanged.addListener(
  callback: function,
)

已知藍牙裝置的資訊變更時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (device: Device) => void

onDeviceRemoved

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

當先前探索到的藍牙裝置超出範圍，時間長到足以視為再次無法使用，以及移除已配對的裝置時，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    (device: Device) => void