From 72d1affbddaa28241971f4836be9e84504d90071 Mon Sep 17 00:00:00 2001 From: dario-piotrowicz Date: Thu, 7 Jul 2022 16:32:50 +0100 Subject: [PATCH] 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 --- aio/content/guide/complex-animation-sequences.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/aio/content/guide/complex-animation-sequences.md b/aio/content/guide/complex-animation-sequences.md index e24bc96cd79..c85f484fccf 100644 --- a/aio/content/guide/complex-animation-sequences.md +++ b/aio/content/guide/complex-animation-sequences.md @@ -138,6 +138,14 @@ If you need to animate the items of an `*ngFor` list and there is a possibility +## 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 `
`.