@nota/nativescript-accessibility-ext NPM

@nota/nativescript-accessibility-ext

Nativescript plugin for enabling accessibility features

Reasoning behind this plugin:

NativeScript is a framework for developing cross-platform mobile applications.

NativeScript's support for platform specific accessibility features is very limited, as it only implements those that can be abstracted for both platforms. So you have to enable these features in JavaScript-code rather than in the template.

The goal of this plugin is to expose all platform-specific accessibility features for both Android and iOS through component properties.

It's heavily inspired by React-Native's accessibility API: https://facebook.github.io/react-native/docs/accessibility.html

But is written from scratch, extending NativeScript's classes.

API:

Extends tns-core-modules/ui/core/view with these attributes and functions.

Attributes and functions for both `iOS` and `Android`

Attribute: View.accessible (iOS, Android)

If true the element is an accessibility element and all the children will be treated as a single selectable component.

Function: View.accessibilityAnnouncement(msg?: string) (iOS, Android)

Make an announcement to the screen reader.

msg	Description
annnouncement text	The text that will be read by the screen reader
null	The elements automationText of the element will be read by the screen reader instead

Attribute: View.accessibilityLabel (iOS, Android)

Set the accessibility label on the element, this will be read by the screen reader inplace in any 'text' value the element has. Important note: NativeScript provides the property automationText, this sets both accessibilityLabel AND accessibilityIdentifier on iOS which can break automated tests. If you use accessibilityLabel from this plugin, don't use automationText at the same time.

CSSClasse: Page.a11y-fontscale (iOS, Android)

If you need to apply different styling when fonts are scaled, these css-classes are available on the Page.

The number indicated pct font scale:

a11y-fontscale-50 (iOS only)
a11y-fontscale-70 (iOS only)
a11y-fontscale-85
a11y-fontscale-100
a11y-fontscale-115
a11y-fontscale-130
a11y-fontscale-150 (iOS only)
a11y-fontscale-200 (iOS only - extra large fonts)
a11y-fontscale-250 (iOS only - extra large fonts)
a11y-fontscale-300 (iOS only - extra large fonts)
a11y-fontscale-350 (iOS only - extra large fonts)
a11y-fontscale-400 (iOS only - extra large fonts)

If you want auto scaling on iOS Labels see: Label.accessibilityAdjustsFontSize

Attributes and functions for `iOS`-only

Attribute: View.accessibilityTraits (iOS)

Set one or more traits that best fits the elemnet. Comma or space separated list of traits.

key	Description
none	Used when the element has no traits.
button	Used when the element should be treated as a button.
link	Used when the element should be treated as a link.
header	Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
search	Used when the text field element should also be treated as a search field.
image	Used when the element should be treated as an image. Can be combined with button or link, for example.
selected	Used when the element is selected. For example, a selected row in a table or a selected button within a segmented control.
plays	Used when the element plays its own sound when activated.
key	Used when the element acts as a keyboard key.
text	Used when the element should be treated as static text that cannot change.
summary	Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches. For example, when Weather first launches, the element with today\'s weather conditions is marked with this trait.
disabled	Used when the control is not enabled and does not respond to user input. (You should also set `isEnabled="false"` on the element)
frequentUpdates	Used when the element frequently updates its label or value, but too often to send notifications. Allows an accessibility client to poll for changes. A stopwatch would be an example.
startsMedia	Used when activating an element starts a media session (e.g. playing a movie, recording audio) that should not be interrupted by output from an assistive technology, like VoiceOver.
adjustable	Used when an element can be "adjusted" (e.g. a slider).
allowsDirectInteraction	Used when an element allows direct touch interaction for VoiceOver users (for example, a view representing a piano keyboard).
pageTurn	Informs VoiceOver that it should scroll to the next page when it finishes reading the contents of the element.

Attribute: View.accessibilityValue (iOS)

Define the value of an accessibility element.

This is to give the user more information about the value of a field. For instance a Slider would normally have a value between 0-100%, but if the Slider represents time, you can give the user better information about the value.

Attribute: View.accessibilityIdentifier (iOS)

Set the elements unique accessibilityIdentifier. Important note: NativeScript provides the property automationText, this sets both accessibilityLabel AND accessibilityIdentifier on iOS which can break automated tests. If you use accessibilityIdentifier from this plugin, don't use automationText at the same time.

Attribute: View.accessibilityElementsHidden (iOS)

Indicating whether the accessibility elements contained within this accessibility element are hidden.

Defaults to false.

Attribute: Label.accessibilityAdjustsFontSize (iOS)

Scales the font on a Label on iOS according to the settings in Settings -> General -> Accessibility -> Larger text On Android this is handled automatically, on iOS you have to specify it yourself. Note: It's similar to UILabel.adjustsFontForContentSizeCategory but affects all fonts not just the preferedFonts. Note: Font Scale between 50% and 400%. 200% -> 400% are extra large accessibility font scaling

Function: View.postAccessibilityNotification(notificationType: string, arg?: string | null) (iOS)

Post an accessibility notification to iOS.

  el.postAccessibilityNotification(notificationType, arg);

notificationType	Description
screen	Notify iOS that the sceen have changed
layout	Notify iOS that the layout have changed
announcement	Make an announcement to the scren reader (Please use: view.accessibilityAnnouncement(msg) for both platforms)

arg	Description
text	notificationType = 'announcement': Annoucement text to be read
null	notificationType = 'layout': do nothing. notificationType = 'screen': auto selects, the first accessible element within this element will be given accessibility focus

Attributes and functions for `Android`-only

Attribute: View.accessibilityComponentType (Android)

Defines the type of accessibility element, for example if something is a button. This isn't needed for Nativescript Buttons, but used to make other elements behave like buttons.

value	Description
button	Button element
radiobutton_checked	Checked radiobutton
radiobutton_unchecked	Unchecked radiobutton

Attribute: View.accessibilityLiveRegion (Android)

When components dynamically change, we want TalkBack to alert the end user.

value	Description
none	Accessibility services should not announce changes to this view.
polite	Accessibility services should announce changes to this view.
assertive	Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

Attribute: View.importantForAccessibility (Android)

key	Description
auto	(default)
yes	Is important
no	Is not important
no-hide-descendants	Force accessibility services to ignore the component and all of its children. For android < 19 treated as auto

Function: View.sendAccessibilityEvent(eventName: string, msg?: text) (Android)

Trigger an accessibility event on Android

  el.sendAccessibilityEvent(eventName, msg);

eventName	Description
invalid_position	Invalid selection/focus position
max_text_length	Maximum length of the text fields
view_clicked	Represents the event of clicking on a android.view.View like android.widget.Button, android.widget.CompoundButton, etc
view_long_clicked	Represents the event of long clicking on a android.view.View like android.widget.Button, android.widget.CompoundButton, etc
view_selected	Represents the event of selecting an item usually in the context of an android.widget.AdapterView
view_focused	Represents the event of setting input focus of a android.view.View
view_text_changed	Represents the event of changing the text of an android.widget.EditText
window_state_changed	Represents the event of opening a android.widget.PopupWindow, android.view.Menu, android.app.Dialog, etc
notification_state_changed	Represents the event showing a android.app.Notification
view_hover_enter	Represents the event of a hover enter over a android.view.View
view_hover_exit	Represents the event of a hover exit over a android.view.View
touch_exploration_gesture_start	Represents the event of starting a touch exploration gesture
touch_exploration_gesture_end	Represents the event of ending a touch exploration gesture
window_content_changed	Represents the event of changing the content of a window and more specifically the sub-tree rooted at the event's source
view_scrolled	Represents the event of scrolling a view
view_text_selection_changed	Represents the event of changing the selection in an android.widget.EditText
announcement	Represents the event of an application making an announcement
view_accessibility_focused	Represents the event of gaining accessibility focus
view_accessibility_focus_cleared	Represents the event of clearing accessibility focus
view_text_traversed_at_movement_granularity	Represents the event of traversing the text of a view at a given movement granularity
gesture_detection_start	Represents the event of beginning gesture detection.
gesture_detection_end	Represents the event of ending gesture detection
touch_interaction_start	Represents the event of the user starting to touch the screen
touch_interaction_end	Represents the event of the user ending to touch the screen
all	Mask for AccessibilityEvent all types

msg is an optional argument only used for announcement. If not provided with announcement the elements automationText value will be announced instead.

The following are not implemented (yet)

accessibilityLabel (NativeScript implements this as automationText. android maps to ContentDescription and iOS to both accessibilityLabel and acccesibilityIdentifier)
onAccessibilityTap (iOS)
onMagicTap (iOS)

Helpers:

FontScaleObservable

NativeScript Observable for getting the native fontScale on either platform. Note: For this to work properly on Android you need to add fontScale to the android:configChanges in your AndroidManifest.xml Note: Android: Font scale between 0.85 and 1.3 (85% -> 130%) iOS: Font scale between 50% and 400%. 200% -> 400% are extra large accessibility font

Using the plugin

To use the plugin in your nativescript-app, install and import the module:

npm i --save @nota/nativescript-accessibility-ext

Import in your app.ts/app.js, just after you import nativescript modules (NativeScriptModule if you run nativescript-angular)

import '@nota/nativescript-accessibility-ext';

Start adding the new properties to your templates:

<StackLayout
  accessible="true"
  automationText="This now a button"
  accessibilityComponentType="button"
  accessibilityTraits="button"
>
  <Label text="First button" (tap)="tapped($event)"></Label>
</StackLayout>

About Nota

Nota is the Danish Library and Expertise Center for people with print disabilities.

To become a member of Nota you must be able to document that you cannot read ordinary printed text. Members of Nota are visually impaired, dyslexic or otherwise impaired.

Our purpose is to ensure equal access to knowledge, community participation and experiences for people who're unable to read ordinary printed text.

NativeScript JavaScript Accessibility angular Android TalkBack VoiceOver iOS

@infinitebrahmanuniverse/nolb-_not @everything-registry/sub-chunk-666

2 years ago

4 years ago

4 years ago

4 years ago