Versteckte Inhalte suchen

Webfunktionen: <details> Sich gegenseitig ausschließende <details>-Elemente hidden="until-found"

In Weboberflächen werden Inhalte oft ausgeblendet, um die Nutzerfreundlichkeit zu verbessern, Platz auf dem Bildschirm zu sparen oder die Seitenleistung zu erhöhen. Mit herkömmlichen Methoden wie display: none oder visibility: hidden werden Inhalte visuell ausgeblendet, aber sie sind dann auch für Screenreader und Browserfunktionen wie „Auf Seite suchen“ nicht mehr zugänglich.

Wenn ihr Inhalte visuell ausblenden, aber dennoch für Nutzer suchbar machen und über URL-Fragmente und „Scroll to Text Fragment“-Links verlinken möchtet, könnt ihr entweder das HTML-Element <details> oder das Attribut hidden="until-found" verwenden. Das <details>-Element wird im Allgemeinen empfohlen, da es einfacher zu implementieren und zu verwalten ist. Es gibt jedoch einige komplexere Fälle, in denen <details> nicht ausreicht und hidden="until-found" erforderlich ist.

Beispiel:

  • Wenn Sie die volle Kontrolle über das Design des Ein-/Ausblendemechanismus haben möchten.
  • Wenn sich die UI-Steuerelemente zum Ein-/Ausblenden des Inhalts in einem anderen Teil des DOM befinden.
  • Wenn Sie das Ausblenden der Inhalte nach der Anzeige nicht unterstützen möchten.

Implementierung

Das <details>-Element enthält standardmäßig durchsuchbaren und barrierefreien Text. Es ist keine spezielle Implementierung erforderlich. Verwenden Sie nach Möglichkeit <details> anstelle von hidden="until-found".

Wenn Sie stattdessen hidden="until-found" verwenden müssen, gehen Sie so vor:

  1. Attribut anwenden: Fügen Sie das HTML-Attribut hidden="until-found" direkt den Elementen hinzu, die die Inhalte enthalten, die ausgeblendet werden sollen.
  2. UI-Status synchronisieren: Wenn die Benutzeroberfläche verwandte Status hat, die von der Sichtbarkeit des Inhalts abhängen (z.B. Aktualisieren von ARIA-Attributen, Umschalten von CSS-Klassen zum Öffnen/Schließen oder Drehen von Akkordeonsymbolen):
    • Sie MÜSSEN einen Event-Listener für das beforematch-Ereignis hinzufügen.
    • Registrieren Sie den beforematch-Event-Listener direkt für das Element mit dem hidden="until-found"-Attribut. Da das Ereignis weitergegeben wird, können Sie alternativ die Ereignisdelegierung verwenden, indem Sie einen einzelnen Listener für ein übergeordnetes Element (z. B. einen Tab-Container) registrieren, um mehrere ausgeblendete Abschnitte gleichzeitig zu verwalten.
    • Führen Sie im Event-Listener die Logik aus, um zugehörige UI-Elemente zu synchronisieren (z. B. andere geöffnete Tabs schließen oder den Status eines Ein/Aus-Buttons ändern).

Beispielcode

Ziel: Einen ausgeblendeten Container rendern, dessen Inhalt für den Nutzer unsichtbar bleibt, bis er nach einem Wort in diesem Bereich sucht.

<details>-Element verwenden

<details>
  <summary>Click to expand</summary>
  <p>This content is visually hidden.</p>
</details>

Sich gegenseitig ausschließende Offenlegungen

Wenn Sie sich gegenseitig ausschließende Inhaltsbereiche wie ein exklusives Akkordeon verarbeiten, verwenden Sie das native HTML-Element <details> mit einem gemeinsamen name-Attribut.

<div class="accordion-group">
  <!-- The name attribute creates an exclusive disclosure group -->
  <details class="disclosure" name="my-accordion">
    <summary>Section 1</summary>
    <p>Section 1 content</p>
  </details>

  <details class="disclosure" name="my-accordion" open>
    <summary>Section 2</summary>
    <p>Section 2 content</p>
  </details>

  <details class="disclosure" name="my-accordion">
    <summary>Section 3</summary>
    <p>Section 3 content</p>
  </details>
</div>

Attribut hidden="until-found" verwenden

<!-- The browser automatically removes hidden="until-found" upon a search match -->
<div class="hidden-container" hidden="until-found">
  <p>This content is visually hidden.</p>
</div>

Benutzerdefinierte, sich gegenseitig ausschließende Offenlegungen

Wenn Sie benutzerdefinierte, sich gegenseitig ausschließende Bereiche verarbeiten, die über externe Schaltflächen gesteuert werden, achten Sie darauf, dass nur das übereinstimmende Steuerfeld sichtbar bleibt. Im beforematch-Event-Handler MÜSSEN Sie zugehörige ARIA-Zustände synchronisieren, z. B. aria-expanded="true" auf der steuernden Schaltfläche festlegen.

<div class="custom-accordion">
  <div class="controls">
    <button aria-expanded="true" aria-controls="panel-1" id="btn-1">Section 1</button>
    <button aria-expanded="false" aria-controls="panel-2" id="btn-2">Section 2</button>
  </div>

  <div id="panel-1" class="panel">
    <p>Section 1 content (visible)</p>
  </div>

  <div id="panel-2" class="panel" hidden="until-found">
    <p>Section 2 content (hidden)</p>
  </div>
</div>

const accordion = document.querySelector('.custom-accordion');

accordion.addEventListener('beforematch', (e) => {
  // Hide all panels and synchronize button states before the browser reveals the matched panel
  accordion.querySelectorAll('.panel').forEach((panel) => {
    if (panel !== e.target) {
      panel.hidden = 'until-found';
    }
  });
  accordion.querySelectorAll('button').forEach((btn) => {
    const controls = btn.getAttribute('aria-controls');
    btn.setAttribute('aria-expanded', controls === e.target.id ? 'true' : 'false');
  });
});

Best Practices für hidden="until-found"

  • DO apply borders, padding, and backgrounds to nested child wrappers rather than directly to the element with the hidden="until-found" attribute. So werden unbeabsichtigte Layoutverschiebungen oder visuelle Überbleibsel verhindert, während das Element ausgeblendet ist.
  • Wenden Sie display: none, visibility: hidden oder zugehörige CSS-Eigenschaften wie display oder visibility NICHT direkt auf Elemente mit dem Attribut hidden="until-found" an. Dadurch wird die native Funktionalität beeinträchtigt und der Inhalt wird dauerhaft aus dem Suchindex ausgeblendet.
  • Verwenden Sie hidden="until-found" NICHT für vertrauliche Informationen, interne Daten-Tokens oder irrelevante Daten, die nicht über die Suche zugänglich sein sollen.
  • Verwenden Sie hidden="until-found" NICHT als Ersatz für Text, der nur für Screenreader bestimmt ist (.sr-only).

Browserunterstützung und Fallback-Strategien

Verzichten Sie NICHT auf hidden="until-found", nur weil es nicht von allen Browsern unterstützt wird. Die Vorteile für die Barrierefreiheit im Internet überwiegen die Kosten für die Implementierung eines Fallbacks bei Weitem.

hidden="until-found" Fallback

Verwenden Sie für Standard-UI-Elemente wie Akkordeons oder „Mehr lesen“-Abschnitte JavaScript, um die Funktion zu erkennen und alle Inhalte anzuzeigen, wenn die Funktion nicht unterstützt wird.

if (!('onbeforematch' in HTMLElement.prototype)) {
  // Expand all hidden content for unsupported browsers
  document.querySelectorAll('[hidden="until-found"]').forEach((el) => {
    el.removeAttribute('hidden');
    // MANDATORY: also update any aria references to this element.
  });
}

Bei sich gegenseitig ausschließenden UI-Paradigmen (z. B. benutzerdefinierten exklusiven Bereichen, in denen Inhalte denselben visuellen Bereich teilen) sollte der Fallback alle Inhalte linear unter dem interaktiven Hauptbereich extrahieren und anzeigen. Dabei sollten URL-Ankerfragmente verwendet werden, damit Nutzer direkt zu den entsprechenden Abschnitten navigieren können.