new Magnetometer() — Methode · JavaScript-Referenz

Signatur

new Magnetometer(options)

Beschreibung

Der Konstruktor Magnetometer() gehört zur Generic Sensor API. Er erzeugt ein Sensorobjekt, das die Stärke des umgebenden Magnetfelds in Mikrotesla (µT) getrennt nach den Achsen x, y und z misst. Solche Werte braucht man etwa für Kompass-Anwendungen, zum Erkennen von Metall in der Nähe oder für eigene Sensorfusion zusammen mit Accelerometer und Gyroscope.

Durch das Erzeugen des Objekts startet die Messung noch nicht. Erst nach dem Aufruf von start() fragt der Sensor Werte ab und löst bei jedem neuen Messwert das Ereignis reading aus. Fehler wie fehlende Berechtigungen oder nicht vorhandene Hardware kommen über das Ereignis error an. Mit stop() beendet man die Messung wieder, was auch Akku spart.

Über das Objekt options legt man die gewünschte Abtastrate (frequency) und das Bezugssystem (referenceFrame) fest. Das Bezugssystem kann das Gerät selbst sein ("device") oder der Bildschirm ("screen"). Im zweiten Fall werden die Achsen passend zur aktuellen Bildschirmausrichtung umgerechnet.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Einstellungsobjekt für den Sensor.
$options.frequency	number	abhängig vom Gerät	Gewünschte Anzahl an Messungen pro Sekunde (Hz). Der Browser kann die Rate nach unten begrenzen.
$options.referenceFrame	"device" \| "screen"	"device"	Bezugssystem der Achsen: `"device"` nutzt das Gerät, `"screen"` rechnet die Achsen auf die aktuelle Bildschirmausrichtung um.

Rückgabewert

Typ

Magnetometer

Beschreibung

Ein neues, noch nicht gestartetes Magnetometer-Objekt mit den Eigenschaften x, y, z, timestamp, activated und hasReading.

Beispiele

Sensor 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: 21.3 µT, y: -4.8 µT, z: -38.2 µT

Einfacher Kompass (Gerät flach liegend)

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

mag.addEventListener('reading', () => {
  // Winkel in der Horizontalebene; 0° ≈ magnetischer Norden
  let heading = Math.atan2(mag.y, mag.x) * (180 / Math.PI);
  heading = (heading + 360) % 360;
  document.querySelector('#kompass').textContent = `${Math.round(heading)}°`;
});

mag.start();

// Messung bei verstecktem Tab anhalten, um Akku zu sparen
document.addEventListener('visibilitychange', () => {
  document.hidden ? mag.stop() : mag.start();
});

Berechtigung prüfen und Fehler behandeln

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

  try {
    const mag = new Magnetometer();
    mag.onerror = ({ error }) => {
      if (error.name === 'NotReadableError') {
        console.error('Sensor nicht verfügbar.');
      }
    };
    mag.onreading = () => console.log('Feldstärke z:', mag.z);
    mag.start();
    return mag;
  } catch (err) {
    // z. B. SecurityError durch Permissions-Policy
    console.error('Konstruktor fehlgeschlagen:', err.name);
    return null;
  }
};

startMagnetometer();

Feldstärke z: -38.2

// Wichtig · Fallstricke

Experimentell und kaum unterstützt: Nur Chromium-basierte Browser bieten die API an, meist erst nach Aktivieren von chrome://flags/#enable-generic-sensor-extra-classes. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer vorher mit 'Magnetometer' in window.
Nur in sicherem Kontext: Die API funktioniert nur über HTTPS (oder localhost). In iframes muss sie zusätzlich per Permissions-Policy (allow="magnetometer") freigegeben sein. Sonst wirft der Konstruktor einen SecurityError.
Fehlende Hardware oder verweigerte Berechtigung werfen keine Ausnahme im Konstruktor. Sie werden erst nach start() über das Ereignis error gemeldet (NotReadableError, NotAllowedError).
Vor dem ersten Messwert sind x, y und z null. Prüfe bei Bedarf hasReading.
Die Messwerte sind nicht kalibriert und reagieren stark auf Metall und Elektronik in der Nähe. Für eine zuverlässige Himmelsrichtung ist AbsoluteOrientationSensor meist besser geeignet.
Datenschutz: Magnetometer-Daten können für Fingerprinting missbraucht werden. Browser begrenzen deshalb die Abtastrate und liefern Werte nur, solange die Seite sichtbar ist.

Siehe auch

Magnetometer Sensor Sensor.prototype.start() Accelerometer new Accelerometer()