Skip to content

Commit 297092d

Browse files
ist-h-iist-h-i
authored
feat(docs): translate guide/animations/migration.md (#1152)
* docs: translate guide/animations/migration.md * Feat(docs) translate guide/animations/overview * Fix(docs) align wording in guide/animations/overview * Revert "Merge pull request #3 from ist-h-i/codex/feat-docs-translate-guide-animations-overview" This reverts commit d8430de, reversing changes made to a2ba752.
1 parent 0085728 commit 297092d

File tree

2 files changed

+367
-87
lines changed

2 files changed

+367
-87
lines changed

‎adev-ja/src/content/guide/animations/migration.en.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# Migrating away from Angular's Animations package
2+
3+
The `@angular/animations` package is deprecated as of v20.2, which also introduced the new `animate.enter` and `animate.leave` feature to add animations to your application. Using these new features, you can replace all animations based on `@angular/animations` with plain CSS or JS animation libraries. Removing `@angular/animations` from your application can significantly reduce the size of your JavaScript bundle. Native CSS animations generally offer superior performance, as they can benefit from hardware acceleration. This guide walks through the process of refactoring your code from `@angular/animations` to native CSS animations.
4+
5+
## How to write animations in native CSS
6+
7+
If you've never written any native CSS animations, there are a number of excellent guides to get you started. Here's a few of them:
8+
[MDN's CSS Animations guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)
9+
[W3Schools CSS3 Animations guide](https://www.w3schools.com/css/css3_animations.asp)
10+
[The Complete CSS Animations Tutorial](https://www.lambdatest.com/blog/css-animations-tutorial/)
11+
[CSS Animation for Beginners](https://thoughtbot.com/blog/css-animation-for-beginners)
12+
13+
and a couple of videos:
14+
[Learn CSS Animation in 9 Minutes](https://www.youtube.com/watch?v=z2LQYsZhsFw)
15+
[Net Ninja CSS Animation Tutorial Playlist](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)
16+
17+
Check some of these various guides and tutorials out, and then come back to this guide.
18+
19+
## Creating Reusable Animations
20+
21+
Just like with the animations package, you can create reusable animations that can be shared across your application. The animations package version of this had you using the `animation()` function in a shared typescript file. The native CSS version of this is similar, but lives in a shared CSS file.
22+
23+
#### With Animations Package
24+
25+
<docs-code header="animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" region="animation-example"/>
26+
27+
#### With Native CSS
28+
29+
<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>
30+
31+
Adding the class `animated-class` to an element would trigger the animation on that element.
32+
33+
## Animating a Transition
34+
35+
### Animating State and Styles
36+
37+
The animations package allowed you to define various states using the [`state()`](api/animations/state) function within a component. Examples might be an `open` or `closed` state containing the styles for each respective state within the definition. For example:
38+
39+
#### With Animations Package
40+
41+
<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="state1"/>
42+
43+
This same behavior can be accomplished natively by using CSS classes either using a keyframe animation or transition styling.
44+
45+
#### With Native CSS
46+
47+
<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>
48+
49+
Triggering the `open` or `closed` state is done by toggling classes on the element in your component. You can find examples of how to do this in our [template guide](guide/templates/binding#css-class-and-style-property-bindings).
50+
51+
You can see similar examples in the template guide for [animating styles directly](guide/templates/binding#css-style-properties).
52+
53+
### Transitions, Timing, and Easing
54+
55+
The animations package `animate()` function allows for providing timing, like duration, delays and easing. This can be done natively with CSS using several css properties or shorthand properties.
56+
57+
Specify `animation-duration`, `animation-delay`, and `animation-timing-function` for a keyframe animation in CSS, or alternatively use the `animation` shorthand property.
58+
59+
<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>
60+
61+
Similarly, you can use `transition-duration`, `transition-delay`, and `transition-timing-function` and the `transition` shorthand for animations that are not using `@keyframes`.
62+
63+
<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>
64+
65+
### Triggering an Animation
66+
67+
The animations package required specifying triggers using the `trigger()` function and nesting all of your states within it. With native CSS, this is unnecessary. Animations can be triggered by toggling CSS styles or classes. Once a class is present on an element, the animation will occur. Removing the class will revert the element back to whatever CSS is defined for that element. This results in significantly less code to do the same animation. Here's an example:
68+
69+
#### With Animations Package
70+
71+
<docs-code-multifile>
72+
<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/animations-package/open-close.ts" />
73+
<docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/animations-package/open-close.html" />
74+
<docs-code header="open-close.css" path="adev/src/content/examples/animations/src/app/animations-package/open-close.css"/>
75+
</docs-code-multifile>
76+
77+
#### With Native CSS
78+
79+
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.ts">
80+
<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.ts" />
81+
<docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.html" />
82+
<docs-code header="open-close.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.css"/>
83+
</docs-code-multifile>
84+
85+
## Transition and Triggers
86+
87+
### Predefined State and wildcard matching
88+
89+
The animations package offers the ability to match your defined states to a transition via strings. For example, animating from open to closed would be `open => closed`. You can use wildcards to match any state to a target state, like `* => closed` and the `void` keyword can be used for entering and exiting states. For example: `* => void` for when an element leaves a view or `void => *` for when the element enters a view.
90+
91+
These state matching patterns are not needed at all when animating with CSS directly. You can manage what transitions and `@keyframes` animations apply based on whatever classes you set and / or styles you set on the elements. You can also add `@starting-style` to control how the element looks upon immediately entering the DOM.
92+
93+
### Automatic Property Calculation with Wildcards
94+
95+
The animations package offers the ability to animate things that have been historically difficult to animate, like animating a set height to `height: auto`. You can now do this with pure CSS as well.
96+
97+
#### With Animations Package
98+
99+
<docs-code-multifile>
100+
<docs-code header="auto-height.ts" path="adev/src/content/examples/animations/src/app/animations-package/auto-height.ts" />
101+
<docs-code header="auto-height.html" path="adev/src/content/examples/animations/src/app/animations-package/auto-height.html" />
102+
<docs-code header="auto-height.css" path="adev/src/content/examples/animations/src/app/animations-package/auto-height.css" />
103+
</docs-code-multifile>
104+
105+
You can use css-grid to animate to auto height.
106+
107+
#### With Native CSS
108+
109+
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts">
110+
<docs-code header="auto-height.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts" />
111+
<docs-code header="auto-height.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.html" />
112+
<docs-code header="auto-height.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.css" />
113+
</docs-code-multifile>
114+
115+
If you don't have to worry about supporting all browsers, you can also check out `calc-size()`, which is the true solution to animating auto height. See [MDN's docs](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) and (this tutorial)[https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/] for more information.
116+
117+
### Animate entering and leaving a view
118+
119+
The animations package offered the previously mentioned pattern matching for entering and leaving but also included the shorthand aliases of `:enter` and `:leave`.
120+
121+
#### With Animations Package
122+
123+
<docs-code-multifile>
124+
<docs-code header="insert-remove.ts" path="adev/src/content/examples/animations/src/app/animations-package/insert-remove.ts" />
125+
<docs-code header="insert-remove.html" path="adev/src/content/examples/animations/src/app/animations-package/insert-remove.html" />
126+
<docs-code header="insert-remove.css" path="adev/src/content/examples/animations/src/app/animations-package/insert-remove.css" />
127+
</docs-code-multifile>
128+
129+
#### With Native CSS
130+
131+
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.ts">
132+
<docs-code header="insert.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.ts" />
133+
<docs-code header="insert.html" path="adev/src/content/examples/animations/src/app/native-css/insert.html" />
134+
<docs-code header="insert.css" path="adev/src/content/examples/animations/src/app/native-css/insert.css" />
135+
</docs-code-multifile>
136+
137+
#### With Native CSS
138+
139+
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.ts">
140+
<docs-code header="remove.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.ts" />
141+
<docs-code header="remove.html" path="adev/src/content/examples/animations/src/app/native-css/remove.html" />
142+
<docs-code header="remove.css" path="adev/src/content/examples/animations/src/app/native-css/remove.css" />
143+
</docs-code-multifile>
144+
145+
For more information on `animate.enter` and `animate.leave`, see the [Enter and Leave animations guide](guide/animations).
146+
147+
### Animating increment and decrement
148+
149+
Along with the aforementioned `:enter` and `:leave`, there's also `:increment` and `:decrement`. You can animate these also by adding and removing classes. Unlike the animation package built-in aliases, there is no automatic application of classes when the values go up or down. You can apply the appropriate classes programmatically. Here's an example:
150+
151+
#### With Animations Package
152+
153+
<docs-code-multifile>
154+
<docs-code header="increment-decrement.ts" path="adev/src/content/examples/animations/src/app/animations-package/increment-decrement.ts" />
155+
<docs-code header="increment-decrement.html" path="adev/src/content/examples/animations/src/app/animations-package/increment-decrement.html" />
156+
<docs-code header="increment-decrement.css" path="adev/src/content/examples/animations/src/app/animations-package/increment-decrement.css" />
157+
</docs-code-multifile>
158+
159+
#### With Native CSS
160+
161+
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts">
162+
<docs-code header="increment-decrement.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts" />
163+
<docs-code header="increment-decrement.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.html" />
164+
<docs-code header="increment-decrement.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.css" />
165+
</docs-code-multifile>
166+
167+
### Parent / Child Animations
168+
169+
Unlike the animations package, when multiple animations are specified within a given component, no animation has priority over another and nothing blocks any animation from firing. Any sequencing of animations would have to be handled by your definition of your CSS animation, using animation / transition delay, and / or using `animationend` or `transitionend` to handle adding the next css to be animated.
170+
171+
### Disabling an animation or all animations
172+
173+
With native CSS animations, if you'd like to disable the animations that you've specified, you have multiple options.
174+
175+
1. Create a custom class that forces animation and transition to `none`.
176+
177+
```css
178+
.no-animation {
179+
animation: none !important;
180+
transition: none !important;
181+
}
182+
```
183+
184+
Applying this class to an element prevents any animation from firing on that element. You could alternatively scope this to your entire DOM or section of your DOM to enforce this behavior. However, this prevents animation events from firing. If you are awaiting animation events for element removal, this solution won't work. A workaround is to set durations to 1 millisecond instead.
185+
186+
2. Use the [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query to ensure no animations play for users that prefer less animation.
187+
188+
3. Prevent adding animation classes programatically
189+
190+
### Animation Callbacks
191+
192+
The animations package exposed callbacks for you to use in the case that you want to do something when the animation has finished. Native CSS animations also have these callbacks.
193+
194+
[`OnAnimationStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationstart_event)
195+
[`OnAnimationEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationend_event)
196+
[`OnAnimationIteration`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationitration_event)
197+
[`OnAnimationCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationcancel_event)
198+
199+
[`OnTransitionStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionstart_event)
200+
[`OnTransitionRun`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionrun_event)
201+
[`OnTransitionEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionend_event)
202+
[`OnTransitionCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitioncancel_event)
203+
204+
The Web Animations API has a lot of additional functionality. [Take a look at the documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) to see all the available animation APIs.
205+
206+
NOTE: Be aware of bubbling issues with these callbacks. If you are animating children and parents, the events bubble up from children to parents. Consider stopping propagation or looking at more details within the event to determine if you're responding to the desired event target rather than an event bubbling up from a child node. You can examine the `animationname` property or the properties being transitioned to verify you have the right nodes.
207+
208+
## Complex Sequences
209+
210+
The animations package has built-in functionality for creating complex sequences. These sequences are all entirely possible without the animations package.
211+
212+
### Targeting specific elements
213+
214+
In the animations package, you could target specific elements by using the `query()` function to find specific elements by a CSS class name, similar to [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector). This is unnecessary in a native CSS animation world. Instead, you can use your CSS selectors to target sub-classes and apply any desired `transform` or `animation`.
215+
216+
To toggle classes for child nodes within a template, you can use class and style bindings to add the animations at the right points.
217+
218+
### Stagger()
219+
220+
The `stagger()` function allowed you to delay the animation of each item in a list of items by a specified time to create a cascade effect. You can replicate this behavior in native CSS by utilizing `animation-delay` or `transition-delay`. Here is an example of what that CSS might look like.
221+
222+
#### With Animations Package
223+
224+
<docs-code-multifile>
225+
<docs-code header="stagger.ts" path="adev/src/content/examples/animations/src/app/animations-package/stagger.ts" />
226+
<docs-code header="stagger.html" path="adev/src/content/examples/animations/src/app/animations-package/stagger.html" />
227+
<docs-code header="stagger.css" path="adev/src/content/examples/animations/src/app/animations-package/stagger.css" />
228+
</docs-code-multifile>
229+
230+
#### With Native CSS
231+
232+
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.ts">
233+
<docs-code header="stagger.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.ts" />
234+
<docs-code header="stagger.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.html" />
235+
<docs-code header="stagger.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.css" />
236+
</docs-code-multifile>
237+
238+
### Parallel Animations
239+
240+
The animations package has a `group()` function to play multiple animations at the same time. In CSS, you have full control over animation timing. If you have multiple animations defined, you can apply all of them at once.
241+
242+
```css
243+
.target-element {
244+
animation:
245+
rotate 3s,
246+
fade-in 2s;
247+
}
248+
```
249+
250+
In this example, the `rotate` and `fade-in` animations fire at the same time.
251+
252+
### Animating the items of a reordering list
253+
254+
Items reordering in a list works out of the box using the previously described techniques. No additional special work is required. Items in a `@for` loop will be removed and re-added properly, which will fire off animations using `@starting-styles` for entry animations. Alternatively, you can use `animate.enter` for this same behavior. Use `animate.leave` to animate elements as they are removed, as seen in the example above.
255+
256+
#### With Animations Package
257+
258+
<docs-code-multifile>
259+
<docs-code header="reorder.ts" path="adev/src/content/examples/animations/src/app/animations-package/reorder.ts" />
260+
<docs-code header="reorder.html" path="adev/src/content/examples/animations/src/app/animations-package/reorder.html" />
261+
<docs-code header="reorder.css" path="adev/src/content/examples/animations/src/app/animations-package/reorder.css" />
262+
</docs-code-multifile>
263+
264+
#### With Native CSS
265+
266+
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.ts">
267+
<docs-code header="reorder.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.ts" />
268+
<docs-code header="reorder.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.html" />
269+
<docs-code header="reorder.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.css" />
270+
</docs-code-multifile>
271+
272+
## Migrating usages of AnimationPlayer
273+
274+
The `AnimationPlayer` class allows access to an animation to do more advanced things like pause, play, restart, and finish an animation through code. All of these things can be handled natively as well.
275+
276+
You can retrieve animations off an element directly using [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations). This returns an array of every [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) on that element. You can use the `Animation` API to do much more than you could with what the `AnimationPlayer` from the animations package offered. From here you can `cancel()`, `play()`, `pause()`, `reverse()` and much more. This native API should provide everything you need to control your animations.
277+
278+
## Route Transitions
279+
280+
You can use view transitions to animate between routes. See the [Route Transition Animations Guide](guide/routing/route-transition-animations) to get started.

0 commit comments

Comments
 (0)