Addaw, anar a la pàgina d'inici Donar

Tècnica ARIA WCAG 2.2

ARIA19Anunciar els errors d'un formulari amb role="alert" o aria-live

Nom oficial al W3C: Utilitzar la funció (role) alert d'ARIA o regions actives per identificar errors

Versión en castellano

En poques paraules

Quan un formulari mostra un error sense tornar a carregar la pàgina, el lector de pantalla no se n'assabenta sol. Si el missatge s'escriu en una regió activa (una zona marcada amb role="alert" o aria-live), es llegeix en veu alta a l'instant. Aquesta zona ha d'existir a la pàgina des del principi.

Per què és important

Una persona cega prem «Envia» i el focus es queda en el botó. El missatge d'error apareix a la pantalla, però ella no el sent. Creu que tot ha anat bé.

Una regió activa fa que el lector de pantalla llegeixi el missatge sense moure el focus. Així la persona sap que hi ha un error i el pot corregir.

Com es fa

  1. Col·loqueu a l'HTML inicial un contenidor buit amb role="alert", que equival a aria-live="assertive".
  2. Afegiu-hi aria-atomic="true" perquè es llegeixi el missatge complet. VoiceOver a l'iPhone i l'iPad ho necessita per avisar a partir del segon enviament.
  3. En detectar l'error, escriviu el text dins d'aquest contenidor amb JavaScript.
  4. En cada enviament nou, buideu el contenidor abans d'escriure-hi el missatge nou.
  5. Reserveu role="alert" per a errors i avisos urgents. Per a missatges d'èxit, utilitzeu role="status".

Exemple pràctic

Formulari de subscripció al butlletí d'una botiga en línia. Valida l'adreça electrònica amb JavaScript, sense tornar a carregar la pàgina. El missatge d'error apareix al costat del botó, però el focus no s'hi mou.

Així no: Error escrit en un paràgraf sense regió activa

El missatge es veu en vermell, però s'escriu en un <p> normal. El lector de pantalla no anuncia res. La persona continua en el botó sense saber que l'enviament ha fallat. Per notar-ho, activeu NVDA o VoiceOver i envieu el formulari buit.

Captura de pantalla de l'exemple incorrecte: Error escrit en un paràgraf sense regió activa
Així es veu l'exemple incorrecte.

La demostració conté, a propòsit, l'error d'accessibilitat que s'explica.

Mostra el codi de l'exemple incorrecte
<form id="boletin" action="#" novalidate>
  <label for="correo">Correu electrònic</label>
  <input type="email" id="correo" autocomplete="email">
  <button>Subscriu-me</button>
  <p id="error" class="error"></p>
</form>
<style>.error { color: #b00020; font-weight: bold; }</style>
<script>
document.getElementById('boletin').addEventListener('submit', function (e) {
  e.preventDefault();
  var campo = document.getElementById('correo');
  var valido = campo.value && campo.validity.valid;
  document.getElementById('error').textContent = valido ? '' :
    'Error: escriviu una adreça electrònica vàlida, per exemple nom@domini.cat.';
});
</script>

Així sí: Contenidor amb role="alert" present des de la càrrega

El mateix paràgraf porta role="alert" i aria-atomic="true" des que es carrega la pàgina. Així, el text que s'hi escriu s'anuncia de seguida. En cada enviament es buida el contenidor i es torna a escriure el missatge. D'aquesta manera també s'anuncia si l'error es repeteix.

Proveu-ho aquí:

Mostra el codi de l'exemple correcte
<form id="boletin" action="#" novalidate>
  <label for="correo">Correu electrònic</label>
  <input type="email" id="correo" autocomplete="email">
  <button>Subscriu-me</button>
  <p id="error" class="error" role="alert" aria-atomic="true"></p>
</form>
<style>.error { color: #b00020; font-weight: bold; }</style>
<script>
document.getElementById('boletin').addEventListener('submit', function (e) {
  e.preventDefault();
  var campo = document.getElementById('correo'), caja = document.getElementById('error');
  var valido = campo.value && campo.validity.valid;
  caja.textContent = '';
  if (!valido) setTimeout(function () {
    caja.textContent = 'Error: escriviu una adreça electrònica vàlida, per exemple nom@domini.cat.';
  }, 100);
});
</script>

Com comprovar-ho

Lector de pantalla (NVDA o VoiceOver)

  1. Amb el camp buit, situar el focus en el botó «Subscriu-me» i prémer Retorn.
  2. Comprovar que el missatge d'error s'anuncia sense que el focus es mogui.
  3. Tornar a prémer Retorn i verificar que el missatge es torna a anunciar.

Hauria d'anunciar: «Error: escriviu una adreça electrònica vàlida, per exemple nom@domini.cat.»

Eines del navegador

  1. Obrir les eines de desenvolupament (F12) a la pestanya Elements.
  2. Comprovar que el contenidor buit amb role="alert" (o aria-live="assertive") ja existeix abans de provocar l'error.
  3. A la pestanya Accessibilitat, verificar que el contenidor té la funció «alert».
  4. Comprovar que el missatge s'escriu dins d'aquest contenidor, no en un element nou.

Teclat

  1. Enviar el formulari només amb el teclat. El missatge s'ha de veure al costat del botó i el focus no ha de saltar a cap altre lloc.

Validació automàtica

  1. axe DevTools, WAVE i Lighthouse no comproven si un missatge que apareix després s'anuncia. No detecten la falta de regió activa.
  2. Només assenyalen atributs ARIA mal escrits o amb valors no vàlids (regles aria-valid-attr i aria-valid-attr-value d'axe). L'anunci s'ha de comprovar amb un lector de pantalla.

Errors freqüents en auditories

  • Crear el contenidor amb role="alert" en el mateix moment de l'error. Molts lectors de pantalla no l'anuncien.
  • Escriure el mateix missatge que ja hi havia sense buidar abans el contenidor. El segon error no s'anuncia.
  • Posar role="alert" en tot el formulari o en un contenidor gran. Es llegeix sencer cada vegada que alguna cosa canvia.
  • Utilitzar role="alert" en missatges informatius o d'èxit. No són urgents i han d'anar en role="status".
Veure el text complet del W3C (traducció al català)

Aquesta és una traducció no oficial al català de la tècnica ARIA19 de Techniques for WCAG 2.2, del W3C. Pot contenir errors. L'únic document oficial i normatiu és la versió original en anglès, publicada al lloc web del W3C.

Aplicabilitat

Tecnologies que admeten Accessible Rich Internet Applications (WAI-ARIA).

Descripció

El propòsit d'aquesta tècnica és notificar a les tecnologies de suport quan es produeix un error d'entrada. L'atribut aria-live fa possible que una tecnologia de suport (com ara un lector de pantalla) rebi una notificació quan s'injecten missatges d'error en un contenidor de regió activa (live region). El contingut de la regió aria-live el llegeix automàticament la tecnologia de suport, sense que aquesta hagi de situar el focus en el lloc on es mostra el text.

També hi ha diverses funcions (rols) de regió activa per a casos especials que es poden utilitzar en lloc d'aplicar directament les propietats de regió activa.

Exemples

Injectar missatges d'error en un contenidor amb role=alert ja present al DOM

L'exemple següent utilitza role=alert, que equival a utilitzar aria-live=assertive.

En l'exemple hi ha un element contenidor de missatges d'error buit amb aria-atomic=true i una propietat aria-live o una funció alert, present al DOM en carregar la pàgina. El contenidor d'errors ha de ser present al DOM en carregar la pàgina perquè la majoria dels lectors de pantalla llegeixin el missatge d'error. aria-atomic=true és necessari perquè VoiceOver a iOS llegeixi els missatges d'error després de més d'un enviament no vàlid.

S'utilitza JavaScript per comprovar si els camps d'entrada són buits en enviar el formulari i, en aquest cas, injectar els missatges d'error en els contenidors de regió activa. Cada vegada que s'intenta un enviament nou, els missatges d'error anteriors s'eliminen del contenidor i s'injecten els nous.

// Get the form element
const form = document.getElementById('signup');
// Listen for when the form is submitted
form.addEventListener('submit', function(event) {
// Stop the form from actually submitting (so we can check it first)
event.preventDefault();
// Get references to the input fields
const firstNameInput = document.getElementById('first');
const lastNameInput = document.getElementById('last');
const emailInput = document.getElementById('email');
// Get the element where we'll show error messages
const errorsContainer = document.getElementById('errors');
// Create an empty array to collect error messages
const errorMessages = [];
// Check if first name is empty
if (firstNameInput.value === '') {
  errorMessages.push('<li>Please enter your first name.</li>');
}
// Check if last name is empty
if (lastNameInput.value === '') {
  errorMessages.push('<li>Please enter your last name.</li>');
}
// Check if email is empty
if (emailInput.value === '') {
  errorMessages.push('<li>Please enter your email address.</li>');
}
// Clear the errors container first
// (This helps screen readers notice when new content appears)
errorsContainer.innerHTML = '';
// Wait 500 milliseconds, then show the errors
setTimeout(function() {
  // If there are any errors, wrap them in a list and display them
  if (errorMessages.length > 0) {
    errorsContainer.innerHTML = '<ul>' + errorMessages.join('') + '</ul>';
  }
}, 500);
});
<form name="signup" id="signup">
  <p id="errors" role="alert" aria-atomic="true"></p>
  <div>
    <label for="first">First Name (required)</label>
    <input autocomplete="given-name" type="text" name="first" id="first">
  </div>
  <div>
    <label for="last">Last Name (required)</label>
    <input autocomplete="family-name" type="text" name="last" id="last">
  </div>
  <div>
    <label for="email">Email (required)</label>
    <input autocomplete="email" type="text" name="email" id="email">
  </div>
  <div>
    <input type="submit" name="button" id="button" value="Submit">
  </div>
 </form>

Exemple funcional: Utilitzar role=alert per identificar errors.

Proves

Procediment

  1. Determinar que en carregar la pàgina hi ha present al DOM (Document Object Model) un contenidor d'errors buit amb l'atribut role=alert o aria-live=assertive.
  2. Provocar l'error que fa que el contingut de la regió activa aparegui o s'actualitzi.
  3. Determinar que el missatge d'error s'ha injectat en el contenidor d'errors ja present.

Resultats esperats

  • Les comprovacions núm. 1 i núm. 3 són certes.

Recursos

Com ho comprovem a ADDAW

En cada auditoria d'ADDAW revisem aquesta tècnica pàgina per pàgina i us lliurem els errors amb captures i la manera de corregir-los.

Sol·licitar una auditoria

Basat en la tècnica ARIA19 del W3C (WCAG 2.2). Explicació i exemples: ADDAW. Traducció no oficial del text del W3C © W3C, llicència de documents del W3C. Heu vist un error? Escriviu-nos.