chrome.bluetooth

說明

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

可用性

僅適用於 ChromeOS

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 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 裝置。這項功能僅在探索階段可用且有效。

  • 名稱

    字串 選填

    人類可讀的裝置名稱。

  • paired

    布林值 選填

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

  • productId

    數字 選填

  • transport

    Transport 選填

    Chrome 76 以上版本

    藍牙裝置的傳輸類型。

  • 類型

    DeviceType 選填

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

  • uuids

    string[] 選填

    裝置廣播的通訊協定、設定檔和服務 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"

"known"

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 以上版本

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

getDevice()

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

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

參數

  • deviceAddress

    字串

    要取得的裝置位址。

  • callback

    函式 選填

    callback 參數如下： 

    (deviceInfo: Device) => void

    • deviceInfo

      裝置

      包含裝置資訊的物件。

傳回

  • Promise<Device>

    Chrome 91 以上版本

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

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 以上版本

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

startDiscovery()

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

開始探索。新偵測到的裝置會透過 onDeviceAdded 事件傳回。先前探索到的裝置 (轉接器已知) 必須使用 getDevices 取得，且只有在裝置資訊變更時，才會使用 onDeviceChanged 事件更新。

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

參數

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

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

stopDiscovery()

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

停止探索。

參數

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

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

事件

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