chrome.bluetooth

說明

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

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 API。

"bluetooth"

類型

AdapterState

屬性

  • 地址

    字串

    轉接器的地址，格式為「XX:XX:XX:XX:XX:XX」。

  • 供應

    布林值

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

  • 探索

    布林值

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

  • 名稱

    字串

    使用者可理解的轉接器名稱。

  • 供電

    布林值

    指出轉接頭是否有電源。

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 裝置。這項資訊在探索期間可行且有效。

  • 名稱

    string optional

    使用者可理解的裝置名稱。

  • 已配對

    布林值 選填

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

  • productId

    編號 選填

  • transport

    運輸 選用

    Chrome 76 以上版本

    藍牙裝置的傳輸類型。

  • 類型

    DeviceType (選用)

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

  • uuids

    string[] 選填

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

  • vendorId

    編號 選填

  • vendorIdSource

    VendorIdSource 選用

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

DeviceType

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

列舉

"電腦"

"手機"

"modem"

"音訊"

"carAudio"

"影片"

"週邊裝置"

"搖桿"

"遊戲手把"

"鍵盤"

"mouse"

"平板電腦"

"keyboardMouseCombo"

FilterType

Chrome 67 以上版本

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

列舉

"all"

"已知"

Transport

Chrome 76 以上版本

藍牙裝置的傳輸類型。

列舉

「無效」

"傳統"

"le"

"dual"

VendorIdSource

供應商 ID 的分配機構。

列舉

「bluetooth」

「usb」

方法

getAdapterState()

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

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (adapterInfo: AdapterState) => void

    • adapterInfo

      AdapterState

      包含轉接器資訊的物件。

傳回

  • Promise<AdapterState>

    Chrome 91 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getDevice()

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

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

參數

  • deviceAddress

    字串

    要取得的裝置地址。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (deviceInfo: Device) => void

    • deviceInfo

      裝置

      包含裝置資訊的物件。

傳回

  • Promise<Device>

    Chrome 91 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getDevices()

Promise 
chrome.bluetooth.getDevices(
  filter?: BluetoothFilter,
  callback?: function,
)

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

參數

  • 篩選器

    BluetoothFilter 選用

    Chrome 67 以上版本

    一些用於篩選傳回的藍牙裝置清單的條件。如未設定篩選器或設為「{}」，傳回的裝置清單會包含所有藍牙裝置。目前只有 ChromeOS 支援這項功能，系統會針對其他平台傳回完整清單。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (deviceInfos: Device[]) => void

    • deviceInfos

      裝置[]

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

傳回

  • Promise<裝置[]>

    Chrome 91 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

startDiscovery()

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

開始探索。系統會透過 onDeviceAdded 事件退回新發現的裝置。先前發現的裝置已知是透過 getDevices 取得，且必須在相關資訊發生變化時，才使用 onDeviceChanged 事件更新裝置。

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

stopDiscovery()

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

停止探索。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

活動

onAdapterStateChanged

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

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

參數

onDeviceAdded

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (device: Device) => void

onDeviceChanged

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (device: Device) => void

onDeviceRemoved

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

當先前發現的藍牙裝置時間超出限制範圍，因而無法再次使用，並移除了配對的裝置時，就會啟動。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (device: Device) => void