docs(animations): add section about animations and view encapsulation (#46738)

Add a section regarding component view encapsulations in the complex animation
sequences guide to let developers know how animations work in regard to
view encapsulations.

This section is used to both add information to the guide but also to
take a stand on how the animations should behave in regard to the
shadow dom view encapsulation.

This relates to PR #46488 which by trying to make sure the query
function works with shadow dom elements proved that having the
animations implementation work with shadow dom would increase the
complexity of the code and would have a negative impact on performance,
such facts alongide the small adoption of shadow dom by users influenced
the decision to keep the current functionalities and simply discourage
the use of animations and shadow dom components.

PR Close #46738
This commit is contained in:
dario-piotrowicz
2022-07-07 16:32:50 +01:00
committed by Alex Rickabaugh
parent 68b46e0d8d
commit 72d1affbdd
@@ -138,6 +138,14 @@ If you need to animate the items of an `*ngFor` list and there is a possibility
</div>
## Animations and Component View Encapsulation
Angular animations are based on the components DOM structure and do not directly take [View Encapsulation](/guide/view-encapsulation) into account, this means that components using `ViewEncapsulation.Emulated` behave exactly as if they where using `ViewEncapsulation.None` (`ViewEncapsulation.ShadowDom` behaves differently as we'll discuss shortly).
For example if the `query()` function (which you'll see more of in the rest of the Animations guide) were to be applied at the top of a tree of components using the emulated view encapsulation, such query would be able to identify (and thus animate) DOM elements on any depth of the tree.
On the other hand the `ViewEncapsulation.ShadowDom` changes the component's DOM structure by "hiding" DOM elements inside [`ShadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) elements. Such DOM manipulations do prevent some of the animations implementation to work properly since it relies on simple DOM structures and doesn't take `ShadowRoot` elements into account. Therefore it is advised to avoid applying animations to views incorporating components using the ShadowDom view encapsulation.
## Animation sequence summary
Angular functions for animating multiple elements start with `query()` to find inner elements; for example, gathering all images within a `<div>`.