XRTransientInputHitTestSource.cancel() — Methode · JavaScript-Referenz

Signatur

XRTransientInputHitTestSource.prototype.cancel()

Beschreibung

Die Methode cancel() beendet einen Treffertest, den du vorher mit XRSession.requestHitTestSourceForTransientInput() angemeldet hast. Transiente Eingaben sind kurzlebige Eingabequellen, zum Beispiel ein Fingertipp auf den Bildschirm in einer AR-Sitzung auf dem Smartphone (Profil "generic-touchscreen"). Solange die Quelle aktiv ist, rechnet der Browser in jedem Frame Treffertests gegen die erkannte reale Umgebung.

Rufe cancel() auf, sobald du die Ergebnisse nicht mehr brauchst. Typische Fälle: Der Nutzer hat ein Objekt platziert, der Platzierungsmodus ist vorbei, oder die Anwendung wechselt in einen anderen Zustand. So sparst du Rechenzeit und Akku, denn die Treffertests laufen sonst im Hintergrund weiter.

Nach dem Abmelden gibt XRFrame.getHitTestResultsForTransientInput() für diese Quelle keine Ergebnisse mehr zurück. Eine abgemeldete Quelle lässt sich nicht wieder aktivieren. Brauchst du erneut Treffertests, forderst du eine neue Quelle an.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Transiente Treffertest-Quelle anfordern und wieder abmelden

const session = await navigator.xr.requestSession('immersive-ar', {
  requiredFeatures: ['hit-test']
});

// Treffertests für Bildschirm-Tipps anfordern
const transientSource = await session.requestHitTestSourceForTransientInput({
  profile: 'generic-touchscreen'
});

// ... später, wenn die Tests nicht mehr gebraucht werden:
transientSource.cancel();
console.log('Transienter Treffertest abgemeldet');

Transienter Treffertest abgemeldet

Nach dem Platzieren eines Objekts abmelden

let transientSource = null;
let refSpace = null;

const startPlacement = async (session) => {
  refSpace = await session.requestReferenceSpace('local');
  transientSource = await session.requestHitTestSourceForTransientInput({
    profile: 'generic-touchscreen'
  });
  session.requestAnimationFrame(onFrame);
};

const onFrame = (time, frame) => {
  const session = frame.session;
  if (transientSource) {
    const results = frame.getHitTestResultsForTransientInput(transientSource);
    for (const inputResult of results) {
      const hit = inputResult.results[0];
      if (hit) {
        const pose = hit.getPose(refSpace);
        console.log('Objekt platziert bei', pose.transform.position);
        // Platzierung erledigt – Treffertest beenden
        transientSource.cancel();
        transientSource = null;
        break;
      }
    }
  }
  session.requestAnimationFrame(onFrame);
};

Objekt platziert bei DOMPointReadOnly {x: 0.12, y: -1.3, z: -0.8, w: 1}

Beim Sitzungsende aufräumen

const sources = new Set();

const addTransientSource = async (session) => {
  const source = await session.requestHitTestSourceForTransientInput({
    profile: 'generic-touchscreen'
  });
  sources.add(source);
  return source;
};

const cleanup = () => {
  sources.forEach((source) => source.cancel());
  sources.clear();
  console.log('Alle Treffertest-Quellen abgemeldet');
};

// session.addEventListener('end', cleanup);

Alle Treffertest-Quellen abgemeldet

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell. Sie wird vor allem von Chromium-basierten Browsern unterstützt (Chrome für Android mit ARCore). Firefox und Safari unterstützen sie nicht. Frage die Funktion "hit-test" beim Aufruf von requestSession() an und prüfe vorher, ob navigator.xr vorhanden ist.
WebXR funktioniert nur in einem sicheren Kontext (HTTPS).
Nach cancel() ist die Quelle dauerhaft ungültig. Setze deine Referenz deshalb auf null, damit du die Quelle nicht versehentlich weiter an getHitTestResultsForTransientInput() übergibst. Laut Spezifikation wird ein InvalidStateError ausgelöst, wenn du cancel() auf einer bereits abgemeldeten Quelle aufrufst. Rufe die Methode also nur einmal auf.
Wenn die Sitzung endet, werden alle Treffertest-Quellen automatisch ungültig. Es ist trotzdem gute Praxis, sie ausdrücklich abzumelden, sobald du sie nicht mehr brauchst. So sparst du Leistung und Akku.
Für Treffertests, die nicht an transiente Eingaben gebunden sind, gibt es das Gegenstück XRHitTestSource.cancel().

Siehe auch

XRTransientInputHitTestSource XRSession.requestHitTestSourceForTransientInput() XRFrame.getHitTestResultsForTransientInput() XRTransientInputHitTestResult XRHitTestSource.cancel()