Magnetometer.x — Eigenschaft · JavaScript-Referenz

Signatur

Magnetometer.x

Beschreibung

Die Eigenschaft x der Schnittstelle Magnetometer (Generic Sensor API) enthält den zuletzt gemessenen Wert des Magnetfelds entlang der x-Achse des Geräts. Die Einheit ist Mikrotesla (µT). Die x-Achse verläuft bei einem Smartphone im Hochformat waagerecht von links nach rechts über das Display.

Zusammen mit y und z ergibt sich der Vektor des Magnetfelds. Daraus lassen sich z. B. eine einfache Kompassrichtung berechnen, Metall in der Nähe erkennen oder, zusammen mit Beschleunigungssensor und Gyroskop, die Lage des Geräts im Raum bestimmen.

Der Wert steht erst zur Verfügung, nachdem der Sensor mit start() gestartet wurde und die erste Messung gemeldet hat, meist im reading-Event. Vorher und nach einem Fehler ist x null. Weil es sich um eine reine Lese-Eigenschaft handelt, hat eine Zuweisung keine Wirkung.

Rückgabewert

Typ

number | null

Beschreibung

Magnetfeldstärke entlang der x-Achse in Mikrotesla (µT) oder null, solange noch keine Messung vorliegt.

Beispiele

Magnetfeld aller Achsen ausgeben

const sensor = new Magnetometer({ frequency: 10 });

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

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

sensor.start();

x: 12.34 µT y: -20.51 µT z: -38.02 µT

Einfache Kompassrichtung berechnen (Gerät liegt flach)

const sensor = new Magnetometer({ frequency: 5 });

sensor.onreading = () => {
  // Gilt nur für ein waagerecht liegendes, unkalibriertes Gerät
  let heading = Math.atan2(sensor.y, sensor.x) * (180 / Math.PI);
  heading = (heading + 360) % 360;
  console.log(`Richtung: ${Math.round(heading)}°`);
};

sensor.start();

Richtung: 57°

Unterstützung und Berechtigung prüfen, Metall erkennen

const startMetalDetector = async () => {
  if (!('Magnetometer' in window)) {
    console.warn('Magnetometer wird nicht unterstützt.');
    return;
  }

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

  const sensor = new Magnetometer({ frequency: 20 });
  console.log('Vor dem Start:', sensor.x); // null

  sensor.onreading = () => {
    const staerke = Math.hypot(sensor.x, sensor.y, sensor.z);
    if (staerke > 100) console.log('Metall in der Nähe!', staerke.toFixed(1), 'µT');
  };
  sensor.start();
};

startMetalDetector();

Vor dem Start: null Metall in der Nähe! 143.7 µT

// Wichtig · Fallstricke

Kompatibilität: Der Magnetometer ist experimentell und in Chromium-Browsern nur mit dem Flag #enable-generic-sensor-extra-classes verfügbar. Firefox und Safari unterstützen ihn nicht. Verwende deshalb immer eine Feature-Erkennung ('Magnetometer' in window).
Die API funktioniert nur in einem sicheren Kontext (HTTPS) und kann über die Permissions Policy (magnetometer) gesperrt werden. Ist sie gesperrt, wirft der Konstruktor einen SecurityError.
Vor der ersten Messung ist x null. Ein Aufruf wie sensor.x.toFixed() außerhalb des reading-Events kann daher einen TypeError auslösen.
Die Rohwerte sind nicht kalibriert und werden durch Metall, Magnete und Elektronik in der Nähe verfälscht. Für eine genaue Lage des Geräts ist AbsoluteOrientationSensor besser geeignet. Für unkalibrierte Rohdaten mit Bias-Werten gibt es UncalibratedMagnetometer.
Datenschutz: Magnetfelddaten können zum Fingerprinting genutzt werden. Browser senken deshalb möglicherweise die Frequenz oder Genauigkeit der Messwerte.

Siehe auch

Magnetometer Magnetometer.y Magnetometer.z Sensor.start() AbsoluteOrientationSensor PannerNode.positionX