Magnetometer.z — Eigenschaft · JavaScript-Referenz

Signatur

Magnetometer.z

Beschreibung

Die Eigenschaft z des Magnetometer-Interfaces (Generic Sensor API) gibt die zuletzt gemessene Stärke des Magnetfelds entlang der z-Achse des Geräts zurück. Die Einheit ist Mikrotesla (µT). Die z-Achse steht senkrecht zum Bildschirm und zeigt beim flach liegenden Gerät nach oben, also zum Betrachter.

Zusammen mit x und y ergibt z den dreidimensionalen Magnetfeldvektor. Daraus lassen sich z. B. die Gesamtfeldstärke (Betrag des Vektors), die Neigung des Erdmagnetfelds oder Störungen durch Metall bzw. Magnete in der Nähe ermitteln. Für eine reine Kompassrichtung auf einem flach liegenden Gerät braucht man vor allem x und y; z wird wichtig, sobald das Gerät gekippt wird und eine Neigungskorrektur (z. B. mit dem Accelerometer) nötig ist.

Der Wert wird erst nach sensor.start() und dem ersten reading-Event gefüllt. Davor, nach stop() oder nach einem Fehler ist er null. Sinnvoll ausgelesen wird er deshalb im Handler des reading-Events.

Beispiele

z-Wert bei jeder Messung ausgeben

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

  sensor.addEventListener('reading', () => {
    console.log(`Magnetfeld z: ${sensor.z.toFixed(2)} µT`);
  });

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

  sensor.start();
} else {
  console.warn('Magnetometer wird von diesem Browser nicht unterstützt.');
}

Magnetfeld z: -42.17 µT Magnetfeld z: -42.09 µT

Gesamtfeldstärke berechnen und Metall erkennen

const sensor = new Magnetometer({ frequency: 20 });
const ERDFELD_MAX = 65; // Erdmagnetfeld liegt etwa zwischen 25 und 65 µT

sensor.addEventListener('reading', () => {
  const { x, y, z } = sensor;
  const staerke = Math.hypot(x, y, z);
  const status = staerke > ERDFELD_MAX * 1.5 ? 'Störung/Metall in der Nähe!' : 'normal';
  console.log(`|B| = ${staerke.toFixed(1)} µT (z = ${z.toFixed(1)}) → ${status}`);
});

sensor.start();

|B| = 48.3 µT (z = -40.2) → normal |B| = 131.7 µT (z = -118.4) → Störung/Metall in der Nähe!

Berechtigung prüfen und Wert vor/nach dem Start vergleichen

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

  const sensor = new Magnetometer();
  console.log('Vor dem Start:', sensor.z); // null

  sensor.addEventListener('reading', () => {
    console.log('Erste Messung z:', sensor.z);
    sensor.stop();
  }, { once: true });

  sensor.start();
};

messeZ();

Vor dem Start: null Erste Messung z: -39.84

// Wichtig · Fallstricke

Browser-Unterstützung: Das Magnetometer ist experimentell und nur in Chromium-Browsern verfügbar, meist erst nach Aktivieren des Flags #enable-generic-sensor-extra-classes. Firefox und Safari unterstützen es nicht. Prüfe die Verfügbarkeit immer vorher mit 'Magnetometer' in window.
Sicherer Kontext und Berechtigung: Die API steht nur über HTTPS zur Verfügung, braucht die Berechtigung magnetometer und muss bei eingebetteten iframes per Permissions Policy (allow="magnetometer") freigegeben werden.
null-Wert: Vor dem ersten reading-Event ist z null. Ein Aufruf wie sensor.z.toFixed() außerhalb des Handlers wirft dann einen TypeError.
Kalibrierung und Störungen: Die Rohwerte sind nicht kalibriert. Lautsprecher, Metallgehäuse, Magnethüllen oder Elektronik in der Nähe verfälschen die Messung deutlich. Für eine Kompassanzeige ist der AbsoluteOrientationSensor meist robuster.
Koordinatensystem: Standardmäßig bezieht sich die Achse auf das Gerät. Mit der Option referenceFrame: 'screen' im Konstruktor folgen die Achsen der Bildschirmausrichtung.
Datenschutz: Magnetometer-Daten lassen sich für Fingerprinting oder zum Ableiten des Standorts missbrauchen. Deshalb begrenzen Browser teilweise die Frequenz oder Genauigkeit.

Siehe auch

Magnetometer Magnetometer.x Magnetometer.y Sensor.prototype.start() Accelerometer