Document.fragmentDirective — Eigenschaft · JavaScript-Referenz

Signatur

get Document.fragmentDirective

Beschreibung

document.fragmentDirective liefert ein FragmentDirective-Objekt. Es gehört zur Fragment-Direktive einer URL, also zu dem Teil nach #:~:. Dort stehen zum Beispiel Text-Fragmente wie https://example.com/seite#:~:text=Suchbegriff. Beim Aufruf einer solchen Adresse scrollt der Browser zu der gesuchten Textstelle und hebt sie hervor, auch wenn die Seite dafür keinen eigenen Anker (id) hat.

Das Objekt selbst hat bisher kaum Funktionen. Man verwendet die Eigenschaft deshalb vor allem zur Funktionserkennung: Ist 'fragmentDirective' in document wahr, versteht der Browser Text-Fragment-Links. So kann eine Anwendung etwa einen Button „Link zu dieser Textstelle kopieren“ nur dann anzeigen, wenn der Link beim Empfänger auch funktioniert.

Wichtig: Der Browser entfernt die Fragment-Direktive aus der URL, bevor Skripte sie zu sehen bekommen. location.hash, location.href und document.URL enthalten den Teil :~:text=… nicht. Eine Seite kann also nicht auslesen, nach welchem Text ein Besucher gesucht hat. Das ist so gewollt und schützt die Privatsphäre.

Rückgabewert

Typ

FragmentDirective | undefined

Beschreibung

Das FragmentDirective-Objekt des Dokuments. In Browsern ohne Unterstützung gibt es die Eigenschaft nicht, der Zugriff ergibt dann undefined.

Beispiele

Prüfen, ob der Browser Text-Fragmente unterstützt

const unterstuetztTextFragmente = 'fragmentDirective' in document;

console.log(unterstuetztTextFragmente
  ? 'Text-Fragmente werden unterstützt'
  : 'Keine Unterstützung für Text-Fragmente');
console.log(document.fragmentDirective);

Text-Fragmente werden unterstützt FragmentDirective {}

Link zur markierten Textstelle erzeugen (nur bei Unterstützung)

const erzeugeTextLink = (text) => {
  const url = new URL(location.href);
  url.hash = ''; // vorhandenen Anker entfernen
  return `${url.href}#:~:text=${encodeURIComponent(text)}`;
};

document.addEventListener('mouseup', async () => {
  const auswahl = window.getSelection().toString().trim();
  if (!auswahl || !('fragmentDirective' in document)) return;

  const link = erzeugeTextLink(auswahl);
  await navigator.clipboard.writeText(link);
  console.log('Kopiert:', link);
});

Kopiert: https://example.com/artikel#:~:text=Fragment%20Direktive

Die Direktive ist für Skripte unsichtbar

// Seite aufgerufen mit: https://example.com/doku#abschnitt:~:text=Beispiel
console.log(location.hash);
console.log(location.href.includes(':~:'));

#abschnitt false

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser seit Version 86 (Text-Fragmente selbst seit Version 80), Safari seit 16.1, Firefox erst seit 131. In älteren Browsern fehlt die Eigenschaft. Sie sollte also immer mit 'fragmentDirective' in document geprüft werden und nicht über den Wert selbst.
Kein Auslesen der Direktive: location.hash und location.href enthalten den Teil :~:… nicht. Aus Datenschutzgründen gibt es auch keine offizielle Programmierschnittstelle, mit der eine Seite den gesuchten Text erfährt.
Wenig Funktionsumfang: FragmentDirective hat derzeit keine standardisierten Eigenschaften. Weitere Methoden (etwa zum Erzeugen von Selektoren) sind höchstens experimentell verfügbar und sollten im Produktivcode nicht vorausgesetzt werden.
Einschränkungen beim Scrollen: Browser springen nur unter bestimmten Bedingungen zur Textstelle, zum Beispiel wenn die Navigation vom Nutzer ausgelöst wurde und nicht in einem iframe stattfindet. Mit dem Header Document-Policy: force-load-at-top kann eine Seite das automatische Scrollen abschalten.
Sonderzeichen wie -, & und , im Suchtext müssen mit encodeURIComponent() kodiert werden, weil sie in der Text-Direktive eine eigene Bedeutung haben.

Siehe auch

Document Location.hash HTMLTextAreaElement.required PerformanceTiming.redirectEnd Document.documentURI