chrome.bluetooth

說明

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

資訊清單

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

"bluetooth"

類型

AdapterState

屬性

  • 地址

    字串

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

  • 供應

    布林值

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

  • 探索

    布林值

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

  • 名稱

    字串

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

  • 技術提供

    布林值

    指出變壓器是否有電。

BluetoothFilter

Chrome 67 以上版本

屬性

  • filterType

    FilterType 選填

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

  • 限制

    號碼 選填

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

Device

屬性

  • 地址

    字串

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

  • batteryPercentage

    號碼 選填

    Chrome 77 以上版本

    裝置的剩餘電量。

  • connectable

    boolean 選填

    Chrome 48 以上版本

    指出裝置是否可連線。

  • 已連線。

    boolean 選填

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

  • 轉機航班

    boolean 選填

    Chrome 48 以上版本

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

  • deviceClass

    號碼 選填

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

  • deviceId

    號碼 選填

  • inquiryRssi

    號碼 選填

    Chrome 44 以上版本

    接收訊號強度，單位為 dBm。這個欄位僅在偵測期間可用且有效。在探索之外，系統不會指定其值。

  • inquiryTxPower

    號碼 選填

    Chrome 44 以上版本

    傳輸功率。這個欄位僅適用於在廣告中加入此欄位的 LE 裝置。這項功能僅在探索階段提供，且僅在探索階段有效。

  • 名稱

    string 選填

    使用者可讀的裝置名稱。

  • 已配對

    boolean 選填

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

  • productId

    號碼 選填

  • transport

    運輸 選填

    Chrome 76 以上版本

    Bluetooth 裝置的傳輸類型。

  • 類型

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

Bluetooth 裝置的傳輸類型。

列舉

"invalid"

"classic"

"le"

"dual"

VendorIdSource

供應商 ID 的分配權限。

列舉

"bluetooth"

"usb"

方法

getAdapterState()

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (adapterInfo: AdapterState) => void

    • adapterInfo

      AdapterState

      包含轉接器資訊的物件。

傳回

  • Promise<AdapterState>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getDevice()

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

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

參數

  • deviceAddress

    字串

    要取得的裝置位址。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (deviceInfo: Device) => void

    • deviceInfo

      裝置

      包含裝置資訊的物件。

傳回

  • Promise<Device>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getDevices()

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

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

參數

  • 篩選器

    BluetoothFilter 選填

    Chrome 67 以上版本

    用於篩選傳回的藍牙裝置清單的某些條件。如果未設定篩選器或將其設為 {}，則傳回的裝置清單會包含所有藍牙裝置。目前僅 ChromeOS 支援這項功能，其他平台則會傳回完整清單。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (deviceInfos: Device[]) => void

    • deviceInfos

      裝置[]

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

傳回

  • Promise<Device[]>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

startDiscovery()

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

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

stopDiscovery()

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

停止探索。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾僅支援資訊清單 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