docs(a11y): add docs about a11y style utilities (#13067)

Adds a couple of paragraphs about the utility styles that come with `cdk/a11y`.
This commit is contained in:
Kristiyan Kostadinov
2018-09-12 00:14:08 +02:00
committed by Jeremy Elbourn
parent 714c205312
commit c5076bab74
+44 -8
View File
@@ -22,7 +22,7 @@ interface ListKeyManagerOption {
Navigation through options can be made to wrap via the `withWrap` method
```ts
this.keyManager = new FocusKeyManager(...).withWrap();
```
```
### Types of key managers
There are two varieties of `ListKeyManager`, `FocusKeyManager` and `ActiveDescendantKeyManager`.
@@ -37,7 +37,7 @@ interface FocusableOption extends ListKeyManagerOption {
```
#### ActiveDescendantKeyManager
Used when options will be marked as active via `aria-activedescendant`.
Used when options will be marked as active via `aria-activedescendant`.
Each item managed must implement the
`Highlightable` interface:
```ts
@@ -69,10 +69,10 @@ This directive will not prevent focus from moving out of the trapped region due
interaction.
### Regions
Regions can be declared explicitly with an initial focus element by using
the `cdkFocusRegionStart`, `cdkFocusRegionEnd` and `cdkFocusInitial` DOM attributes.
`cdkFocusInitial` specifies the element that will receive focus upon initialization of the region.
`cdkFocusRegionStart` and `cdkFocusRegionEnd` define the region within which focus will be
Regions can be declared explicitly with an initial focus element by using
the `cdkFocusRegionStart`, `cdkFocusRegionEnd` and `cdkFocusInitial` DOM attributes.
`cdkFocusInitial` specifies the element that will receive focus upon initialization of the region.
`cdkFocusRegionStart` and `cdkFocusRegionEnd` define the region within which focus will be
trapped. When using the tab key, focus will move through this region and wrap around on either end.
For example:
@@ -94,7 +94,7 @@ details.
## LiveAnnouncer
`LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region.
See [the W3C's WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live)
for more information on aria-live regions.
for more information on aria-live regions.
### Example
```ts
@@ -135,7 +135,7 @@ if you `markForCheck` in the subscription you must put yourself back in the Angu
```ts
focusMonitor.monitor(el).subscribe(origin => this.ngZone.run(() => /* ... */ ));
```
```
Any element that is monitored by calling `monitor` should eventually be unmonitored by calling
`stopMonitoring` with the same element.
@@ -158,3 +158,39 @@ the host element with `checkChildren` set to `true`. Each of these directives ha
`cdkFocusChange` that will emit the new `FocusOrigin` whenever it changes.
<!-- example(focus-monitor-directives) -->
## Styling utilities
The CDK `a11y` package comes with a set of CSS styles that can be used when building accessible
components. To take advantage of them, you have to include the styles in your global stylesheet.
If you're using Material together with the CDK, these styles have been included for you already.
```scss
@import '~@angular/cdk/text-field/text-field';
@include cdk-a11y();
```
### Hiding elements, while keeping them available for screen readers
By default, screen readers and other assistive technology will skip elements that have
`display: none`, `visibility: hidden` etc. In some cases you may need to visually hide an element,
while keeping it available for assistive technology. You can do so using the `cdk-visually-hidden`
class:
```html
<div class="custom-checkbox">
<input type="checkbox" class="cdk-visually-hidden">
</div>
```
### Targeting high contrast users
The `a11y` package offers a mixin that allows you to target users that have the Windows high
contrast mode turned on, via a media query. To target high contrast users, you can wrap your
styles with the `cdk-high-contrast` mixin:
```scss
button {
@include cdk-high-contrast {
outline: solid 1px;
}
}
```