EVOLUTION-MANAGER
Edit File: accessibility.html
<a href='https://github.com/angular/angular.js/edit/v1.3.x/docs/content/guide/accessibility.ngdoc?message=docs(guide%2FAccessibility)%3A%20describe%20your%20change...' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit"> </i>Improve this Doc</a> <h1 id="accessibility-with-ngaria">Accessibility with ngAria</h1> <p>The goal of ngAria is to improve Angular's default accessibility by enabling common <a href="http://www.w3.org/TR/wai-aria/">ARIA</a> attributes that convey state or semantic information for assistive technologies used by persons with disabilities.</p> <h2 id="including-ngaria">Including ngAria</h2> <p>Using <a href="api/ngAria">ngAria</a> is as simple as requiring the ngAria module in your application. ngAria hooks into standard AngularJS directives and quietly injects accessibility support into your application at runtime.</p> <pre><code class="lang-js">angular.module('myApp', ['ngAria'])... </code></pre> <h3 id="using-ngaria">Using ngAria</h3> <p>Most of what ngAria does is only visible "under the hood". To see the module in action, once you've added it as a dependency, you can test a few things:</p> <ul> <li>Using your favorite element inspector, look for ngAria attributes in your own code.</li> <li>Test using your keyboard to ensure <code>tabindex</code> is used correctly.</li> <li>Fire up a screen reader such as VoiceOver to listen for ARIA support. <a href="http://webaim.org/articles/screenreader_testing/">Helpful screen reader tips.</a></li> </ul> <h2 id="supported-directives">Supported directives</h2> <p>Currently, ngAria interfaces with the following directives:</p> <ul> <li><a href="guide/accessibility#ngmodel">ngModel</a></li> <li><a href="guide/accessibility#ngdisabled">ngDisabled</a></li> <li><a href="guide/accessibility#ngshow">ngShow</a></li> <li><a href="guide/accessibility#nghide">ngHide</a></li> <li><a href="guide/accessibility#ngclick">ngClick</a></li> <li><a href="guide/accessibility#ngdblclick">ngDblClick</a></li> </ul> <h2 id="ngmodel">ngModel</h2> <p>Most of ngAria's heavy lifting happens in the <a href="api/ng/directive/ngModel">ngModel</a> directive. For elements using ngModel, special attention is paid by ngAria if that element also has a a role or type of <code>checkbox</code>, <code>radio</code>, <code>range</code> or <code>textbox</code>.</p> <p>For those elements using ngModel, ngAria will dynamically bind and update the following ARIA attributes (if they have not been explicitly specified by the developer):</p> <ul> <li>aria-checked</li> <li>aria-valuemin</li> <li>aria-valuemax</li> <li>aria-valuenow</li> <li>aria-invalid</li> <li>aria-required</li> </ul> <h3 id="example">Example</h3> <p> <div> <a ng-click="openPlunkr('examples/example-example1')" class="btn pull-right"> <i class="glyphicon glyphicon-edit"> </i> Edit in Plunker</a> <div class="runnable-example" path="examples/example-example1" module="ngAria_ngModelExample" deps="angular-aria.js"> <div class="runnable-example-file" name="index.html" language="html" type="html"> <pre><code> <style> [role=checkbox] { cursor: pointer; display: inline-block; } [role=checkbox] .icon:before { content: '\2610'; display: inline-block; font-size: 2em; line-height: 1; vertical-align: middle; speak: none; } [role=checkbox].active .icon:before { content: '\2611'; } pre { white-space: pre-wrap; } </style> <div> <form ng-controller="formsController"> <some-checkbox role="checkbox" ng-model="checked" ng-class="{active: checked}" ng-disabled="isDisabled" ng-click="toggleCheckbox()" aria-label="Custom Checkbox" show-attrs> <span class="icon" aria-hidden="true"></span> Custom Checkbox </some-checkbox> </form> </div> <script> var app = angular.module('ngAria_ngModelExample', ['ngAria']) .controller('formsController', function($scope){ $scope.checked = false; $scope.toggleCheckbox = function(){ $scope.checked = !$scope.checked; } }) .directive('someCheckbox', function(){ return { restrict: 'E', link: function($scope, $el, $attrs) { $el.on('keypress', function(event){ event.preventDefault(); if(event.keyCode === 32 || event.keyCode === 13){ $scope.toggleCheckbox(); $scope.$apply(); } }); } } }) .directive('showAttrs', function() { return function($scope, $el, $attrs) { var pre = document.createElement('pre'); $el.after(pre); $scope.$watch(function() { var $attrs = {}; Array.prototype.slice.call($el[0].attributes, 0).forEach(function(item) { if (item.name !== 'show-$attrs') { $attrs[item.name] = item.value; } }); return $attrs; }, function(newAttrs, oldAttrs) { pre.textContent = JSON.stringify(newAttrs, null, 2); }, true); } }); </script></code></pre> </div> <iframe class="runnable-example-frame" src="examples/example-example1/index.html" name="example-example1"></iframe> </div> </div> </p> <p>ngAria will also add <code>tabIndex</code>, ensuring custom elements with these roles will be reachable from the keyboard. It is still up to <strong>you</strong> as a developer to <strong>ensure custom controls will be operable</strong> from the keybard. Think of <code>ng-click</code> on a <code><div></code> or <code><md-checkbox></code>: you still need to bind <code>ng-keypress</code> to make it fully operable from the keyboard. As a rule, any time you create a widget involving user interaction, be sure to test it with your keyboard and at least one mobile and desktop screen reader (preferably more).</p> <h2 id="ngdisabled">ngDisabled</h2> <p>The <code>disabled</code> attribute is only valid for certain elements such as <code>button</code>, <code>input</code> and <code>textarea</code>. To properly disable custom element directives such as <code><md-checkbox></code> or <code><taco-tab></code>, using ngAria with <a href="https://docs.angularjs.org/api/ng/directive/ngDisabled">ngDisabled</a> will also add <code>aria-disabled</code>. This tells assistive technologies when a non-native input is disabled, helping custom controls to be more accessible.</p> <h3 id="example">Example</h3> <pre><code class="lang-html"><md-checkbox ng-disabled="disabled"> </code></pre> <p>Becomes:</p> <pre><code class="lang-html"><md-checkbox disabled aria-disabled="true"> </code></pre> <blockquote> <p>You can check whether a control is legitimately disabled for a screen reader by visiting <a href="chrome://accessibility">chrome://accessibility</a>.</p> </blockquote> <h2 id="ngshow">ngShow</h2> <blockquote> <p>The <a href="https://docs.angularjs.org/api/ng/directive/ngShow">ngShow</a> directive shows or hides the given HTML element based on the expression provided to the <code>ngShow</code> attribute. The element is shown or hidden by removing or adding the <code>.ng-hide</code> CSS class onto the element.</p> </blockquote> <p>In its default setup, ngAria for <code>ngShow</code> is actually redundant. It toggles <code>aria-hidden</code> on the directive when it is hidden or shown. However, the default CSS of <code>display: none !important</code>, already hides child elements from a screen reader. It becomes more useful when the default CSS is overridden with properties that don’t affect assistive technologies, such as <code>opacity</code> or <code>transform</code>. By toggling <code>aria-hidden</code> dynamically with ngAria, we can ensure content visually hidden with this technique will not be read aloud in a screen reader.</p> <p>One caveat with this combination of CSS and <code>aria-hidden</code>: you must also remove links and other interactive child elements from the tab order using <code>tabIndex=“-1”</code> on each control. This ensures screen reader users won't accidentally focus on "mystery elements". Managing tab index on every child control can be complex and affect performance, so it’s best to just stick with the default <code>display: none</code> CSS. See the <a href="http://www.w3.org/TR/aria-in-html/#fourth-rule-of-aria-use">fourth rule of ARIA use</a>.</p> <h3 id="example">Example</h3> <pre><code class="lang-css">.ng-hide { display: block; opacity: 0; } </code></pre> <pre><code class="lang-html"><div ng-show="false" class="ng-hide" aria-hidden="true"></div> </code></pre> <p>Becomes:</p> <pre><code class="lang-html"><div ng-show="true" aria-hidden="false"></div> </code></pre> <p><em>Note: Child links, buttons or other interactive controls must also be removed from the tab order.</em></p> <h2 id="nghide">ngHide</h2> <blockquote> <p>The <a href="https://docs.angularjs.org/api/ng/directive/ngHide">ngHide</a> directive shows or hides the given HTML element based on the expression provided to the <code>ngHide</code> attribute. The element is shown or hidden by removing or adding the <code>.ng-hide</code> CSS class onto the element.</p> </blockquote> <p>The default CSS for <code>ngHide</code>, the inverse method to <code>ngShow</code>, makes ngAria redundant. It toggles <code>aria-hidden</code> on the directive when it is hidden or shown, but the content is already hidden with <code>display: none</code>. See explanation for <a href="guide/accessibility#ngshow">ngShow</a> when overriding the default CSS.</p> <h2><span id="ngclick">ngClick</span> and <span id="ngdblclick">ngDblclick</span></h2> If <code>ng-click</code> or <code>ng-dblclick</code> is encountered, ngAria will add <code>tabindex</code> if it isn't there already. Even with this, you must currently still add <code>ng-keypress</code> to non-interactive elements such as <code>div</code> or <code>taco-button</code> to enable keyboard access. Conversation is currently ongoing about whether ngAria should also bind <code>ng-keypress</code>. <h3>Example</h3> <code>html <div ng-click="toggleMenu()"></div></code> Becomes: <code>html <div ng-click="toggleMenu()" tabindex="0"></div></code> <em>Note: ngAria still requires <code>ng-keypress</code> to be added manually to non-native controls like divs.</em> <h2 id="ngmessages">ngMessages</h2> <p>The new ngMessages module makes it easy to display form validation or other messages with priority sequencing and animation. To expose these visual messages to screen readers, ngAria injects <code>aria-live="polite"</code>, causing them to be read aloud any time a message is shown, regardless of the user's focus location.</p> <h3 id="example">Example</h3> <pre><code class="lang-html"><div ng-messages="myForm.myName.$error"> <div ng-message="required">You did not enter a field</div> <div ng-message="maxlength">Your field is too long</div> </div> </code></pre> <p>Becomes:</p> <pre><code class="lang-html"><div ng-messages="myForm.myName.$error" aria-live="polite"> <div ng-message="required">You did not enter a field</div> <div ng-message="maxlength">Your field is too long</div> </div> </code></pre> <h2 id="disabling-attributes">Disabling attributes</h2> <p>The attribute magic of ngAria may not work for every scenario. To disable individual attributes, you can use the <a href="api/ngAria/provider/$ariaProvider#config">config</a> method. Just keep in mind this will tell ngAria to ignore the attribute globally.</p> <p> <div> <a ng-click="openPlunkr('examples/example-example2')" class="btn pull-right"> <i class="glyphicon glyphicon-edit"> </i> Edit in Plunker</a> <div class="runnable-example" path="examples/example-example2" module="ngAria_ngDisabledExample" deps="angular-aria.js"> <div class="runnable-example-file" name="index.html" language="html" type="html"> <pre><code> <style> [role=checkbox] { cursor: pointer; display: inline-block; } [role=checkbox] .icon:before { content: '\2610'; display: inline-block; font-size: 2em; line-height: 1; vertical-align: middle; speak: none; } [role=checkbox].active .icon:before { content: '\2611'; } </style> <form ng-controller="formsController"> <div ng-model="someModel" show-attrs> Div with ngModel and aria-invalid disabled </div> <div role="checkbox" ng-model="checked" ng-class="{active: checked}" aria-label="Custom Checkbox" ng-click="toggleCheckbox()" some-checkbox show-attrs> <span class="icon" aria-hidden="true"></span> Custom Checkbox for comparison </div> </form> <script> angular.module('ngAria_ngDisabledExample', ['ngAria'], function config($ariaProvider) { $ariaProvider.config({ ariaInvalid: false, tabindex: true }); }) .controller('formsController', function($scope){ $scope.checked = false; $scope.toggleCheckbox = function(){ $scope.checked = !$scope.checked; } }) .directive('someCheckbox', function(){ return { restrict: 'A', link: function($scope, $el, $attrs) { $el.on('keypress', function(event){ event.preventDefault(); if(event.keyCode === 32 || event.keyCode === 13){ $scope.toggleCheckbox(); $scope.$apply(); } }); } } }) .directive('showAttrs', function() { return function(scope, el, attrs) { var pre = document.createElement('pre'); el.after(pre); scope.$watch(function() { var attrs = {}; Array.prototype.slice.call(el[0].attributes, 0).forEach(function(item) { if (item.name !== 'show-attrs') { attrs[item.name] = item.value; } }); return attrs; }, function(newAttrs, oldAttrs) { pre.textContent = JSON.stringify(newAttrs, null, 2); }, true); } }); </script></code></pre> </div> <iframe class="runnable-example-frame" src="examples/example-example2/index.html" name="example-example2"></iframe> </div> </div> </p> <h2 id="common-accessibility-patterns">Common Accessibility Patterns</h2> <p>Accessibility best practices that apply to web apps in general also apply to Angular.</p> <ul> <li><strong>Text alternatives</strong>: Add alternate text content to make visual information accessible using <a href="http://www.w3.org/TR/html-alt-techniques/">these W3C guidelines</a>. The appropriate technique depends on the specific markup but can be accomplished using offscreen spans, <code>aria-label</code> or label elements, image <code>alt</code> attributes, <code>figure</code>/<code>figcaption</code> elements and more.</li> <li><strong>HTML Semantics</strong>: If you're creating custom element directives, Web Components or HTML in general, use native elements wherever possible to utilize built-in events and properties. Alternatively, use ARIA to communicate semantic meaning. See <a href="http://www.w3.org/TR/aria-in-html/#notes-on-aria-use-in-html">notes on ARIA use</a>.</li> <li><strong>Focus management</strong>: Guide the user around the app as views are appended/removed. Focus should <em>never</em> be lost, as this causes unexpected behavior and much confusion (referred to as "freak-out mode").</li> <li><strong>Announcing changes</strong>: When filtering or other UI messaging happens away from the user's focus, notify with <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions">ARIA Live Regions</a>.</li> <li><strong>Color contrast and scale</strong>: Make sure content is legible and interactive controls are usable at all screen sizes. Consider configurable UI themes for people with color blindness, low vision or other visual impairments.</li> <li><strong>Progressive enhancement</strong>: Some users do not browse with JavaScript enabled or do not have the latest browser. An accessible message about site requirements can inform users and improve the experience.</li> </ul> <h2 id="additional-resources">Additional Resources</h2> <ul> <li><a href="http://www.w3.org/TR/aria-in-html/">Using ARIA in HTML</a></li> <li><a href="https://www.youtube.com/watch?v=dmYDggEgU-s&list=UUEGUP3TJJfMsEM_1y8iviSQ">AngularJS Accessibility at ngEurope</a></li> <li><a href="http://webaim.org/articles/screenreader_testing/">Testing with Screen Readers</a></li> <li><a href="https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb?hl=en">Chrome Accessibility Developer Tools</a></li> <li><a href="http://www.w3.org/wiki/Accessibility_testing">W3C Accessibility Testing</a></li> <li><a href="http://webaim.org">WebAIM</a></li> <li><a href="http://a11yproject.com">A11y Project</a></li> </ul>