Skip to content

Commit 51fc073

Browse files
ricardochlSplaktar
ricardochl
authored and
Splaktar
committed
chore: add adve-es folder with files from origin
The files added to the adev-es folder are files that require traductions.
1 parent e2a4ea9 commit 51fc073

File tree

214 files changed

+31692
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

214 files changed

+31692
-0
lines changed

‎adev-es/src/app/sub-navigation-data.ts‎

Lines changed: 1361 additions & 0 deletions
Large diffs are not rendered by default.

‎adev-es/src/content/best-practices/a11y.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Accessibility in Angular
2+
3+
The web is used by a wide variety of people, including those who have visual or motor impairments.
4+
A variety of assistive technologies are available that make it much easier for these groups to interact with web-based software applications.
5+
Also, designing an application to be more accessible generally improves the user experience for all users.
6+
7+
For an in-depth introduction to issues and techniques for designing accessible applications, see Google's web.dev [Learn Accessibility](https://web.dev/learn/accessibility/) course.
8+
9+
This page discusses best practices for designing Angular applications that work well for all users, including those who rely on assistive technologies.
10+
11+
## Accessibility attributes
12+
13+
<!-- TODO: add link once attribute binding guide is implemented -->
14+
Building accessible web experience often involves setting [Accessible Rich Internet Applications \(ARIA\) attributes](https://web.dev/learn/accessibility/aria-html/) to provide semantic meaning where it might otherwise be missing.
15+
Use attribute binding template syntax to control the values of accessibility-related attributes.
16+
17+
When binding to ARIA attributes in Angular, you must use the `attr.` prefix. The ARIA specification depends specifically on HTML attributes rather than properties of DOM elements.
18+
19+
<docs-code language="html">
20+
&lt;!-- Use attr. when binding to an ARIA attribute --&gt;
21+
&lt;button [attr.aria-label]="myActionLabel"&gt;&hellip;&lt;/button&gt;
22+
</docs-code>
23+
24+
Note: This syntax is only necessary for attribute *bindings*.
25+
Static ARIA attributes require no extra syntax.
26+
27+
<docs-code language="html">
28+
&lt;!-- Static ARIA attributes require no extra syntax --&gt;
29+
&lt;button aria-label="Save document"&gt;&hellip;&lt;/button&gt;
30+
</docs-code>
31+
32+
HELPFUL: By convention, HTML attributes use lowercase names \(`tabindex`\), while properties use camelCase names \(`tabIndex`\).
33+
34+
<!-- TODO: add link once attribute binding guide implemented -->
35+
See the [Binding syntax guide](guide/templates) for more background on the difference between attributes and properties.
36+
37+
## Angular UI components
38+
39+
The [Angular Material](https://material.angular.io) library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible.
40+
The [Component Development Kit (CDK)](https://material.angular.io/cdk/categories) includes the `a11y` package that provides tools to support various areas of accessibility.
41+
For example:
42+
43+
* `LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region.
44+
See the W3C documentation for more information on [aria-live regions](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live).
45+
46+
* The `cdkTrapFocus` directive traps Tab-key focus within an element.
47+
Use it to create accessible experience for components such as modal dialogs, where focus must be constrained.
48+
49+
For full details of these and other tools, see the [Angular CDK accessibility overview](https://material.angular.io/cdk/a11y/overview).
50+
51+
### Augmenting native elements
52+
53+
Native HTML elements capture several standard interaction patterns that are important to accessibility.
54+
When authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors.
55+
56+
For example, instead of creating a custom element for a new variety of button, create a component that uses an attribute selector with a native `<button>` element.
57+
This most commonly applies to `<button>` and `<a>`, but can be used with many other types of element.
58+
59+
You can see examples of this pattern in Angular Material:
60+
[`MatButton`](https://github.com/angular/components/blob/main/src/material/button/button.ts#L33C3-L36C5), [`MatTabNav`](https://github.com/angular/components/blob/main/src/material/tabs/tab-nav-bar/tab-nav-bar.ts#L62), and [`MatTable`](https://github.com/angular/components/blob/main/src/material/table/table.ts#L40).
61+
62+
### Using containers for native elements
63+
64+
Sometimes using the appropriate native element requires a container element.
65+
For example, the native `<input>` element cannot have children, so any custom text entry components need to wrap an `<input>` with extra elements.
66+
By just including `<input>` in your custom component's template, it's impossible for your component's users to set arbitrary properties and attributes to the `<input>` element.
67+
Instead, create a container component that uses content projection to include the native control in the component's API.
68+
69+
You can see [`MatFormField`](https://material.angular.io/components/form-field/overview) as an example of this pattern.
70+
71+
## Case study: Building a custom progress bar
72+
73+
The following example shows how to make a progress bar accessible by using host binding to control accessibility-related attributes.
74+
75+
* The component defines an accessibility-enabled element with both the standard HTML attribute `role`, and ARIA attributes.
76+
The ARIA attribute `aria-valuenow` is bound to the user's input.
77+
* In the template, the `aria-label` attribute ensures that the control is accessible to screen readers.
78+
79+
<docs-code-multifile
80+
path="accessibility/src/app/app.component.ts"
81+
preview>
82+
<docs-code
83+
path="accessibility/src/app/progress-bar.component.ts"
84+
linenums
85+
highlight="[12, 20]"/>
86+
<docs-code
87+
path="accessibility/src/app/app.component.html"
88+
linenums
89+
highlight="[8, 9]"/>
90+
</docs-code-multifile>
91+
92+
## Routing
93+
94+
### Focus management after navigation
95+
96+
Tracking and controlling [focus](https://web.dev/learn/accessibility/focus/) in a UI is an important consideration in designing for accessibility.
97+
When using Angular routing, you should decide where page focus goes upon navigation.
98+
99+
To avoid relying solely on visual cues, you need to make sure your routing code updates focus after page navigation.
100+
Use the `NavigationEnd` event from the `Router` service to know when to update focus.
101+
102+
The following example shows how to find and focus the main content header in the DOM after navigation.
103+
104+
<docs-code language="typescript">
105+
106+
router.events.pipe(filter(e =&gt; e instanceof NavigationEnd)).subscribe(() =&gt; {
107+
const mainHeader = document.querySelector('&num;main-content-header')
108+
if (mainHeader) {
109+
mainHeader.focus();
110+
}
111+
});
112+
113+
</docs-code>
114+
115+
In a real application, the element that receives focus depends on your specific application structure and layout.
116+
The focused element should put users in a position to immediately move into the main content that has just been routed into view.
117+
You should avoid situations where focus returns to the `body` element after a route change.
118+
119+
### Active links identification
120+
121+
CSS classes applied to active `RouterLink` elements, such as `RouterLinkActive`, provide a visual cue to identify the active link.
122+
Unfortunately, a visual cue doesn't help blind or visually impaired users.
123+
Applying the `aria-current` attribute to the element can help identify the active link.
124+
For more information, see [Mozilla Developer Network \(MDN\) aria-current](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)).
125+
126+
The `RouterLinkActive` directive provides the `ariaCurrentWhenActive` input which sets the `aria-current` to a specified value when the link becomes active.
127+
128+
The following example shows how to apply the `active-page` class to active links as well as setting their `aria-current` attribute to `"page"` when they are active:
129+
130+
```html
131+
<nav>
132+
<a routerLink="home"
133+
routerLinkActive="active-page"
134+
ariaCurrentWhenActive="page">
135+
Home
136+
</a>
137+
<a routerLink="about"
138+
routerLinkActive="active-page"
139+
ariaCurrentWhenActive="page">
140+
About
141+
</a>
142+
<a routerLink="shop"
143+
routerLinkActive="active-page"
144+
ariaCurrentWhenActive="page">
145+
Shop
146+
</a>
147+
</nav>
148+
```
149+
150+
<!-- vale Angular.Angular_Spelling = NO -->
151+
152+
## More information
153+
154+
* [Accessibility - Google Web Fundamentals](https://developers.google.com/web/fundamentals/accessibility)
155+
* [ARIA specification and authoring practices](https://www.w3.org/TR/wai-aria)
156+
* [Material Design - Accessibility](https://material.io/design/usability/accessibility.html)
157+
* [Smashing Magazine](https://www.smashingmagazine.com/search/?q=accessibility)
158+
* [Inclusive Components](https://inclusive-components.design)
159+
* [Accessibility Resources and Code Examples](https://dequeuniversity.com/resources)
160+
* [W3C - Web Accessibility Initiative](https://www.w3.org/WAI/people-use-web)
161+
* [Rob Dodson A11ycasts](https://www.youtube.com/watch?v=HtTyRajRuyY)
162+
* [Angular ESLint](https://github.com/angular-eslint/angular-eslint#functionality) provides linting rules that can help you make sure your code meets accessibility standards.
163+
164+
<!-- vale Angular.Angular_Spelling = YES -->
165+
166+
Books
167+
168+
<!-- vale Angular.Google_Quotes = NO -->
169+
170+
* "A Web for Everyone: Designing Accessible User Experiences," Sarah Horton and Whitney Quesenbery
171+
* "Inclusive Design Patterns," Heydon Pickering
172+
173+
<!-- vale Angular.Google_Quotes = YES -->

‎adev-es/src/content/best-practices/runtime-performance/overview.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Runtime performance optimization
2+
3+
Fast rendering is critical for Angular and we've built the framework with a lot of optimizations in mind to help you develop performant apps. To better understand the performance of your app we offer [Angular DevTools](tools/devtools) and a [video guide](https://www.youtube.com/watch?v=FjyX_hkscII) on how to use Chrome DevTools for profiling. In this section we cover the most common performance optimization techniques.
4+
5+
**Change detection** is the process through which Angular checks to see whether your application state has changed, and if any DOM needs to be updated. At a high level, Angular walks your components from top to bottom, looking for changes. Angular runs its change detection mechanism periodically so that changes to the data model are reflected in an application’s view. Change detection can be triggered either manually or through an asynchronous event (for example, a user interaction or an XMLHttpRequest completion).
6+
7+
Change detection is highly optimized and performant, but it can still cause slowdowns if the application runs it too frequently.
8+
9+
In this guide, you’ll learn how to control and optimize the change detection mechanism by skipping parts of your application and running change detection only when necessary.
10+
11+
Watch this video if you prefer to learn more about performance optimizations in a media format:
12+
13+
<docs-video src="https://www.youtube.com/embed/f8sA-i6gkGQ"/>

‎adev-es/src/content/best-practices/runtime-performance/skipping-subtrees.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Skipping component subtrees
2+
3+
JavaScript, by default, uses mutable data structures that you can reference from multiple different components. Angular runs change detection over your entire component tree to make sure that the most up-to-date state of your data structures is reflected in the DOM.
4+
5+
Change detection is sufficiently fast for most applications. However, when an application has an especially large component tree, running change detection across the whole application can cause performance issues. You can address this by configuring change detection to only run on a subset of the component tree.
6+
7+
If you are confident that a part of the application is not affected by a state change, you can use [OnPush](/api/core/ChangeDetectionStrategy) to skip change detection in an entire component subtree.
8+
9+
## Using `OnPush`
10+
11+
OnPush change detection instructs Angular to run change detection for a component subtree **only** when:
12+
13+
* The root component of the subtree receives new inputs as the result of a template binding. Angular compares the current and past value of the input with `==`.
14+
* Angular handles an event _(for example using event binding, output binding, or `@HostListener` )_ in the subtree's root component or any of its children whether they are using OnPush change detection or not.
15+
16+
You can set the change detection strategy of a component to `OnPush` in the `@Component` decorator:
17+
18+
```ts
19+
import { ChangeDetectionStrategy, Component } from '@angular/core';
20+
@Component({
21+
changeDetection: ChangeDetectionStrategy.OnPush,
22+
})
23+
export class MyComponent {}
24+
```
25+
26+
## Common change detection scenarios
27+
28+
This section examines several common change detection scenarios to illustrate Angular's behavior.
29+
30+
### An event is handled by a component with default change detection
31+
32+
If Angular handles an event within a component without `OnPush` strategy, the framework executes change detection on the entire component tree. Angular will skip descendant component subtrees with roots using `OnPush`, which have not received new inputs.
33+
34+
As an example, if we set the change detection strategy of `MainComponent` to `OnPush` and the user interacts with a component outside the subtree with root `MainComponent`, Angular will check all the green components from the diagram below (`AppComponent`, `HeaderComponent`, `SearchComponent`, `ButtonComponent`) unless `MainComponent` receives new inputs:
35+
36+
```mermaid
37+
graph TD;
38+
app[AppComponent] --- header[HeaderComponent];
39+
app --- main["MainComponent (OnPush)"];
40+
header --- search[SearchComponent];
41+
header --- button[ButtonComponent];
42+
main --- login["LoginComponent (OnPush)"];
43+
main --- details[DetailsComponent];
44+
event>Event] --- search
45+
46+
style main fill:#E4BE74,color:#000
47+
style login fill:#E4BE74,color:#000
48+
style details fill:#E4BE74,color:#000
49+
50+
style app fill:#C1D5B0,color:#000
51+
style header fill:#C1D5B0,color:#000
52+
style button fill:#C1D5B0,color:#000
53+
style search fill:#C1D5B0,color:#000
54+
```
55+
56+
## An event is handled by a component with OnPush
57+
58+
If Angular handles an event within a component with OnPush strategy, the framework will execute change detection within the entire component tree. Angular will ignore component subtrees with roots using OnPush, which have not received new inputs and are outside the component which handled the event.
59+
60+
As an example, if Angular handles an event within `MainComponent`, the framework will run change detection in the entire component tree. Angular will ignore the subtree with root `LoginComponent` because it has `OnPush` and the event happened outside of its scope.
61+
62+
<img alt="Change detection propagation from OnPush component" src="assets/content/images/best-practices/runtime-performance/on-push-trigger.svg">
63+
64+
```mermaid
65+
graph TD;
66+
app[AppComponent] --- header[HeaderComponent];
67+
app --- main["MainComponent (OnPush)"];
68+
header --- search[SearchComponent];
69+
header --- button[ButtonComponent];
70+
main --- login["LoginComponent (OnPush)"];
71+
main --- details[DetailsComponent];
72+
event>Event] --- main
73+
74+
style login fill:#E4BE74,color:#000
75+
76+
style app fill:#C1D5B0,color:#000
77+
style header fill:#C1D5B0,color:#000
78+
style button fill:#C1D5B0,color:#000
79+
style search fill:#C1D5B0,color:#000
80+
style main fill:#C1D5B0,color:#000
81+
style details fill:#C1D5B0,color:#000
82+
```
83+
84+
## An event is handled by a descendant of a component with OnPush
85+
86+
If Angular handles an event in a component with OnPush, the framework will execute change detection in the entire component tree, including the component’s ancestors.
87+
88+
As an example, in the diagram below, Angular handles an event in `LoginComponent` which uses OnPush. Angular will invoke change detection in the entire component subtree including `MainComponent` (`LoginComponent`’s parent), even though `MainComponent` has `OnPush` as well. Angular checks `MainComponent` as well because `LoginComponent` is part of its view.
89+
90+
```mermaid
91+
graph TD;
92+
app[AppComponent] --- header[HeaderComponent];
93+
app --- main["MainComponent (OnPush)"];
94+
header --- search[SearchComponent];
95+
header --- button[ButtonComponent];
96+
main --- login["LoginComponent (OnPush)"];
97+
main --- details[DetailsComponent];
98+
event>Event] --- login
99+
100+
style app fill:#C1D5B0,color:#000
101+
style header fill:#C1D5B0,color:#000
102+
style button fill:#C1D5B0,color:#000
103+
style search fill:#C1D5B0,color:#000
104+
style login fill:#C1D5B0,color:#000
105+
style main fill:#C1D5B0,color:#000
106+
style details fill:#C1D5B0,color:#000
107+
```
108+
109+
## New inputs to component with OnPush
110+
111+
Angular will run change detection within a child component with `OnPush` when setting an input property as result of a template binding.
112+
113+
For example, in the diagram below, `AppComponent` passes a new input to `MainComponent`, which has `OnPush`. Angular will run change detection in `MainComponent` but will not run change detection in `LoginComponent`, which also has `OnPush`, unless it receives new inputs as well.
114+
115+
```mermaid
116+
graph TD;
117+
app[AppComponent] --- header[HeaderComponent];
118+
app --- main["MainComponent (OnPush)"];
119+
header --- search[SearchComponent];
120+
header --- button[ButtonComponent];
121+
main --- login["LoginComponent (OnPush)"];
122+
main --- details[DetailsComponent];
123+
event>Parent passes new input to MainComponent]
124+
125+
style login fill:#E4BE74,color:#000
126+
127+
linkStyle 1 stroke:green
128+
style app fill:#C1D5B0,color:#000
129+
style header fill:#C1D5B0,color:#000
130+
style button fill:#C1D5B0,color:#000
131+
style search fill:#C1D5B0,color:#000
132+
style main fill:#C1D5B0,color:#000
133+
style details fill:#C1D5B0,color:#000
134+
```
135+
136+
## Edge cases
137+
138+
* **Modifying input properties in TypeScript code**. When you use an API like `@ViewChild` or `@ContentChild` to get a reference to a component in TypeScript and manually modify an `@Input` property, Angular will not automatically run change detection for OnPush components. If you need Angular to run change detection, you can inject `ChangeDetectorRef` in your component and call `changeDetectorRef.markForCheck()` to tell Angular to schedule a change detection.
139+
* **Modifying object references**. In case an input receives a mutable object as value and you modify the object but preserve the reference, Angular will not invoke change detection. That’s the expected behavior because the previous and the current value of the input point to the same reference.

0 commit comments

Comments
 (0)