Document.hasFocus() — Methode · JavaScript-Referenz

Signatur

Document.prototype.hasFocus()

Beschreibung

document.hasFocus() prüft, ob das Dokument gerade aktiv ist, also ob es selbst oder eines seiner Elemente (auch ein eingebettetes Dokument in einem <iframe>) den Fokus hat. Damit lässt sich feststellen, ob der Benutzer gerade mit der Seite arbeitet oder ob ein anderes Fenster, ein anderer Tab oder eine andere Anwendung im Vordergrund ist.

Typische Einsatzfälle: Benachrichtigungen nur dann zeigen, wenn der Benutzer die Seite nicht gerade ansieht, Polling oder Animationen drosseln, solange das Fenster inaktiv ist, oder Statusanzeigen („Benutzer ist abwesend“) umsetzen.

Wichtig ist der Unterschied zu document.activeElement und zur Page Visibility API: activeElement liefert welches Element fokussiert ist (auch wenn das Fenster selbst inaktiv ist), während hasFocus() sagt, ob das Dokument überhaupt fokussiert ist. Eine Seite kann sichtbar sein (visibilityState === "visible") und trotzdem keinen Fokus haben, zum Beispiel wenn daneben ein anderes Fenster aktiv ist.

Die Methode liefert nur den aktuellen Zustand und kann nicht beobachtet werden. Wenn du auf Änderungen reagieren willst, verwende die Events focus und blur auf window und frage dort bei Bedarf hasFocus() ab.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Dokument oder eines seiner Elemente (auch in untergeordneten Frames) den Fokus hat, sonst false.

Beispiele

Fokus-Zustand einmalig prüfen

// Sofort beim Laden prüfen
console.log(document.hasFocus() ? 'Seite ist aktiv' : 'Seite ist im Hintergrund');

Seite ist aktiv

Benachrichtigung nur bei inaktivem Fenster

const notifyNewMessage = async (text) => {
  // Benutzer sieht die Seite gerade: keine System-Benachrichtigung nötig
  if (document.hasFocus()) {
    console.log('Inline-Hinweis:', text);
    return;
  }
  if (Notification.permission !== 'granted') {
    await Notification.requestPermission();
  }
  if (Notification.permission === 'granted') {
    new Notification('Neue Nachricht', { body: text });
  }
};

notifyNewMessage('Hallo von Anna!');

Fokus-Wechsel mit focus/blur und hasFocus() anzeigen

const updateStatus = () => {
  document.title = document.hasFocus() ? 'Aktiv' : 'Abwesend';
};

window.addEventListener('focus', updateStatus);
window.addEventListener('blur', updateStatus);
updateStatus();

Polling drosseln, solange die Seite keinen Fokus hat

const poll = async () => {
  const res = await fetch('/api/status');
  console.log('Status:', await res.json());
  // Aktiv: alle 5 s, inaktiv: alle 60 s
  setTimeout(poll, document.hasFocus() ? 5000 : 60000);
};

poll();

Status: { ... }

// Wichtig · Fallstricke

Nicht gleich Sichtbarkeit: hasFocus() kann false sein, obwohl die Seite sichtbar ist, etwa bei einem zweiten Monitor oder wenn die Entwicklerwerkzeuge fokussiert sind. Für „Tab ist sichtbar“ verwende document.visibilityState und das Event visibilitychange.
Entwicklerwerkzeuge: Wenn du document.hasFocus() direkt in der Konsole ausführst, liefert es meist false, weil die Konsole den Fokus hat. Teste lieber mit setTimeout(() => console.log(document.hasFocus()), 3000) und klicke vorher in die Seite.
iframes: Hat ein Element in einem eingebetteten <iframe> den Fokus, liefert hasFocus() im übergeordneten Dokument ebenfalls true. Das Dokument im iframe liefert nur dann true, wenn der Fokus in ihm selbst liegt.
Kein Event: Die Methode fragt nur den Zustand ab. Für Änderungen brauchst du focus/blur auf window oder focusin/focusout auf document.
Die Methode wird von allen modernen Browsern unterstützt, auch von älteren Versionen des Internet Explorer.

Siehe auch

Document.activeElement Document.visibilityState HTMLElement.focus() DOMImplementation.hasFeature() Document.append()