Nativescript plugin for enabling accessibility features

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.

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

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

CSS-property: a11y-enabled = true / false

Set the accessibility label on the element, this will be read by the screen reader in-place 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, DO NOT use automationText at the same time.

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.

Describes the result of performing an action on the view.

Should only be provided if the result isn't obvious from the label.

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 this plugin, DO NOT use automationText at the same time.

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

Defaults to false.

CSS-property: a11y-hidden = true / false

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.

CSS-property: a11y-role = value

Set the state of the element. Should be used with accessibilityRole.

CSS-property: a11y-state = value

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

Note for iOS:

polite and assertive is treated as accessibilityTraits.frequentUpdates

CSS-property: a11y-live-region = value

Make an announcement to the screen reader.

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

The number indicated pct font scale:

• a11y-fontscale-50 (iOS only - extra small font size)

• a11y-fontscale-70 (iOS only - extra small font size)

• a11y-fontscale-85

• a11y-fontscale-100

• a11y-fontscale-115

• a11y-fontscale-130

• a11y-fontscale-150 (iOS only)

• a11y-fontscale-200 (iOS only - extra large font size)

• a11y-fontscale-250 (iOS only - extra large font size)

• a11y-fontscale-300 (iOS only - extra large font size)

• a11y-fontscale-350 (iOS only - extra large font size)

• a11y-fontscale-400 (iOS only - extra large font size)

• a11y-fontscale-xs (iOS only - for extra small font size e.g < 85%)

• a11y-fontscale-xs-visible (iOS only - visible only when font size is extra small)

• a11y-fontscale-xs-hidden (iOS only - hidden when font size is extra small)

• a11y-fontscale-m (Medium font size >=85% and <=150%)

• a11y-fontscale-m-visible (visible only when font size is medium)

• a11y-fontscale-m-hidden (hidden when font size is medium)

• a11y-fontscale-xl (iOS only - for extra large font size e.g >150%)

• a11y-fontscale-xl-visible (iOS only - visible only when font size is extra large)

• a11y-fontscale-xl-hidden (iOS only - hidden when font size is visible large)

• a11y-service-enabled (is VoiceOver/TalkBack enabled)

• a11y-service-enabled-visible (only visible when the a11y service is enabled)

• a11y-service-enabled-hidden (hidden when the a11y service is enabled)

• a11y-service-disabled (is VoiceOver/TalkBack disabled)

• a11y-service-disabled-visible (only visible when the a11y service is disabled)

• a11y-service-disabled-hidden (hidden when the a11y service is disabled)

Note:

Android auto scales font Label out of the box. But iOS does not.

To enabled for iOS please use nativescript-theme-core@^2.0.19 with our extensions from this plugin.

To use it all you need to do is add this to your app.scss / app.css:

@import '~@nativescript/theme/core.compat';
@import '~@nativescript/theme/scss/index';
@import url('~@nota/nativescript-accessibility-ext/a11y.css'); // <-- add this line

For compat mode:

@import '~@nativescript/theme/core.compat';
@import '~@nativescript/theme/scss/index';
@import url('~@nota/nativescript-accessibility-ext/a11y.compat.css'); // <-- add this line

For more see FontScale.md.

Reading https://nshipster.com/uiaccessibility/ is recommended.

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

Post an accessibility notification to iOS.

el.iosPostAccessibilityNotification(notificationType, arg);

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 preferredFonts. Note: Font Scale between 50% and 400%. 200% -> 400% are extra large accessibility font scaling

Change the increment/decrement step size for the swipe up / down gesture.

Default step size is 10

Trigger an accessibility event on Android

el.androidSendAccessibilityEvent(eventName, msg);

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

• onAccessibilityTap (iOS)
• onMagicTap (iOS)

Each built-in nativescript View-class is extended with global-events.

Note: This conflicts with nativescript-globalevents-plugin. If you for some reason need to load both modules, you need to import nativescript-globalevents before @nota/nativescript-accessibility-ext.

This event is added to every view-type.

View.on(View.loadedEvent, (evt) => {
  const view = evt.object;
  // Do stuff.
});

This event is aded to all Labels

Label.on(View.loadedEvent, (evt) => {
  const label = evt.object;
  // Do stuff.
});

Remove all global loaded events from the View-class.

View.off(View.loadedEvent);

Remove a single global loaded event from the View-class.

View.off(View.loadedEvent, callbackReference);

NativeScript Observable for getting the native fontScale on either platform.

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

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

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

We support Android 19 and up, but the compileSdkVersion needs to be at least 29.

Edit your App_Resources/Android/app.gradle:

android {
  defaultConfig {
    minSdkVersion = 19 // <-- change this line
    compileSdkVersion = 29 // <-- change this line, if it exists.
    generatedDensities = []
  }
  aaptOptions {
    additionalParameters "--no-version-vectors"
  }
}

Change to your app.ts/app.js

import * as app from 'tns-core-modules/application';
import '@nota/nativescript-accessibility-ext'; /// <-- Add this line

app.run({ moduleName: 'app-root' });

Change to your app.module.ts

import { NgModule, NO_ERRORS_SCHEMA } from "@angular/core";
import { NativeScriptModule } from "nativescript-angular/nativescript.module";
import { NotaAccessibilityExtModule } '@nota/nativescript-accessibility-ext/angular'; /// <-- Add this line

/// ... stuff

@NgModule({
    bootstrap: [
        AppComponent
    ],
    imports: [
        NativeScriptModule,
        AppRoutingModule,
        NotaAccessibilityExtModule, /// <-- Add this line
    ],
    declarations: [
        AppComponent,
        ItemsComponent,
        ItemDetailComponent
    ],
    providers: [],
    schemas: [
        NO_ERRORS_SCHEMA
    ]
})
export class AppModule { }

For more see Angular.

Change to your app.js:

import Vue from "nativescript-vue";
import '@nota/nativescript-accessibility-ext'; /// <-- Add this line

....

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>

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.