chrome.bluetoothLowEnergy

重要事項： 這個 API 僅適用於 ChromeOS。

說明

chrome.bluetoothLowEnergy API 可用於透過通用屬性設定檔 (GATT) 與藍牙智慧 (低功耗) 裝置通訊。

可用性

僅適用於 ChromeOS

資訊清單

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

"bluetooth"

類型

Advertisement

Chrome 47 以上版本

屬性

• manufacturerData

  ManufacturerData[] 選用

  要納入廣告資料「Manufacturer Specific Data」欄位的製造商特定資料清單。

• serviceData

  ServiceData[] 選填

  要納入廣告資料「服務資料」欄位的服務資料清單。

• serviceUuids

  string[] 選填

  要納入廣告資料「服務 UUID」欄位的 UUID 清單。這些 UUID 可以是 16 位元、32 位元或 128 位元格式。

• solicitUuids

  string[] 選填

  要納入廣告資料「Solicit UUIDs」欄位的 UUID 清單。這些 UUID 可以是 16 位元、32 位元或 128 位元格式。

• 類型

  AdvertisementType

  廣告類型。

AdvertisementType

Chrome 47 以上版本

廣告類型。如果選擇「broadcast」，傳送的廣告類型會是 ADV_NONCONN_IND，且裝置會使用隨機 MAC 位址廣播。如果設為「peripheral」，廣告類型會是 ADV_IND 或 ADV_SCAN_IND，且裝置會使用實際藍牙轉接器的 MAC 位址進行廣播。

列舉

"broadcast"

"peripheral"

Characteristic

屬性

• instanceId

  字串 選填

  傳回指派給這項特徵的 ID。您可以使用執行個體 ID 區分具有相同 UUID 的周邊裝置特徵，並呼叫採用特徵 ID 的函式。如果這個例項代表遠端特徵，則會顯示。

• 屬性

  CharacteristicProperty[]

  這項特徵的屬性。

• 服務

  服務 選填

  這個特徵所屬的 GATT 服務。

• uuid

  字串

  特徵的 UUID，例如 00002a37-0000-1000-8000-00805f9b34fb。

• 值

  ArrayBuffer 選用

  目前快取的特徵值。透過通知或指示讀取或更新特徵值時，這個值就會更新。

CharacteristicProperty

代表特徵可能屬性的值。系統會根據這些屬性推論特徵權限。請參閱藍牙 4.x 規格，瞭解各項屬性的意義。

列舉

"broadcast"

"read"

"writeWithoutResponse"

「寫入」

"notify"

「indicate」

"authenticatedSignedWrites"

"extendedProperties"

"reliableWrite"

"writableAuxiliaries"

"encryptRead"

"encryptWrite"

"encryptAuthenticatedRead"

"encryptAuthenticatedWrite"

ConnectProperties

屬性

• 永久

  布林值

  這個標記指出應用程式的事件頁面卸載時，是否要讓裝置連線保持開啟 (請參閱「管理應用程式生命週期」)。預設值為 false.

Descriptor

屬性

• characteristic

  Characteristic 選填

  這個描述元所屬的 GATT 特徵。

• instanceId

  字串 選填

  傳回指派給這個描述元的 ID。使用執行個體 ID 區分具有相同 UUID 的周邊裝置描述元，並呼叫採用描述元 ID 的函式。如果這個例項代表遠端特徵，則會顯示。

• 權限

  DescriptorPermission[]

  Chrome 52 以上版本

  這個描述元的權限。

• uuid

  字串

  特徵描述元的 UUID，例如 00002902-0000-1000-8000-00805f9b34fb。

• 值

  ArrayBuffer 選用

  目前快取的描述元值。讀取描述元的值時，這個值會更新。

DescriptorPermission

Chrome 52 以上版本

代表描述元可能權限的值。請參閱藍牙 4.x 規格，瞭解各項權限的意義。

列舉

"read"

「寫入」

"encryptedRead"

"encryptedWrite"

"encryptedAuthenticatedRead"

"encryptedAuthenticatedWrite"

Device

Chrome 52 以上版本

屬性

• 地址

  字串

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

• deviceClass

  數字 選填

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

• 名稱

  字串 選填

  人類可讀的裝置名稱。

ManufacturerData

Chrome 47 以上版本

屬性

• 資料

  number[]

• id

  數字

Notification

Chrome 52 以上版本

屬性

• shouldIndicate

  布林值 選填

  選用標記，用於傳送指示而非通知。

• 值

  ArrayBuffer

  特徵的新值。

NotificationProperties

屬性

• 永久

  布林值

  這個標記指出應用程式是否應在應用程式的事件頁面卸載時接收通知 (請參閱「管理應用程式生命週期」)。預設值為 false。

Request

Chrome 52 以上版本

屬性

• 裝置

  裝置

  傳送這項要求的裝置。

• requestId

  數字

  這項要求的專屬 ID。回覆這項要求時，請使用這個 ID。

• 值

  ArrayBuffer 選用

  要寫入的值 (如果是寫入要求)。

Response

Chrome 52 以上版本

屬性

• isError

  布林值

  如果這是錯誤回應，則應為 true。

• requestId

  數字

  這項回應對應的要求 ID。

• 值

  ArrayBuffer 選用

  回覆值。寫入要求和錯誤回應會忽略這個參數。

Service

屬性

• deviceAddress

  字串 選填

  GATT 服務所屬遠端周邊裝置的裝置位址。如果這個執行個體代表遠端服務，則會顯示。

• instanceId

  字串 選填

  傳回指派給這項服務的 ID。您可以使用執行個體 ID，區分來自具有相同 UUID 的周邊裝置服務，並發出採用服務 ID 的函式呼叫。如果這個執行個體代表遠端服務，則會顯示。

• isPrimary

  布林值

  指出這項服務的類型是主要或次要。

• uuid

  字串

  服務的 UUID，例如 0000180d-0000-1000-8000-00805f9b34fb。

ServiceData

Chrome 47 以上版本

屬性

• 資料

  number[]

• uuid

  字串

方法

connect()

Promise

chrome.bluetoothLowEnergy.connect(
  deviceAddress: string,
  properties?: ConnectProperties,
  callback?: function,
): Promise<void>

在應用程式和具有指定位址的裝置之間建立連線。裝置可能已連線，且其 GATT 服務可用，而無需呼叫 connect，但想要存取裝置 GATT 服務的應用程式應呼叫此函式，以確保與裝置保持連線。如果裝置未連線，系統會在成功呼叫 connect 後，探索裝置的所有 GATT 服務。

參數

• deviceAddress

  字串

  遠端裝置的藍牙位址，應開啟 GATT 連線。

• 屬性

  ConnectProperties 選填

  連線屬性 (選用)。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

createCharacteristic()

Promise Chrome 52 以上版本

chrome.bluetoothLowEnergy.createCharacteristic(
  characteristic: Characteristic,
  serviceId: string,
  callback?: function,
): Promise<string>

建立本機託管的 GATT 特徵。這項特徵必須由有效的服務託管。如果服務 ID 無效，系統會設定 lastError。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。部分應用程式可能無法使用周邊裝置權限。

參數

• characteristic

  特性

  要建立的特徵。

• serviceId

  字串

  要建立這項特徵的服務 ID。

• callback

  函式 選填

  callback 參數如下：

  (characteristicId: string) => void

  • characteristicId

    字串

傳回

• Promise<string>

  Chrome 91 以上版本

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

createDescriptor()

Promise Chrome 52 以上版本

chrome.bluetoothLowEnergy.createDescriptor(
  descriptor: Descriptor,
  characteristicId: string,
  callback?: function,
): Promise<string>

建立本機託管的 GATT 描述元。這個描述元必須託管在有效的特徵下。如果特徵 ID 無效，系統會設定 lastError。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。部分應用程式可能無法使用周邊裝置權限。

參數

• 描述元

  描述元

  要建立的描述元。

• characteristicId

  字串

  要建立這個描述元的特徵 ID。

• callback

  函式 選填

  callback 參數如下：

  (descriptorId: string) => void

  • descriptorId

    字串

傳回

• Promise<string>

  Chrome 91 以上版本

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

createService()

Promise Chrome 52 以上版本

chrome.bluetoothLowEnergy.createService(
  service: Service,
  callback?: function,
): Promise<string>

建立本機託管的 GATT 服務。這項服務可註冊為在本機 GATT 伺服器上提供。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。部分應用程式可能無法使用周邊裝置權限。

參數

• 服務

  服務

  要建立的服務。

• callback

  函式 選填

  callback 參數如下：

  (serviceId: string) => void

  • serviceId

    字串

傳回

• Promise<string>

  Chrome 91 以上版本

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

disconnect()

Promise

chrome.bluetoothLowEnergy.disconnect(
  deviceAddress: string,
  callback?: function,
): Promise<void>

關閉應用程式與指定位址裝置的連線。請注意，這不一定會破壞實體連結本身，因為可能有其他應用程式開啟連線。

參數

• deviceAddress

  字串

  遠端裝置的藍牙位址。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

getCharacteristic()

Promise

chrome.bluetoothLowEnergy.getCharacteristic(
  characteristicId: string,
  callback?: function,
): Promise<Characteristic>

取得具有指定執行個體 ID 的 GATT 特徵，該特徵屬於指定的 GATT 服務 (如果特徵存在)。

參數

• characteristicId

  字串

  所要求 GATT 特徵的執行個體 ID。

• callback

  函式 選填

  callback 參數如下：

  (result: Characteristic) => void

  • 結果

    特性

傳回

• Promise<Characteristic>

  Chrome 91 以上版本

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

getCharacteristics()

Promise

chrome.bluetoothLowEnergy.getCharacteristics(
  serviceId: string,
  callback?: function,
): Promise<Characteristic[]>

取得屬於指定服務的所有已探索 GATT 特徵清單。

參數

• serviceId

  字串

  應傳回特徵的 GATT 服務執行個體 ID。

• callback

  函式 選填

  callback 參數如下：

  (result: Characteristic[]) => void

  • 結果

    Characteristic[]

傳回

• Promise<Characteristic[]>

  Chrome 91 以上版本

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

getDescriptor()

Promise

chrome.bluetoothLowEnergy.getDescriptor(
  descriptorId: string,
  callback?: function,
): Promise<Descriptor>

取得具有指定執行個體 ID 的 GATT 特徵描述元。

參數

• descriptorId

  字串

  所要求 GATT 特徵描述元的執行個體 ID。

• callback

  函式 選填

  callback 參數如下：

  (result: Descriptor) => void

  • 結果

    描述元

傳回

• Promise<Descriptor>

  Chrome 91 以上版本

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

getDescriptors()

Promise

chrome.bluetoothLowEnergy.getDescriptors(
  characteristicId: string,
  callback?: function,
): Promise<Descriptor[]>

取得屬於指定特性的 GATT 特性描述元清單。

參數

• characteristicId

  字串

  GATT 特徵的執行個體 ID，其描述元應傳回。

• callback

  函式 選填

  callback 參數如下：

  (result: Descriptor[]) => void

  • 結果

    描述元[]

傳回

• Promise<Descriptor[]>

  Chrome 91 以上版本

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

getIncludedServices()

Promise

chrome.bluetoothLowEnergy.getIncludedServices(
  serviceId: string,
  callback?: function,
): Promise<Service[]>

取得指定服務包含的 GATT 服務清單。

參數

• serviceId

  字串

  GATT 服務的執行個體 ID，系統應傳回該服務包含的服務。

• callback

  函式 選填

  callback 參數如下：

  (result: Service[]) => void

  • 結果

    Service[]

傳回

• Promise<Service[]>

  Chrome 91 以上版本

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

getService()

Promise

chrome.bluetoothLowEnergy.getService(
  serviceId: string,
  callback?: function,
): Promise<Service>

取得具有指定執行個體 ID 的 GATT 服務。

參數

• serviceId

  字串

  所要求 GATT 服務的執行個體 ID。

• callback

  函式 選填

  callback 參數如下：

  (result: Service) => void

  • 結果

    服務

傳回

• Promise<Service>

  Chrome 91 以上版本

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

getServices()

Promise

chrome.bluetoothLowEnergy.getServices(
  deviceAddress: string,
  callback?: function,
): Promise<Service[]>

取得在具有指定裝置位址的遠端裝置上發現的所有 GATT 服務。

注意：如果裝置尚未完成服務探索，這個 API 會傳回服務子集 (可能為空白)。解決方法是加入時間延遲和/或重複呼叫，直到傳回預期的服務數量。

參數

• deviceAddress

  字串

  遠端裝置的藍牙位址，系統應傳回該裝置的 GATT 服務。

• callback

  函式 選填

  callback 參數如下：

  (result: Service[]) => void

  • 結果

    Service[]

傳回

• Promise<Service[]>

  Chrome 91 以上版本

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

notifyCharacteristicValueChanged()

Promise Chrome 52 以上版本

chrome.bluetoothLowEnergy.notifyCharacteristicValueChanged(
  characteristicId: string,
  notification: Notification,
  callback?: function,
): Promise<void>

通知遠端裝置特徵的新值。如果通知物件中的 shouldIndicate 旗標為 true，系統會傳送指示，而非通知。請注意，建立特徵時必須正確設定「notify」或「indicate」屬性，這項呼叫才能成功。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。部分應用程式可能無法使用周邊裝置權限。

參數

• characteristicId

  字串

  要傳送通知的特徵。

• 通知

  通知

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

readCharacteristicValue()

Promise

chrome.bluetoothLowEnergy.readCharacteristicValue(
  characteristicId: string,
  callback?: function,
): Promise<Characteristic>

從遠端周邊裝置擷取指定特徵的值。

參數

• characteristicId

  字串

  GATT 特徵的執行個體 ID，其值應從遠端裝置讀取。

• callback

  函式 選填

  callback 參數如下：

  (result: Characteristic) => void

  • 結果

    特性

傳回

• Promise<Characteristic>

  Chrome 91 以上版本

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

readDescriptorValue()

Promise

chrome.bluetoothLowEnergy.readDescriptorValue(
  descriptorId: string,
  callback?: function,
): Promise<Descriptor>

從遠端周邊裝置擷取指定特徵描述元的值。

參數

• descriptorId

  字串

  GATT 特徵描述元的執行個體 ID，其值應從遠端裝置讀取。

• callback

  函式 選填

  callback 參數如下：

  (result: Descriptor) => void

  • 結果

    描述元

傳回

• Promise<Descriptor>

  Chrome 91 以上版本

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

registerAdvertisement()

Promise Chrome 47 以上版本

chrome.bluetoothLowEnergy.registerAdvertisement(
  advertisement: Advertisement,
  callback?: function,
): Promise<number>

建立廣告並註冊廣告。如要呼叫這個函式，應用程式必須將 bluetooth:low_energy 和 bluetooth:peripheral 權限設為 true。此外，這個 API 僅適用於在 Kiosk 模式下自動啟動的應用程式，或設定「--enable-ble-advertising-in-apps」指令列切換。請參閱 https://developer.chrome.com/apps/manifest/bluetooth。注意：部分硬體可同時支援中央和周邊模式，但如果硬體不支援，發出這項呼叫會將裝置切換至周邊模式。如果硬體不支援中央和周邊模式，嘗試在兩種模式下使用裝置會導致未定義的行為，或導致其他中央角色應用程式無法正常運作 (包括探索藍牙低功耗裝置)。

參數

• 廣告

  廣告

  要宣傳的廣告。

• callback

  函式 選填

  callback 參數如下：

  (advertisementId: number) => void

  • advertisementId

    數字

傳回

• Promise<number>

  Chrome 91 以上版本

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

registerService()

Promise Chrome 52 以上版本

chrome.bluetoothLowEnergy.registerService(
  serviceId: string,
  callback?: function,
): Promise<void>

向本機 GATT 伺服器註冊指定服務。如果服務 ID 無效，系統會設定 lastError。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。周邊裝置權限可能不適用於所有應用程式。

參數

• serviceId

  字串

  已建立服務的專屬 ID。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

removeService()

Promise Chrome 52 以上版本

chrome.bluetoothLowEnergy.removeService(
  serviceId: string,
  callback?: function,
): Promise<void>

移除指定服務，如果服務已註冊，則取消註冊。如果服務 ID 無效，系統會設定 lastError。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。部分應用程式可能無法使用周邊裝置權限。

參數

• serviceId

  字串

  目前已註冊服務的專屬 ID。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

resetAdvertising()

Promise Chrome 61 以上版本

chrome.bluetoothLowEnergy.resetAdvertising(
  callback?: function,
): Promise<void>

重設目前裝置的廣告。這項操作會取消註冊並停止所有現有的廣告。

參數

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

sendRequestResponse()

Chrome 52 以上版本

chrome.bluetoothLowEnergy.sendRequestResponse(
  response: Response,
): void

傳送特徵或描述元讀取/寫入要求的回應。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。周邊裝置權限可能不適用於所有應用程式。

參數

• 回應

  回應

  對要求的應答。

setAdvertisingInterval()

Promise Chrome 55 以上版本

chrome.bluetoothLowEnergy.setAdvertisingInterval(
  minInterval: number,
  maxInterval: number,
  callback?: function,
): Promise<void>

設定兩次連續廣告之間的間隔。注意：我們會盡力確保您的版本在時限內發布。實際間隔可能與要求的間隔有明顯差異。在某些硬體上，最短間隔為 100 毫秒。最小值和最大值不得超過藍牙 4.2 規格允許的範圍。

參數

• minInterval

  數字

  廣告之間的最小間隔 (以毫秒為單位)。根據規格，這個值不得低於 20 毫秒。

• maxInterval

  數字

  廣告之間的最長間隔 (以毫秒為單位)。根據規格，這個值不得超過 10240 毫秒。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

startCharacteristicNotifications()

Promise

chrome.bluetoothLowEnergy.startCharacteristicNotifications(
  characteristicId: string,
  properties?: NotificationProperties,
  callback?: function,
): Promise<void>

啟用指定特徵的值通知/指示。啟用後，應用程式就能使用 onCharacteristicValueChanged 事件監聽通知。

參數

• characteristicId

  字串

  應啟用通知的 GATT 特徵執行個體 ID。

• 屬性

  NotificationProperties 選用

  通知工作階段屬性 (選用)。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

stopCharacteristicNotifications()

Promise

chrome.bluetoothLowEnergy.stopCharacteristicNotifications(
  characteristicId: string,
  callback?: function,
): Promise<void>

停用指定特徵的值通知/指示。呼叫成功後，應用程式會停止接收這個特性的通知/指示。

參數

• characteristicId

  字串

  GATT 特徵的執行個體 ID，這個應用程式的通知工作階段應在該特徵上停止。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

unregisterAdvertisement()

Promise Chrome 47 以上版本

chrome.bluetoothLowEnergy.unregisterAdvertisement(
  advertisementId: number,
  callback?: function,
): Promise<void>

取消註冊廣告並停止廣告。如果廣告無法取消註冊，可能需要重新啟動裝置，才能停止廣告。

參數

• advertisementId

  數字

  要取消註冊的廣告 ID。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

unregisterService()

Promise Chrome 52 以上版本

chrome.bluetoothLowEnergy.unregisterService(
  serviceId: string,
  callback?: function,
): Promise<void>

向本機 GATT 伺服器取消註冊指定服務。如果服務 ID 無效，系統會設定 lastError。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限都設為 true 時，才能使用這項功能。部分應用程式可能無法使用周邊裝置權限。

參數

• serviceId

  字串

  目前已註冊服務的專屬 ID。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

writeCharacteristicValue()

Promise

chrome.bluetoothLowEnergy.writeCharacteristicValue(
  characteristicId: string,
  value: ArrayBuffer,
  callback?: function,
): Promise<void>

寫入遠端周邊裝置指定特徵的值。

參數

• characteristicId

  字串

  GATT 特徵的執行個體 ID，其值應寫入。

• 值

  ArrayBuffer

  應傳送至遠端特徵的值，做為寫入要求的一部分。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

writeDescriptorValue()

Promise

chrome.bluetoothLowEnergy.writeDescriptorValue(
  descriptorId: string,
  value: ArrayBuffer,
  callback?: function,
): Promise<void>

寫入遠端周邊裝置的指定特徵描述元值。

參數

• descriptorId

  字串

  GATT 特徵描述元的執行個體 ID，其值應寫入。

• 值

  ArrayBuffer

  應做為寫入要求的一部分，傳送至遠端描述元的值。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

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

事件

onCharacteristicReadRequest

Chrome 52 以上版本

chrome.bluetoothLowEnergy.onCharacteristicReadRequest.addListener(
  callback: function,
)

當已連線的中央裝置要求讀取本機 GATT 伺服器上註冊的特徵值時，就會觸發這個事件。如果長時間未回應這項要求，可能會中斷連線。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限皆設為 true 時，才能使用這個事件。部分應用程式可能無法使用周邊裝置權限。

參數

• callback

  函式

  callback 參數如下：

  (request: Request, characteristicId: string) => void

  • 申請。

    要求

  • characteristicId

    字串

onCharacteristicValueChanged

chrome.bluetoothLowEnergy.onCharacteristicValueChanged.addListener(
  callback: function,
)

當遠端 GATT 特徵值因讀取要求或值變更通知/指示而變更時，系統會觸發這個事件。只有在應用程式透過呼叫 startCharacteristicNotifications 啟用通知時，系統才會傳送這個事件。

參數

• callback

  函式

  callback 參數如下：

  (characteristic: Characteristic) => void

  • characteristic

    特性

onCharacteristicWriteRequest

Chrome 52 以上版本

chrome.bluetoothLowEnergy.onCharacteristicWriteRequest.addListener(
  callback: function,
)

當已連線的中央裝置要求寫入本機 GATT 伺服器上註冊的特徵值時，就會觸發這個事件。如果長時間未回應這項要求，可能會中斷連線。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限皆設為 true 時，才能使用這個事件。部分應用程式可能無法使用周邊裝置權限。

參數

• callback

  函式

  callback 參數如下：

  (request: Request, characteristicId: string) => void

  • 申請。

    要求

  • characteristicId

    字串

onDescriptorReadRequest

Chrome 52 以上版本

chrome.bluetoothLowEnergy.onDescriptorReadRequest.addListener(
  callback: function,
)

當已連線的中央裝置要求讀取本機 GATT 伺服器上註冊的描述元值時，就會觸發這個事件。如果長時間未回應這項要求，可能會中斷連線。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限皆設為 true 時，才能使用這個事件。部分應用程式可能無法使用周邊裝置權限。

參數

• callback

  函式

  callback 參數如下：

  (request: Request, descriptorId: string) => void

  • 申請。

    要求

  • descriptorId

    字串

onDescriptorValueChanged

chrome.bluetoothLowEnergy.onDescriptorValueChanged.addListener(
  callback: function,
)

當遠端 GATT 特徵描述元的值變更時 (通常是讀取要求的結果)，就會觸發這個事件。這個事件主要是為了方便而存在，且一律會在成功呼叫 readDescriptorValue 後傳送。

參數

• callback

  函式

  callback 參數如下：

  (descriptor: Descriptor) => void

  • 描述元

    描述元

onDescriptorWriteRequest

Chrome 52 以上版本

chrome.bluetoothLowEnergy.onDescriptorWriteRequest.addListener(
  callback: function,
)

當已連線的中央裝置要求寫入本機 GATT 伺服器上註冊的描述元值時，就會觸發這個事件。如果長時間未回應這項要求，可能會中斷連線。只有在應用程式的 bluetooth:low_energy 和 bluetooth:peripheral 權限皆設為 true 時，才能使用這個事件。部分應用程式可能無法使用周邊裝置權限。

參數

• callback

  函式

  callback 參數如下：

  (request: Request, descriptorId: string) => void

  • 申請。

    要求

  • descriptorId

    字串

onServiceAdded

chrome.bluetoothLowEnergy.onServiceAdded.addListener(
  callback: function,
)

在遠端裝置上發現新的 GATT 服務時觸發。

參數

• callback

  函式

  callback 參數如下：

  (service: Service) => void

  • 服務

    服務

onServiceChanged

chrome.bluetoothLowEnergy.onServiceChanged.addListener(
  callback: function,
)

在遠端 GATT 服務狀態變更時觸發。這包括從服務中新增或移除的任何特徵和/或描述元，以及遠端裝置的「ServiceChanged」通知。

參數

• callback

  函式

  callback 參數如下：

  (service: Service) => void

  • 服務

    服務

onServiceRemoved

chrome.bluetoothLowEnergy.onServiceRemoved.addListener(
  callback: function,
)

在遠端裝置上先前探索到的 GATT 服務遭到移除時觸發。

參數

• callback

  函式

  callback 參數如下：

  (service: Service) => void

  • 服務

    服務