BluetoothDevice.name — Eigenschaft · JavaScript-Referenz

Signatur

BluetoothDevice.name

Beschreibung

Die Eigenschaft name eines BluetoothDevice-Objekts enthält den Namen, den das Gerät selbst meldet, zum Beispiel „Polar H10 1A2B3C“ oder „LE-Bose Micro“. Der Wert stammt aus den Advertising-Daten oder aus der GAP-Charakteristik Device Name und wird vom Browser zwischengespeichert.

Man nutzt name vor allem, um das gekoppelte Gerät in der Oberfläche anzuzeigen, etwa in Statusmeldungen wie „Verbunden mit …“, oder um Protokolle lesbarer zu machen. Zur eindeutigen Identifikation eignet sich der Name dagegen nicht: Mehrere Geräte können denselben Namen haben. Dafür gibt es BluetoothDevice.id.

Hat das Gerät keinen Namen gemeldet, ist der Wert undefined. Die Eigenschaft ist schreibgeschützt. Wer einen eigenen Anzeigenamen braucht, speichert ihn selbst, zum Beispiel in localStorage und verknüpft mit der id. Ein BluetoothDevice-Objekt bekommt man über navigator.bluetooth.requestDevice() oder navigator.bluetooth.getDevices().

Rückgabewert

Typ

string | undefined

Beschreibung

Der vom Gerät gemeldete, lesbare Name. undefined, wenn kein Name verfügbar ist.

Beispiele

Gerät auswählen und Namen anzeigen

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. einen Klick)
const button = document.querySelector('#connect');

button.addEventListener('click', async () => {
  try {
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['heart_rate'] }]
    });
    console.log(`Ausgewählt: ${device.name ?? 'Unbekanntes Gerät'}`);
  } catch (err) {
    console.error('Auswahl abgebrochen oder fehlgeschlagen:', err.message);
  }
});

Ausgewählt: Polar H10 1A2B3C

Nach Namenspräfix filtern und verbinden

const connectToSensor = async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ namePrefix: 'Thingy' }],
    optionalServices: ['battery_service']
  });

  const server = await device.gatt.connect();
  document.querySelector('#status').textContent =
    `Verbunden mit ${device.name ?? device.id}`;
  return server;
};

document.querySelector('#scan').addEventListener('click', connectToSensor);

Bereits erlaubte Geräte mit Namen auflisten

const listKnownDevices = async () => {
  if (!('getDevices' in navigator.bluetooth)) {
    console.warn('getDevices() wird nicht unterstützt');
    return;
  }
  const devices = await navigator.bluetooth.getDevices();
  devices.forEach(({ id, name }) => {
    console.log(`${name ?? '(ohne Namen)'} – ID: ${id}`);
  });
};

listKnownDevices();

Polar H10 1A2B3C – ID: kQ3xZ... (ohne Namen) – ID: 9fT2a...

// Wichtig · Fallstricke

Kann undefined sein: Viele Geräte melden keinen Namen. Nutze deshalb immer einen Ersatzwert, z. B. device.name ?? 'Unbekannt'.
Nicht eindeutig: Namen können sich wiederholen und vom Gerät geändert werden. Für die Wiedererkennung ist BluetoothDevice.id gedacht.
Nicht vertrauenswürdig: Den Namen legt das Gerät selbst fest. Er sollte nicht über innerHTML eingefügt werden, sondern über textContent, weil sonst XSS möglich ist.
Kompatibilität: Die Web Bluetooth API ist experimentell. Sie gibt es nur in Chromium-basierten Browsern und nur in sicheren Kontexten (HTTPS). Firefox und Safari unterstützen sie nicht, unter Linux ist sie teilweise nur per Flag aktivierbar. Vor der Nutzung sollte man prüfen: 'bluetooth' in navigator.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert und wirft im Strict Mode einen TypeError.

Siehe auch

BluetoothDevice BluetoothDevice.id BluetoothDevice.gatt Bluetooth.requestDevice() Bluetooth.getDevices() Bluetooth FileSystemHandle.name