From 328d2b0f0e3286f5a13c8291cdd0f01c52dabefa Mon Sep 17 00:00:00 2001 From: Arcadio Quintero Date: Wed, 29 Oct 2025 21:53:18 -0400 Subject: [PATCH] feat: add best practices for accessibility, error handling, coding style, updates, and runtime performance - Introduced new guides for accessibility in Angular applications. - Added error handling best practices to improve application robustness. - Created a comprehensive coding style guide to promote consistency. - Included instructions for keeping Angular projects up-to-date. - Added runtime performance optimization techniques, including change detection strategies and profiling with Chrome DevTools. - Implemented translations for all new content. --- adev-es/src/content/best-practices/a11y.en.md | 173 ++++++++++ adev-es/src/content/best-practices/a11y.md | 126 +++---- .../best-practices/error-handling.en.md | 42 +++ .../content/best-practices/error-handling.md | 44 +-- .../runtime-performance/overview.en.md | 13 + .../runtime-performance/overview.md | 12 +- .../profiling-with-chrome-devtools.en.md | 100 ++++++ .../profiling-with-chrome-devtools.md | 102 +++--- .../skipping-subtrees.en.md | 132 ++++++++ .../runtime-performance/skipping-subtrees.md | 52 +-- .../slow-computations.en.md | 26 ++ .../runtime-performance/slow-computations.md | 32 +- .../runtime-performance/zone-pollution.en.md | 123 +++++++ .../runtime-performance/zone-pollution.md | 52 +-- .../content/best-practices/style-guide.en.md | 320 ++++++++++++++++++ .../src/content/best-practices/style-guide.md | 236 +++++-------- .../src/content/best-practices/update.en.md | 64 ++++ adev-es/src/content/best-practices/update.md | 78 ++--- 18 files changed, 1329 insertions(+), 398 deletions(-) create mode 100644 adev-es/src/content/best-practices/a11y.en.md create mode 100644 adev-es/src/content/best-practices/error-handling.en.md create mode 100644 adev-es/src/content/best-practices/runtime-performance/overview.en.md create mode 100644 adev-es/src/content/best-practices/runtime-performance/profiling-with-chrome-devtools.en.md create mode 100644 adev-es/src/content/best-practices/runtime-performance/skipping-subtrees.en.md create mode 100644 adev-es/src/content/best-practices/runtime-performance/slow-computations.en.md create mode 100644 adev-es/src/content/best-practices/runtime-performance/zone-pollution.en.md create mode 100644 adev-es/src/content/best-practices/style-guide.en.md create mode 100644 adev-es/src/content/best-practices/update.en.md diff --git a/adev-es/src/content/best-practices/a11y.en.md b/adev-es/src/content/best-practices/a11y.en.md new file mode 100644 index 0000000..7df1b3b --- /dev/null +++ b/adev-es/src/content/best-practices/a11y.en.md @@ -0,0 +1,173 @@ +# Accessibility in Angular + +The web is used by a wide variety of people, including those who have visual or motor impairments. +A variety of assistive technologies are available that make it much easier for these groups to interact with web-based software applications. +Also, designing an application to be more accessible generally improves the user experience for all users. + +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. + +This page discusses best practices for designing Angular applications that work well for all users, including those who rely on assistive technologies. + +## Accessibility attributes + + +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. +Use attribute binding template syntax to control the values of accessibility-related attributes. + +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. + + + + + + +NOTE: This syntax is only necessary for attribute *bindings*. +Static ARIA attributes require no extra syntax. + + + + + + +HELPFUL: By convention, HTML attributes use lowercase names \(`tabindex`\), while properties use camelCase names \(`tabIndex`\). + + +See the [Binding syntax guide](guide/templates) for more background on the difference between attributes and properties. + +## Angular UI components + +The [Angular Material](https://material.angular.dev) library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible. +The [Component Development Kit (CDK)](https://material.angular.dev/cdk/categories) includes the `a11y` package that provides tools to support various areas of accessibility. +For example: + +* `LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region. + 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). + +* The `cdkTrapFocus` directive traps Tab-key focus within an element. + Use it to create accessible experience for components such as modal dialogs, where focus must be constrained. + +For full details of these and other tools, see the [Angular CDK accessibility overview](https://material.angular.dev/cdk/a11y/overview). + +### Augmenting native elements + +Native HTML elements capture several standard interaction patterns that are important to accessibility. +When authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors. + +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 ` -NOTE: This syntax is only necessary for attribute *bindings*. -Static ARIA attributes require no extra syntax. +NOTA: Esta sintaxis solo es necesaria para *enlaces* de atributo. +Los atributos ARIA estáticos no requieren sintaxis adicional. - + -HELPFUL: By convention, HTML attributes use lowercase names \(`tabindex`\), while properties use camelCase names \(`tabIndex`\). +ÚTIL: Por convención, los atributos HTML usan nombres en minúsculas (`tabindex`), mientras que las propiedades usan nombres en camelCase (`tabIndex`). -See the [Binding syntax guide](guide/templates) for more background on the difference between attributes and properties. +Consulta la [guía de sintaxis de enlace](guide/templates) para más información sobre la diferencia entre atributos y propiedades. -## Angular UI components +## Componentes UI de Angular -The [Angular Material](https://material.angular.dev) library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible. -The [Component Development Kit (CDK)](https://material.angular.dev/cdk/categories) includes the `a11y` package that provides tools to support various areas of accessibility. -For example: +La biblioteca [Angular Material](https://material.angular.dev), que es mantenida por el equipo de Angular, es un conjunto de componentes UI reutilizables que busca ser completamente accesible. +El [Component Development Kit (CDK)](https://material.angular.dev/cdk/categories) incluye el paquete `a11y` que proporciona herramientas para soportar diversas áreas de accesibilidad. +Por ejemplo: -* `LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region. - 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). +* `LiveAnnouncer` se usa para anunciar mensajes para usuarios de lectores de pantalla usando una región `aria-live`. + Consulta la documentación de W3C para más información sobre [regiones aria-live](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live). -* The `cdkTrapFocus` directive traps Tab-key focus within an element. - Use it to create accessible experience for components such as modal dialogs, where focus must be constrained. +* La directiva `cdkTrapFocus` atrapa el foco de la tecla Tab dentro de un elemento. + Úsala para crear experiencias accesibles para componentes como diálogos modales, donde el foco debe estar restringido. -For full details of these and other tools, see the [Angular CDK accessibility overview](https://material.angular.dev/cdk/a11y/overview). +Para detalles completos de estas y otras herramientas, consulta la [visión general de accesibilidad de Angular CDK](https://material.angular.dev/cdk/a11y/overview). -### Augmenting native elements +### Aumentando elementos nativos -Native HTML elements capture several standard interaction patterns that are important to accessibility. -When authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors. +Los elementos HTML nativos capturan varios patrones de interacción estándar que son importantes para la accesibilidad. +Al crear componentes de Angular, debes reutilizar estos elementos nativos directamente cuando sea posible, en lugar de reimplementar comportamientos bien soportados. -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 ` + + + +``` + +Using meaningful names like this makes it easier to tell what an event does from reading the +template. + +For keyboard events, you can use Angular's key event modifiers with specific handler names: + +```html +