Magnetometer — Schnittstelle · JavaScript-Referenz

Signatur

interface Magnetometer extends Sensor

Beschreibung

Magnetometer gehört zur Generic Sensor API und erbt von Sensor (und damit von EventTarget). Die Schnittstelle liest den primären Magnetfeldsensor des Geräts aus und stellt die Messwerte über die schreibgeschützten Eigenschaften x, y und z bereit. Alle drei Werte sind in Mikrotesla (µT) angegeben. Solange noch keine Messung vorliegt, sind sie null.

Typische Einsatzgebiete sind Kompass-Anwendungen, das Erkennen von Metall oder Magneten in der Nähe, Spielsteuerung und Sensorfusion. Für eine fertig berechnete Ausrichtung im Raum eignet sich AbsoluteOrientationSensor meist besser. Er kombiniert Magnetometer, Beschleunigungsmesser und Gyroskop und ist deutlich weiter verbreitet.

Die Nutzung folgt dem üblichen Sensor-Muster:

Instanz mit new Magnetometer({ frequency, referenceFrame }) erzeugen.
Auf das Ereignis reading hören (über addEventListener("reading", …) oder onreading).
Mit start() starten und mit stop() beenden.

Fehler wie fehlende Berechtigung oder fehlende Hardware werden über das Ereignis error gemeldet. Es liefert ein SensorErrorEvent.

Die Schnittstelle funktioniert nur in einem sicheren Kontext (HTTPS). Außerdem muss die Permissions Policy magnetometer den Zugriff erlauben. Magnetfelddaten lassen sich zum Fingerprinting und für Seitenkanal-Angriffe missbrauchen. Deshalb ist die API bisher kaum ausgeliefert.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt für den Konstruktor `new Magnetometer(options)`.
$options.frequency	number	abhängig vom Gerät	Gewünschte Anzahl Messungen pro Sekunde (Hz). Der Browser kann den Wert an die Möglichkeiten der Hardware anpassen.
$options.referenceFrame	"device" \| "screen"	"device"	Koordinatensystem der Messwerte: `"device"` bezieht sich auf das physische Gerät, `"screen"` auf die aktuelle Bildschirmausrichtung.

Rückgabewert

Typ

Magnetometer

Beschreibung

Eine neue, noch nicht gestartete Sensor-Instanz. Sie bietet die Eigenschaften x, y, z (number | null, in µT), die geerbten Eigenschaften activated, hasReading und timestamp, die Methoden start() und stop() sowie die Ereignisse reading, activate und error.

Beispiele

Instanz erzeugen und Messwerte ausgeben

if ('Magnetometer' in window) {
  const mag = new Magnetometer({ frequency: 10 });

  mag.addEventListener('reading', () => {
    console.log(`x: ${mag.x.toFixed(1)} µT, y: ${mag.y.toFixed(1)} µT, z: ${mag.z.toFixed(1)} µT`);
  });

  mag.addEventListener('error', (event) => {
    console.error(event.error.name, event.error.message);
  });

  mag.start();
} else {
  console.warn('Magnetometer wird nicht unterstützt.');
}

x: 12.3 µT, y: -31.8 µT, z: -40.2 µT (Beispielwerte, 10-mal pro Sekunde)

Einfacher Kompass: Himmelsrichtung berechnen

const mag = new Magnetometer({ frequency: 5, referenceFrame: 'screen' });

mag.onreading = () => {
  // Gerät liegt flach: Winkel aus der X/Y-Komponente berechnen
  let heading = Math.atan2(mag.y, mag.x) * (180 / Math.PI);
  heading = (heading + 360) % 360;
  console.log(`Ausrichtung: ${Math.round(heading)}°`);
};

mag.onerror = (event) => console.error('Sensorfehler:', event.error.name);
mag.start();

Ausrichtung: 273°

Berechtigung prüfen und Sensor sauber beenden

const startMagnetometer = async () => {
  const { state } = await navigator.permissions.query({ name: 'magnetometer' });
  if (state === 'denied') {
    console.warn('Zugriff auf das Magnetometer wurde verweigert.');
    return null;
  }

  const mag = new Magnetometer({ frequency: 20 });
  mag.addEventListener('reading', () => {
    // Gesamtfeldstärke berechnen (Erdmagnetfeld: ca. 25–65 µT)
    const strength = Math.hypot(mag.x, mag.y, mag.z);
    if (strength > 100) console.log('Starkes Magnetfeld erkannt:', strength.toFixed(0), 'µT');
  });
  mag.start();
  return mag;
};

const sensor = await startMagnetometer();
// Später, z. B. beim Verlassen der Ansicht:
document.addEventListener('visibilitychange', () => {
  if (document.hidden) sensor?.stop();
});

Starkes Magnetfeld erkannt: 184 µT

// Wichtig · Fallstricke

Browser-Unterstützung: Die Schnittstelle ist experimentell. Sie steht nur in Chromium-Browsern bereit und dort nur, wenn das Flag chrome://flags/#enable-generic-sensor-extra-classes aktiviert ist. Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb immer vorher mit 'Magnetometer' in window, ob sie vorhanden ist.
Sicherer Kontext und Permissions Policy: Die Schnittstelle funktioniert nur über HTTPS. In iframes muss der Zugriff mit allow="magnetometer" freigegeben werden. Andernfalls löst der Konstruktor einen SecurityError aus oder das Ereignis error wird ausgelöst.
Fehlerbehandlung: Fehlt die Hardware, liefert error einen NotReadableError. Fehlt die Berechtigung, ist es ein NotAllowedError. Wenn Sie den Konstruktor aufrufen, fangen Sie Ausnahmen zusätzlich mit try…catch ab.
Kalibrierung und Störungen: Die Werte werden von Metall, Lautsprechern, Magnethüllen und Elektronik in der Nähe beeinflusst. Ein Kompass allein aus x/y ist nur genau, wenn das Gerät flach liegt. Für echte Kompass-Anwendungen ist AbsoluteOrientationSensor robuster. Für Rohdaten ohne Kalibrierung gibt es UncalibratedMagnetometer.
Datenschutz und Akku: Magnetfelddaten eignen sich zum Fingerprinting. Fordern Sie deshalb nur die Frequenz an, die Sie wirklich brauchen. Stoppen Sie den Sensor mit stop(), wenn die Seite im Hintergrund ist. Das spart Akku, und im Hintergrund liefern Browser ohnehin keine Messwerte.

Siehe auch

Sensor Accelerometer Gyroscope Permissions.prototype.query() ImageDecoder