chrome.bluetooth

說明

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

資訊清單

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

"bluetooth"

類型

AdapterState

屬性

  • 地址

    字串

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

  • 供應

    boolean

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

  • 探索

    boolean

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

  • 名稱

    字串

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

  • 供電

    boolean

    指出轉接頭是否已有電源。

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 欄位。

  • UID

    string[] 選填

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

  • vendorId

    數字 選填

  • vendorIdSource

    VendorIdSource 選用

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

DeviceType

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

列舉

"modem"

"carAudio"

"gamepad"

"mouse"

"keyboardMouseCombo"

FilterType

Chrome 67 以上版本

篩選藍牙裝置的類型。

列舉

Transport

Chrome 76 以上版本

藍牙裝置的傳輸類型。

列舉

VendorIdSource

供應商 ID 的分配主機名稱。

列舉

方法

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<裝置>

    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，系統將無法啟動探索功能。Discovery 可能會耗用大量資源：應盡快呼叫 stopDiscovery。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

stopDiscovery()

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

停止探索。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<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