mirror of
https://github.com/angular/angular.git
synced 2026-09-14 13:54:52 +08:00
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:
committed by
Jeremy Elbourn
parent
714c205312
commit
c5076bab74
+44
-8
@@ -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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user