Dokument: ariaNotify()-Methode
Eingeschränkt verfügbar
Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.
Die ariaNotify()-Methode der Document-Schnittstelle stellt eine Zeichenkette in die Warteschlange, die von einem Screenreader angekündigt werden soll.
Syntax
ariaNotify(announcement)
ariaNotify(announcement, options)
Parameter
announcement-
Eine Zeichenkette, die den Text spezifiziert, der angekündigt werden soll.
optionsOptional-
Ein Options-Objekt, das die folgenden Eigenschaften enthält:
priority-
Ein enumerierter Wert, der die Priorität der Ankündigung spezifiziert. Mögliche Werte sind:
Rückgabewert
Keiner (undefined).
Beschreibung
Die ariaNotify()-Methode kann verwendet werden, um programmatisch eine Screenreader-Ankündigung auszulösen. Diese Methode bietet ähnliche Funktionalität wie ARIA-Live-Regionen, mit einigen Vorteilen:
- Live-Regionen können nur Ankündigungen machen, nachdem Änderungen am DOM vorgenommen wurden, während eine
ariaNotify()-Ankündigung jederzeit gemacht werden kann. - Bei Ankündigungen in Live-Regionen wird der aktualisierte Inhalt des geänderten DOM-Knotens gelesen, während der Inhalt der
ariaNotify()-Ankündigung unabhängig vom DOM-Inhalt definiert werden kann.
Entwickler umgehen oft die Einschränkungen von Live-Regionen, indem sie verborgene DOM-Knoten mit Live-Regionen darauf verwenden, deren Inhalte mit dem angekündigten Inhalt aktualisiert werden. Dies ist ineffizient und fehleranfällig, und ariaNotify() bietet eine Möglichkeit, solche Probleme zu vermeiden.
Einige Screenreader lesen mehrere ariaNotify()-Ankündigungen der Reihe nach vor, aber dies kann nicht für alle Screenreader und Plattformen garantiert werden. Normalerweise wird nur die letzte Ankündigung gesprochen. Es ist zuverlässiger, mehrere Ankündigungen zu einer zu kombinieren.
Zum Beispiel wären die folgenden Aufrufe:
document.ariaNotify("Hello there.");
document.ariaNotify("The time is now 8 o'clock.");
besser kombiniert:
document.ariaNotify("Hello there. The time is now 8 o'clock.");
ariaNotify()-Ankündigungen erfordern keine vorübergehende Aktivierung; Sie sollten darauf achten, Screenreader-Nutzer nicht mit zu vielen Benachrichtigungen zu überfluten, da dies eine schlechte Benutzererfahrung schaffen könnte.
Ankündigungsprioritäten
Eine ariaNotify()-Ankündigung mit priority: high wird vor einer ariaNotify()-Ankündigung mit priority: normal angekündigt.
ariaNotify()-Ankündigungen sind grob gleichwertig mit ARIA-Live-Region-Ankündigungen wie folgt:
ariaNotify()priority: high:aria-live="assertive".ariaNotify()priority: normal:aria-live="polite".
Allerdings haben aria-live-Ankündigungen Vorrang vor ariaNotify()-Ankündigungen.
Sprachauswahl
Screenreader wählen eine geeignete Stimme, um ariaNotify()-Ankündigungen vorzulesen (in Bezug auf Akzent, Aussprache usw.), basierend auf der in dem <html>-Element angegebenen Sprache im lang-Attribut oder der Standardsprache des Benutzeragenten, wenn kein lang-Attribut gesetzt ist.
Integration der Berechtigungspolitik
Die Nutzung von ariaNotify() in einem Dokument oder <iframe> kann durch eine aria-notify Berechtigungsrichtlinie gesteuert werden.
Speziell dort, wo eine definierte Richtlinie die Nutzung blockiert, schlagen alle mit ariaNotify() erzeugten Ankündigungen geräuschlos fehl (sie werden nicht gesendet).
Beispiele
Grundlegende Nutzung von ariaNotify()
Dieses Beispiel enthält einen <button>, der eine Screenreader-Ankündigung auslöst, wenn er angeklickt wird.
<button>Press</button>
document.querySelector("button").addEventListener("click", () => {
document.ariaNotify("Hi there, I'm Ed Winchester.");
});
Ergebnis
Das Ergebnis ist wie folgt:
Versuchen Sie, einen Screenreader zu aktivieren und dann die Taste zu drücken. Sie sollten hören, wie der Screenreader "Hi there, I'm Ed Winchester." sagt.
Beispiel für eine zugängliche Einkaufsliste
Dieses Beispiel ist eine Einkaufsliste, die es ermöglicht, Artikel hinzuzufügen und zu entfernen, und die die Gesamtkosten aller Artikel nachverfolgt. Wenn ein Artikel hinzugefügt oder entfernt wird, wird von Screenreadern eine Ankündigung vorgelesen, die sagt, welcher Artikel hinzugefügt/entfernt wurde und was die aktualisierte Gesamtsumme ist.
HTML
Unser HTML enthält ein <form>, das zwei <input>-Elemente enthält — ein text-Input zum Eingeben von Artikelnamen und ein number-Input zum Eingeben von Preisen. Beide Eingaben sind required, und das number-Input hat einen step-Wert von 0.01, um zu verhindern, dass Nicht-Preiswerte (wie große Dezimalzahlen) eingegeben werden.
Unter dem Formular haben wir eine ungeordnete Liste, um hinzugefügte Artikel darin darzustellen, und ein <p>-Element, um die Gesamtkosten anzuzeigen.
<h1><code>ariaNotify</code> demo: shopping list</h1>
<form>
<div>
<label for="item">Enter item name</label>
<input type="text" name="item" id="item" required />
</div>
<div>
<label for="price">Enter item price</label>
<input type="number" name="price" id="price" step="0.01" required />
</div>
<div>
<button>Submit</button>
</div>
</form>
<hr />
<ul></ul>
<p>Total: £0.00</p>
JavaScript
Unser Skript beginnt mit mehreren konstanten Definitionen, um Referenzen zum <form>, unseren beiden <input>-Elementen und unseren <ul>- und <p>-Elementen zu speichern. Wir fügen auch eine total-Variable hinzu, um den Gesamtpreis aller Artikel zu speichern.
const form = document.querySelector("form");
const item = document.querySelector("input[type='text']");
const price = document.querySelector("input[type='number']");
const priceList = document.querySelector("ul");
const totalOutput = document.querySelector("p");
let total = 0;
Im nächsten Codeblock definieren wir eine Funktion namens updateTotal(), die eine Aufgabe hat — den Preis, der im <p>-Element angezeigt wird, auf den aktuellen Wert der total-Variablen zu aktualisieren:
function updateTotal() {
totalOutput.textContent = `Total: £${Number(total).toFixed(2)}`;
}
Als nächstes definieren wir eine Funktion namens addItemToList(). Im Funktionskörper erstellen wir zunächst ein <li>-Element, um einen neu hinzugefügten Artikel zu speichern. Wir speichern den Artikelnamen und den Preis in data-*-Attributen auf dem Element und machen seinen Textinhalt gleich einer Zeichenkette, die den Artikel und den Preis enthält. Wir erstellen auch ein <button>-Element mit dem Text "Remove <item-name>", fügen dann das Listenelement der unbeordneten Liste hinzu und den Button dem Listenelement.
Der zweite Hauptteil des Funktionskörpers ist eine Definition eines click-Ereignislisteners auf dem Button. Wenn der Button geklickt wird, greifen wir zunächst auf eine Referenz zum Elternelement des Buttons zu — dem Listenelement, in dem sich der Button befindet. Wir subtrahieren dann die Zahl, die im data-price-Attribut des Listenelements enthalten ist, von der total-Variablen, rufen die updateTotal()-Funktion auf, um den angezeigten Gesamtpreis zu aktualisieren, und rufen ariaNotify() auf, um den entfernten Artikel und den neuen Gesamtbetrag anzukündigen. Schließlich entfernen wir das Listenelement aus dem DOM.
function addItemToList(item, price) {
const listItem = document.createElement("li");
listItem.setAttribute("data-item", item);
listItem.setAttribute("data-price", price);
listItem.textContent = `${item}: £${Number(price).toFixed(2)}`;
const btn = document.createElement("button");
btn.textContent = `Remove ${item}`;
priceList.appendChild(listItem);
listItem.appendChild(btn);
btn.addEventListener("click", (e) => {
const listItem = e.target.parentNode;
total -= Number(listItem.getAttribute("data-price"));
updateTotal();
document.ariaNotify(
`${listItem.getAttribute(
"data-item",
)} removed. Total is now £${total.toFixed(2)}.`,
{
priority: "high",
},
);
listItem.remove();
});
}
Unser letzter Codeblock fügt einen submit-Ereignislistener zum <form> hinzu. Im Funktionshandler rufen wir zunächst preventDefault() auf das Ereignisobjekt auf, um das Absenden des Formulars zu verhindern. Wir rufen dann addItemToList() auf, um den neuen Artikel und den Preis in der Liste anzuzeigen, fügen den Preis zur total-Variablen hinzu, rufen updateTotal() auf, um den angezeigten Gesamtbetrag zu aktualisieren, und rufen ariaNotify() auf, um den hinzugefügten Artikel und den neuen Gesamtbetrag anzukündigen. Schließlich leeren wir die aktuellen Eingabefeldwerte, damit der nächste Artikel hinzugefügt werden kann.
form.addEventListener("submit", (e) => {
e.preventDefault();
addItemToList(item.value, price.value);
total += Number(price.value);
updateTotal();
document.ariaNotify(
`Item ${item.value}, price £${
price.value
}, added to list. Total is now £${total.toFixed(2)}.`,
{
priority: "high",
},
);
item.value = "";
price.value = "";
});
Ergebnis
Das Ergebnis ist wie folgt:
Versuchen Sie, einen Screenreader zu aktivieren und einige Artikel hinzuzufügen und zu entfernen. Sie sollten hören können, dass sie von dem Screenreader angekündigt werden.
Spezifikationen
| Spezifikation |
|---|
| Accessible Rich Internet Applications (WAI-ARIA) # ARIANotifyMixin |