5 lines
15 KiB
JSON
5 lines
15 KiB
JSON
{
|
|
"id": "guide/accessibility",
|
|
"title": "Accessibility in Angular",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/accessibility.md?message=docs%3A%20describe%20your%20change...\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n</div>\n\n\n<div class=\"content\">\n <h1 id=\"accessibility-in-angular\">Accessibility in Angular<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#accessibility-in-angular\"><i class=\"material-icons\">link</i></a></h1>\n<p>The web is used by a wide variety of people, including those who have visual or motor impairments.\nA variety of assistive technologies are available that make it much easier for these groups to\ninteract with web-based software applications.\nIn addition, designing an application to be more accessible generally improves the user experience for all users.</p>\n<p>For an in-depth introduction to issues and techniques for designing accessible applications, see the <a href=\"https://developers.google.com/web/fundamentals/accessibility/#what_is_accessibility\">Accessibility</a> section of the Google's <a href=\"https://developers.google.com/web/fundamentals/\">Web Fundamentals</a>.</p>\n<p>This page discusses best practices for designing Angular applications that\nwork well for all users, including those who rely on assistive technologies.</p>\n<div class=\"alert is-helpful\">\n<p> For the sample app that this page describes, see the <live-example></live-example>.</p>\n</div>\n<h2 id=\"accessibility-attributes\">Accessibility attributes<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#accessibility-attributes\"><i class=\"material-icons\">link</i></a></h2>\n<p>Building accessible web experience often involves setting <a href=\"https://developers.google.com/web/fundamentals/accessibility/semantics-aria\">ARIA attributes</a>\nto provide semantic meaning where it might otherwise be missing.\nUse <a href=\"guide/attribute-binding\">attribute binding</a> template syntax to control the values of accessibility-related attributes.</p>\n<p>When binding to ARIA attributes in Angular, you must use the <code>attr.</code> prefix, as the ARIA\nspecification depends specifically on HTML attributes rather than properties of DOM elements.</p>\n<code-example language=\"html\">\n<!-- Use attr. when binding to an ARIA attribute -->\n<button [attr.aria-label]=\"myActionLabel\">...</button>\n</code-example>\n<p>Note that this syntax is only necessary for attribute <em>bindings</em>.\nStatic ARIA attributes require no extra syntax.</p>\n<code-example language=\"html\">\n<!-- Static ARIA attributes require no extra syntax -->\n<button aria-label=\"Save document\">...</button>\n</code-example>\n<div class=\"alert is-helpful\">\n<p> By convention, HTML attributes use lowercase names (<code>tabindex</code>), while properties use camelCase names (<code>tabIndex</code>).</p>\n<p> See the <a href=\"guide/binding-syntax#html-attribute-vs-dom-property\">Binding syntax</a> guide for more background on the difference between attributes and properties.</p>\n</div>\n<h2 id=\"angular-ui-components\">Angular UI components<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#angular-ui-components\"><i class=\"material-icons\">link</i></a></h2>\n<p>The <a href=\"https://material.angular.io/\">Angular Material</a> library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible.\nThe <a href=\"https://material.angular.io/cdk/categories\">Component Development Kit (CDK)</a> includes the <code>a11y</code> package that provides tools to support various areas of accessibility.\nFor example:</p>\n<ul>\n<li>\n<p><code>LiveAnnouncer</code> is used to announce messages for screen-reader users using an <code>aria-live</code> region. See the W3C documentation for more information on <a href=\"https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live\">aria-live regions</a>.</p>\n</li>\n<li>\n<p>The <code>cdkTrapFocus</code> directive traps Tab-key focus within an element. Use it to create accessible experience for components like modal dialogs, where focus must be constrained.</p>\n</li>\n</ul>\n<p>For full details of these and other tools, see the <a href=\"https://material.angular.io/cdk/a11y/overview\">Angular CDK accessibility overview</a>.</p>\n<h3 id=\"augmenting-native-elements\">Augmenting native elements<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#augmenting-native-elements\"><i class=\"material-icons\">link</i></a></h3>\n<p>Native HTML elements capture a number of standard interaction patterns that are important to accessibility.\nWhen authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors.</p>\n<p>For example, instead of creating a custom element for a new variety of button, you can create a component that uses an attribute selector with a native <code><button></code> element.\nThis most commonly applies to <code><button></code> and <code><a></code>, but can be used with many other types of element.</p>\n<p>You can see examples of this pattern in Angular Material: <a href=\"https://github.com/angular/components/blob/50d3f29b6dc717b512dbd0234ce76f4ab7e9762a/src/material/button/button.ts#L67-L69\"><code>MatButton</code></a>, <a href=\"https://github.com/angular/components/blob/50d3f29b6dc717b512dbd0234ce76f4ab7e9762a/src/material/tabs/tab-nav-bar/tab-nav-bar.ts#L139\"><code>MatTabNav</code></a>, <a href=\"https://github.com/angular/components/blob/50d3f29b6dc717b512dbd0234ce76f4ab7e9762a/src/material/table/table.ts#L22\"><code>MatTable</code></a>.</p>\n<h3 id=\"using-containers-for-native-elements\">Using containers for native elements<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#using-containers-for-native-elements\"><i class=\"material-icons\">link</i></a></h3>\n<p>Sometimes using the appropriate native element requires a container element.\nFor example, the native <code><input></code> element cannot have children, so any custom text entry components need\nto wrap an <code><input></code> with additional elements.\nWhile you might just include the <code><input></code> in your custom component's template,\nthis makes it impossible for users of the component to set arbitrary properties and attributes to the input element.\nInstead, you can create a container component that uses content projection to include the native control in the\ncomponent's API.</p>\n<p>You can see <a href=\"https://material.angular.io/components/form-field/overview\"><code>MatFormField</code></a> as an example of this pattern.</p>\n<h2 id=\"case-study-building-a-custom-progress-bar\">Case study: Building a custom progress bar<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#case-study-building-a-custom-progress-bar\"><i class=\"material-icons\">link</i></a></h2>\n<p>The following example shows how to make a simple progress bar accessible by using host binding to control accessibility-related attributes.</p>\n<ul>\n<li>\n<p>The component defines an accessibility-enabled element with both the standard HTML attribute <code>role</code>, and ARIA attributes. The ARIA attribute <code>aria-valuenow</code> is bound to the user's input.</p>\n<p> <code-example path=\"accessibility/src/app/progress-bar.component.ts\" header=\"src/app/progress-bar.component.ts\" region=\"progressbar-component\">\nimport { <a href=\"api/core/Component\" class=\"code-anchor\">Component</a>, <a href=\"api/core/Input\" class=\"code-anchor\">Input</a> } from '@angular/core';\n\n/**\n * Example progressbar component.\n */\n@<a href=\"api/core/Component\" class=\"code-anchor\">Component</a>({\n selector: 'app-example-progressbar',\n template: `<div class=\"bar\" [style.width.%]=\"value\"></div>`,\n styleUrls: ['./progress-bar.component.css'],\n host: {\n // Sets the role for this component to \"progressbar\"\n role: 'progressbar',\n\n // Sets the minimum and maximum values for the progressbar role.\n 'aria-valuemin': '0',\n 'aria-valuemax': '100',\n\n // Binding that updates the current value of the progressbar.\n '[attr.aria-valuenow]': 'value',\n }\n})\nexport class ExampleProgressbarComponent {\n /** Current value of the progressbar. */\n @<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>() value = 0;\n}\n\n\n</code-example></p>\n</li>\n</ul>\n<ul>\n<li>\n<p>In the template, the <code>aria-label</code> attribute ensures that the control is accessible to screen readers.</p>\n<p> <code-example path=\"accessibility/src/app/app.component.html\" header=\"src/app/app.component.html\" region=\"template\">\n<label>\n Enter an example progress value\n <input type=\"number\" <a href=\"api/forms/MinValidator\" class=\"code-anchor\">min</a>=\"0\" <a href=\"api/forms/MaxValidator\" class=\"code-anchor\">max</a>=\"100\"\n [value]=\"progress\" (input)=\"setProgress($event)\">\n</label>\n\n<!-- The user of the progressbar sets an aria-label to communicate what the progress means. -->\n<app-example-progressbar [value]=\"progress\" aria-label=\"Example of a progress bar\">\n</app-example-progressbar>\n\n</code-example></p>\n</li>\n</ul>\n<h2 id=\"routing-and-focus-management\">Routing and focus management<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#routing-and-focus-management\"><i class=\"material-icons\">link</i></a></h2>\n<p>Tracking and controlling <a href=\"https://developers.google.com/web/fundamentals/accessibility/focus/\">focus</a> in a UI is an important consideration in designing for accessibility.\nWhen using Angular routing, you should decide where page focus goes upon navigation.</p>\n<p>To avoid relying solely on visual cues, you need to make sure your routing code updates focus after page navigation.\nUse the <code><a href=\"api/router/NavigationEnd\" class=\"code-anchor\">NavigationEnd</a></code> event from the <code><a href=\"api/router/Router\" class=\"code-anchor\">Router</a></code> service to know when to update\nfocus.</p>\n<p>The following example shows how to find and focus the main content header in the DOM after navigation.</p>\n<code-example language=\"ts\">\nrouter.events.pipe(filter(e => e instanceof <a href=\"api/router/NavigationEnd\" class=\"code-anchor\">NavigationEnd</a>)).subscribe(() => {\n const mainHeader = document.querySelector('#main-content-header')\n if (mainHeader) {\n mainHeader.focus();\n }\n});\n</code-example>\n<p>In a real application, the element that receives focus will depend on your specific\napplication structure and layout.\nThe focused element should put users in a position to immediately move into the main content that has just been routed into view.\nYou should avoid situations where focus returns to the <code>body</code> element after a route change.</p>\n<h2 id=\"additional-resources\">Additional resources<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#additional-resources\"><i class=\"material-icons\">link</i></a></h2>\n<ul>\n<li>\n<p><a href=\"https://developers.google.com/web/fundamentals/accessibility\">Accessibility - Google Web Fundamentals</a></p>\n</li>\n<li>\n<p><a href=\"https://www.w3.org/TR/wai-aria/\">ARIA specification and authoring practices</a></p>\n</li>\n<li>\n<p><a href=\"https://material.io/design/usability/accessibility.html\">Material Design - Accessibility</a></p>\n</li>\n<li>\n<p><a href=\"https://www.smashingmagazine.com/search/?q=accessibility\">Smashing Magazine</a></p>\n</li>\n<li>\n<p><a href=\"https://inclusive-components.design/\">Inclusive Components</a></p>\n</li>\n<li>\n<p><a href=\"https://dequeuniversity.com/resources/\">Accessibility Resources and Code Examples</a></p>\n</li>\n<li>\n<p><a href=\"https://www.w3.org/WAI/people-use-web/\">W3C - Web Accessibility Initiative</a></p>\n</li>\n<li>\n<p><a href=\"https://www.youtube.com/watch?v=HtTyRajRuyY\">Rob Dodson A11ycasts</a></p>\n</li>\n<li>\n<p><a href=\"http://codelyzer.com/rules/\">Codelyzer</a> provides linting rules that can help you make sure your code meets accessibility standards.</p>\n</li>\n</ul>\n<p>Books</p>\n<ul>\n<li>\n<p>\"A Web for Everyone: Designing Accessible User Experiences\", Sarah Horton and Whitney Quesenbery</p>\n</li>\n<li>\n<p>\"Inclusive Design Patterns\", Heydon Pickering</p>\n</li>\n</ul>\n<h2 id=\"more-on-accessibility\">More on accessibility<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/accessibility#more-on-accessibility\"><i class=\"material-icons\">link</i></a></h2>\n<p>You may also be interested in the following:</p>\n<ul>\n<li><a href=\"https://web.dev/accessible-angular-with-codelyzer/\">Audit your Angular app's accessibility with codelyzer</a>.</li>\n</ul>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/architecture-next-steps\n - guide/example-apps-list\n-->\n<!-- links from this doc:\n - api/core/Component\n - api/core/Input\n - api/forms/MaxValidator\n - api/forms/MinValidator\n - api/router/NavigationEnd\n - api/router/Router\n - guide/accessibility#accessibility-attributes\n - guide/accessibility#accessibility-in-angular\n - guide/accessibility#additional-resources\n - guide/accessibility#angular-ui-components\n - guide/accessibility#augmenting-native-elements\n - guide/accessibility#case-study-building-a-custom-progress-bar\n - guide/accessibility#more-on-accessibility\n - guide/accessibility#routing-and-focus-management\n - guide/accessibility#using-containers-for-native-elements\n - guide/attribute-binding\n - guide/binding-syntax#html-attribute-vs-dom-property\n - http://codelyzer.com/rules/\n - https://dequeuniversity.com/resources/\n - https://developers.google.com/web/fundamentals/\n - https://developers.google.com/web/fundamentals/accessibility\n - https://developers.google.com/web/fundamentals/accessibility/#what_is_accessibility\n - https://developers.google.com/web/fundamentals/accessibility/focus/\n - https://developers.google.com/web/fundamentals/accessibility/semantics-aria\n - https://github.com/angular/angular/edit/master/aio/content/guide/accessibility.md?message=docs%3A%20describe%20your%20change...\n - https://github.com/angular/components/blob/50d3f29b6dc717b512dbd0234ce76f4ab7e9762a/src/material/button/button.ts#L67-L69\n - https://github.com/angular/components/blob/50d3f29b6dc717b512dbd0234ce76f4ab7e9762a/src/material/table/table.ts#L22\n - https://github.com/angular/components/blob/50d3f29b6dc717b512dbd0234ce76f4ab7e9762a/src/material/tabs/tab-nav-bar/tab-nav-bar.ts#L139\n - https://inclusive-components.design/\n - https://material.angular.io/\n - https://material.angular.io/cdk/a11y/overview\n - https://material.angular.io/cdk/categories\n - https://material.angular.io/components/form-field/overview\n - https://material.io/design/usability/accessibility.html\n - https://web.dev/accessible-angular-with-codelyzer/\n - https://www.smashingmagazine.com/search/?q=accessibility\n - https://www.w3.org/TR/wai-aria/\n - https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live\n - https://www.w3.org/WAI/people-use-web/\n - https://www.youtube.com/watch?v=HtTyRajRuyY\n-->"
|
|
} |