AriaLiveAnnouncer¶

Overview¶

A static object used to send aria-live updates to a screen reader. These are alerts that are independent of user focus. This will create and reference 'aria-live' elements in the HTML document and update their content. You will need to get these elements and add them to the document through a reference to this.ariaLiveElements. A number of elements such as the following are created and used:

<p id="elements-1-polite-1" aria-live="polite"></p> <p id="elements-1-polite-2" aria-live="polite"></p> <p id="elements-1-polite-3" aria-live="polite"></p> <p id="elements-1-polite-4" aria-live="polite"></p>

<p id="elements-1-assertive-1" aria-live="assertive"></p> <p id="elements-1-assertive-2" aria-live="assertive"></p> <p id="elements-1-assertive-3" aria-live="assertive"></p> <p id="elements-1-assertive-4" aria-live="assertive"></p>

It was discovered that cycling through using these elements prevented a VoiceOver bug where alerts would interrupt each other. Starting from the first element, content is set on each element in order and cycles through.

Many aria-live and related attributes were tested, but none were well supported or particularly useful for PhET sims, see https://github.com/phetsims/chipper/issues/472.

@author Jesse Greenberg @author John Blanco

Class AriaLiveAnnouncer¶

import { AriaLiveAnnouncer } from 'scenerystack/utterance-queue';

Constructor¶

new AriaLiveAnnouncer( providedOptions? : AriaLiveAnnouncerOptions )¶

Instance Methods¶

announce( announceText : ResolvedResponse, utterance : Utterance, providedOptions? : AriaLiveAnnouncerAnnounceOptions )¶

Announce an alert, setting textContent to an aria-live element.

cancel()¶

The implementation of cancel for AriaLiveAnnouncer. We do not know whether the AT is speaking content so this function is a no-op for aria-live.

cancelUtterance( utterance : Utterance )¶

The implementation of cancelUtterance for AriaLiveAnnouncer. We do not know whether the AT is speaking content so this function is a no-op for aria-live.

Instance Properties¶

ariaLiveContainer : HTMLDivElement¶

(readonly)

Static Properties¶

ARIA_LIVE_DELAY¶

(readonly)

The Announcer only speaks one Utterance per this interval or else VoiceOver reads alerts out of order. This is also the interval at which alert content is cleared from the DOM once set so that it cannot be found with the virtual cursor after setting.

AriaLive¶

(readonly)

Possible values for the aria-live attribute (priority) that can be alerted (like "polite" and "assertive"), see AriaLiveAnnounceOptions for details.

Class AriaLive¶

Possible supported values for the aria-live attributes created in AriaLiveAnnouncer.

import { AriaLive } from 'scenerystack/utterance-queue';

Constructor¶

new AriaLive( attributeString : string )¶

Instance Methods¶

Static Properties¶

POLITE : AriaLive¶

(readonly)

ASSERTIVE : AriaLive¶

(readonly)

enumeration : Enumeration¶

(readonly)

Type AriaLiveAnnouncerOptions¶

import type { AriaLiveAnnouncerOptions } from 'scenerystack/utterance-queue';

• lang?: string
  The language for your content. Changing this will impact the speech engine of a screen reader.
• & AnnouncerOptions

Source Code¶

See the source for AriaLiveAnnouncer.ts in the utterance-queue repository.