FragmentDirective — Schnittstelle · JavaScript-Referenz

Signatur

interface FragmentDirective

Beschreibung

Die Schnittstelle FragmentDirective gehört zur Spezifikation für Textfragmente (URL Fragment Text Directives). Mit Textfragmenten verlinken Sie direkt auf eine bestimmte Textstelle einer Seite, auch wenn es dort keine id gibt. Das Format ist https://example.com/seite#:~:text=[prefix-,]textStart[,textEnde][,-suffix]. Der Browser scrollt zur ersten passenden Stelle und hebt sie hervor.

Eine Instanz erreichen Sie nur über die schreibgeschützte Eigenschaft document.fragmentDirective. Einen öffentlichen Konstruktor gibt es nicht. Die Schnittstelle hat derzeit auch keine eigenen Eigenschaften oder Methoden. Sie ist im Grunde ein Marker für die Funktionserkennung: Gibt es document.fragmentDirective, unterstützt der Browser Textfragmente.

Typische Einsatzfälle sind Funktionen wie „Link zu markiertem Text teilen“, Suchergebnisse, die direkt zur Fundstelle springen, und Dokumentationsseiten mit präzisen Deep-Links. Unterstützt der Browser keine Textfragmente, wird die Direktive einfach ignoriert. Die Seite lädt dann ganz normal oben, ohne Hervorhebung.

Wichtig ist, dass der Browser die Fragment-Direktive (alles ab :~:) aus location.hash entfernt, bevor Skripte darauf zugreifen können. Seiten können also nicht auslesen, welcher Text verlinkt wurde. Die Hervorhebung gestalten Sie per CSS mit dem Pseudo-Element ::target-text.

Rückgabewert

Typ

FragmentDirective | undefined

Beschreibung

document.fragmentDirective gibt ein FragmentDirective-Objekt zurück, wenn der Browser Textfragmente unterstützt. In älteren Browsern ist die Eigenschaft undefined.

Beispiele

Funktionserkennung für Textfragmente

const supportsTextFragments = 'fragmentDirective' in document;

if (supportsTextFragments) {
  console.log('Textfragmente werden unterstützt:', document.fragmentDirective);
} else {
  console.log('Keine Unterstützung – normale Anker-Links verwenden.');
}

Textfragmente werden unterstützt: FragmentDirective {}

„Link zur Textstelle kopieren“ aus der aktuellen Auswahl

// Baut aus dem markierten Text einen Deep-Link mit Textfragment
const buildTextFragmentUrl = (text) => {
  const url = new URL(location.href);
  url.hash = ''; // vorhandenen Anker entfernen
  const words = text.trim().split(/\s+/);
  // Lange Auswahl: Anfang und Ende als Bereich angeben
  const directive = words.length > 8
    ? `${encodeURIComponent(words.slice(0, 4).join(' '))},${encodeURIComponent(words.slice(-4).join(' '))}`
    : encodeURIComponent(words.join(' '));
  return `${url.href}#:~:text=${directive}`;
};

document.addEventListener('keydown', async (event) => {
  if (!(event.altKey && event.key === 'l')) return;
  const selected = window.getSelection()?.toString();
  if (!selected || !('fragmentDirective' in document)) return;

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

Kopiert: https://example.com/artikel#:~:text=Die%20Fetch-API%20liefert%20ein

Die Direktive ist für Skripte unsichtbar

// Aufruf der Seite über: https://example.com/doku#intro:~:text=Promise
console.log(location.hash);
// Die Direktive wird vor dem Skriptzugriff entfernt
console.log(location.hash.includes(':~:'));

#intro false

Hervorhebung nur bei Unterstützung gestalten

if (document.fragmentDirective) {
  const style = document.createElement('style');
  style.textContent = `
    ::target-text {
      background-color: #ffe066;
      color: #000;
    }
  `;
  document.head.append(style);
}

// Wichtig · Fallstricke

Keine Member: FragmentDirective hat aktuell keine Eigenschaften oder Methoden. Ein früher vorgeschlagenes createSelectorDirective() ist nicht standardisiert. Nutzen Sie das Objekt nur zur Funktionserkennung.
Browser-Unterstützung: Chromium-Browser (seit Chrome 81 für Textfragmente, seit 86 für document.fragmentDirective), Safari ab 16.1 und Firefox ab 131. Ältere Browser ignorieren :~:text=, und die Seite lädt ganz normal.
Kodierung: Die Zeichen -, , und & haben in der Direktive eine besondere Bedeutung. Im Text müssen sie prozentkodiert werden. encodeURIComponent() kodiert - nicht, deshalb ggf. zusätzlich .replace(/-/g, '%2D') anwenden.
Datenschutz und Sicherheit: Der Browser entfernt die Direktive aus location.hash, damit Seiten nicht erkennen können, welcher Text gesucht wurde. Textfragmente werden außerdem nur bei Navigationen auf oberster Ebene mit Nutzerinteraktion ausgeführt. In iframes aus anderen Ursprüngen und bei rein skriptgesteuerten Navigationen greifen sie in der Regel nicht.
Passt der Text nicht eindeutig oder gar nicht (z. B. weil sich der Inhalt geändert hat), wird die erste Fundstelle bzw. gar nichts hervorgehoben. Machen Sie Links mit prefix- und -suffix robuster.
Seiten können Textfragmente per Document-Policy: force-load-at-top abschalten.

Siehe auch

Location.hash DocumentTimeline CSSPerspective PaymentAddress PaymentRequest