Feat(docs) translate guide/animations/transition-and-triggers

adev-ja/src/content/guide/animations/transition-and-triggers.en.md

@@ -0,0 +1,304 @@
+# Animation transitions and triggers
+
+IMPORTANT: The `@angular/animations` package is now deprecated. The Angular team recommends using native CSS with `animate.enter` and `animate.leave` for animations for all new code. Learn more at the new enter and leave [animation guide](guide/animations). Also see [Migrating away from Angular's Animations package](guide/animations/migration) to learn how you can start migrating to pure CSS animations in your apps.
+
+This guide goes into depth on special transition states such as the `*` wildcard and `void`. It shows how these special states are used for elements entering and leaving a view.
+This section also explores multiple animation triggers, animation callbacks, and sequence-based animation using keyframes.
+
+## Predefined states and wildcard matching
+
+In Angular, transition states can be defined explicitly through the [`state()`](api/animations/state) function, or using the predefined `*` wildcard and `void` states.
+
+### Wildcard state
+
+An asterisk `*` or _wildcard_ matches any animation state.
+This is useful for defining transitions that apply regardless of the HTML element's start or end state.
+
+For example, a transition of `open => *` applies when the element's state changes from open to anything else.
+
+<img alt="wildcard state expressions" src="assets/images/guide/animations/wildcard-state-500.png">
+
+The following is another code sample using the wildcard state together with the previous example using the `open` and `closed` states.
+Instead of defining each state-to-state transition pair, any transition to `closed` takes 1 second, and any transition to `open` takes 0.5 seconds.
+
+This allows the addition of new states without having to include separate transitions for each one.
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="trigger-wildcard1"/>
+
+Use a double arrow syntax to specify state-to-state transitions in both directions.
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="trigger-wildcard2"/>
+
+### Use wildcard state with multiple transition states
+
+In the two-state button example, the wildcard isn't that useful because there are only two possible states, `open` and `closed`.
+In general, use wildcard states when an element has multiple potential states that it can change to.
+If the button can change from `open` to either `closed` or something like `inProgress`, using a wildcard state could reduce the amount of coding needed.
+
+<img alt="wildcard state with 3 states" src="assets/images/guide/animations/wildcard-3-states.png">
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="trigger-transition"/>
+
+The `* => *` transition applies when any change between two states takes place.
+
+Transitions are matched in the order in which they are defined.
+Thus, you can apply other transitions on top of the `* => *` transition.
+For example, define style changes or animations that would apply just to `open => closed`, then use `* => *` as a fallback for state pairings that aren't otherwise called out.
+
+To do this, list the more specific transitions _before_ `* => *`.
+
+### Use wildcards with styles
+
+Use the wildcard `*` with a style to tell the animation to use whatever the current style value is, and animate with that.
+Wildcard is a fallback value that's used if the state being animated isn't declared within the trigger.
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="transition4"/>
+
+### Void state
+
+Use the `void` state to configure transitions for an element that is entering or leaving a page.
+See [Animating entering and leaving a view](guide/legacy-animations/transition-and-triggers#aliases-enter-and-leave).
+
+### Combine wildcard and void states
+
+Combine wildcard and void states in a transition to trigger animations that enter and leave the page:
+
+- A transition of `* => void` applies when the element leaves a view, regardless of what state it was in before it left
+- A transition of `void => *` applies when the element enters a view, regardless of what state it assumes when entering
+- The wildcard state `*` matches to _any_ state, including `void`
+
+## Animate entering and leaving a view
+
+This section shows how to animate elements entering or leaving a page.
+
+Add a new behavior:
+
+- When you add a hero to the list of heroes, it appears to fly onto the page from the left
+- When you remove a hero from the list, it appears to fly out to the right
+
+<docs-code header="hero-list-enter-leave.ts" path="adev/src/content/examples/animations/src/app/hero-list-enter-leave.ts" region="animationdef"/>
+
+In the preceding code, you applied the `void` state when the HTML element isn't attached to a view.
+
+## Aliases :enter and :leave
+
+`:enter` and `:leave` are aliases for the `void => *` and `* => void` transitions.
+These aliases are used by several animation functions.
+
+```ts {hideCopy}
+
+transition ( ':enter', [ … ] ); // alias for void => _
+transition ( ':leave', [ … ] ); // alias for _ => void
+
+```
+
+It's harder to target an element that is entering a view because it isn't in the DOM yet.
+Use the aliases `:enter` and `:leave` to target HTML elements that are inserted or removed from a view.
+
+### Use `*ngIf` and `*ngFor` with :enter and :leave
+
+The `:enter` transition runs when any `*ngIf` or `*ngFor` views are placed on the page, and `:leave` runs when those views are removed from the page.
+
+IMPORTANT: Entering/leaving behaviors can sometime be confusing.
+As a rule of thumb consider that any element being added to the DOM by Angular passes via the `:enter` transition. Only elements being directly removed from the DOM by Angular pass via the `:leave` transition. For example, an element's view is removed from the DOM because its parent is being removed from the DOM.
+
+This example has a special trigger for the enter and leave animation called `myInsertRemoveTrigger`.
+The HTML template contains the following code.
+
+<docs-code header="insert-remove.html" path="adev/src/content/examples/animations/src/app/insert-remove.html" region="insert-remove"/>
+
+In the component file, the `:enter` transition sets an initial opacity of 0. It then animates it to change that opacity to 1 as the element is inserted into the view.
+
+<docs-code header="insert-remove.ts" path="adev/src/content/examples/animations/src/app/insert-remove.ts" region="enter-leave-trigger"/>
+
+Note that this example doesn't need to use [`state()`](api/animations/state).
+
+## Transition :increment and :decrement
+
+The `transition()` function takes other selector values, `:increment` and `:decrement`.
+Use these to kick off a transition when a numeric value has increased or decreased in value.
+
+HELPFUL: The following example uses `query()` and `stagger()` methods.
+For more information on these methods, see the [complex sequences](guide/legacy-animations/complex-sequences) page.
+
+<docs-code header="hero-list-page.ts" path="adev/src/content/examples/animations/src/app/hero-list-page.ts" region="increment"/>
+
+## Boolean values in transitions
+
+If a trigger contains a Boolean value as a binding value, then this value can be matched using a `transition()` expression that compares `true` and `false`, or `1` and `0`.
+
+<docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/open-close.2.html" region="trigger-boolean"/>
+
+In the code snippet above, the HTML template binds a `<div>` element to a trigger named `openClose` with a status expression of `isOpen`, and with possible values of `true` and `false`.
+This pattern is an alternative to the practice of creating two named states like `open` and `close`.
+
+Inside the `@Component` metadata under the `animations:` property, when the state evaluates to `true`, the associated HTML element's height is a wildcard style or default.
+In this case, the animation uses whatever height the element already had before the animation started.
+When the element is `closed`, the element gets animated to a height of 0, which makes it invisible.
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.2.ts" region="trigger-boolean"/>
+
+## Multiple animation triggers
+
+You can define more than one animation trigger for a component.
+Attach animation triggers to different elements, and the parent-child relationships among the elements affect how and when the animations run.
+
+### Parent-child animations
+
+Each time an animation is triggered in Angular, the parent animation always gets priority and child animations are blocked.
+For a child animation to run, the parent animation must query each of the elements containing child animations. It then lets the animations run using the [`animateChild()`](api/animations/animateChild) function.
+
+#### Disable an animation on an HTML element
+
+A special animation control binding called `@.disabled` can be placed on an HTML element to turn off animations on that element, as well as any nested elements.
+When true, the `@.disabled` binding prevents all animations from rendering.
+
+The following code sample shows how to use this feature.
+
+<docs-code-multifile>
+    <docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/open-close.4.html" region="toggle-animation"/>
+    <docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.4.ts" region="toggle-animation" language="typescript"/>
+</docs-code-multifile>
+
+When the `@.disabled` binding is true, the `@childAnimation` trigger doesn't kick off.
+
+When an element within an HTML template has animations turned off using the `@.disabled` host binding, animations are turned off on all inner elements as well.
+You can't selectively turn off multiple animations on a single element.<!-- vale off -->
+
+A selective child animations can still be run on a disabled parent in one of the following ways:
+
+- A parent animation can use the [`query()`](api/animations/query) function to collect inner elements located in disabled areas of the HTML template.
+Those elements can still animate.
+<!-- vale on -->
+
+- A child animation can be queried by a parent and then later animated with the `animateChild()` function
+
+#### Disable all animations
+
+To turn off all animations for an Angular application, place the `@.disabled` host binding on the topmost Angular component.
+
+<docs-code header="app.ts" path="adev/src/content/examples/animations/src/app/app.ts" region="toggle-app-animations"/>
+
+HELPFUL: Disabling animations application-wide is useful during end-to-end \(E2E\) testing.
+
+## Animation callbacks
+
+The animation `trigger()` function emits _callbacks_ when it starts and when it finishes.
+The following example features a component that contains an `openClose` trigger.
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="events1"/>
+
+In the HTML template, the animation event is passed back via `$event`, as `@triggerName.start` and `@triggerName.done`, where `triggerName` is the name of the trigger being used.
+In this example, the trigger `openClose` appears as follows.
+
+<docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/open-close.3.html" region="callbacks"/>
+
+A potential use for animation callbacks could be to cover for a slow API call, such as a database lookup.
+For example, an **InProgress** button can be set up to have its own looping animation while the backend system operation finishes.
+
+Another animation can be called when the current animation finishes.
+For example, the button goes from the `inProgress` state to the `closed` state when the API call is completed.
+
+An animation can influence an end user to _perceive_ the operation as faster, even when it is not.
+
+Callbacks can serve as a debugging tool, for example in conjunction with `console.warn()` to view the application's progress in a browser's Developer JavaScript Console.
+The following code snippet creates console log output for the original example, a button with the two states of `open` and `closed`.
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="events"/>
+
+## Keyframes
+
+To create an animation with multiple steps run in sequence, use _keyframes_.
+
+Angular's `keyframe()` function allows several style changes within a single timing segment.
+For example, the button, instead of fading, could change color several times over a single 2-second time span.
+
+<img alt="keyframes" src="assets/images/guide/animations/keyframes-500.png">
+
+The code for this color change might look like this.
+
+<docs-code header="status-slider.ts" path="adev/src/content/examples/animations/src/app/status-slider.ts" region="keyframes"/>
+
+### Offset
+
+Keyframes include an `offset` that defines the point in the animation where each style change occurs.
+Offsets are relative measures from zero to one, marking the beginning and end of the animation. They should be applied to each of the keyframe steps if used at least once.
+
+Defining offsets for keyframes is optional.
+If you omit them, evenly spaced offsets are automatically assigned.
+For example, three keyframes without predefined offsets receive offsets of 0, 0.5, and 1.
+Specifying an offset of 0.8 for the middle transition in the preceding example might look like this.
+
+<img alt="keyframes with offset" src="assets/images/guide/animations/keyframes-offset-500.png">
+
+The code with offsets specified would be as follows.
+
+<docs-code header="status-slider.ts" path="adev/src/content/examples/animations/src/app/status-slider.ts" region="keyframesWithOffsets"/>
+
+You can combine keyframes with `duration`, `delay`, and `easing` within a single animation.
+
+### Keyframes with a pulsation
+
+Use keyframes to create a pulse effect in your animations by defining styles at specific offset throughout the animation.
+
+Here's an example of using keyframes to create a pulse effect:
+
+- The original `open` and `closed` states, with the original changes in height, color, and opacity, occurring over a timeframe of 1 second
+- A keyframes sequence inserted in the middle that causes the button to appear to pulsate irregularly over the course of that same 1 second timeframe
+
+<img alt="keyframes with irregular pulsation" src="assets/images/guide/animations/keyframes-pulsation.png">
+
+The code snippet for this animation might look like this.
+
+<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.1.ts" region="trigger"/>
+
+### Animatable properties and units
+
+Angular animations support builds on top of web animations, so you can animate any property that the browser considers animatable.
+This includes positions, sizes, transforms, colors, borders, and more.
+The W3C maintains a list of animatable properties on its [CSS Transitions](https://www.w3.org/TR/css-transitions-1) page.
+
+For properties with a numeric value, define a unit by providing the value as a string, in quotes, with the appropriate suffix:
+
+- 50 pixels:
+  `'50px'`
+
+- Relative font size:
+  `'3em'`
+
+- Percentage:
+  `'100%'`
+
+You can also provide the value as a number. In such cases Angular assumes a default unit of pixels, or `px`.
+Expressing 50 pixels as `50` is the same as saying `'50px'`.
+
+HELPFUL: The string `"50"` would instead not be considered valid\).
+
+### Automatic property calculation with wildcards
+
+Sometimes, the value of a dimensional style property isn't known until runtime.
+For example, elements often have widths and heights that depend on their content or the screen size.
+These properties are often challenging to animate using CSS.
+
+In these cases, you can use a special wildcard `*` property value under `style()`. The value of that particular style property is computed at runtime and then plugged into the animation.
+
+The following example has a trigger called `shrinkOut`, used when an HTML element leaves the page.
+The animation takes whatever height the element has before it leaves, and animates from that height to zero.
+
+<docs-code header="hero-list-auto.ts" path="adev/src/content/examples/animations/src/app/hero-list-auto.ts" region="auto-calc"/>
+
+### Keyframes summary
+
+The `keyframes()` function in Angular allows you to specify multiple interim styles within a single transition. An optional `offset` can be used to define the point in the animation where each style change should occur.
+
+## More on Angular animations
+
+You might also be interested in the following:
+
+<docs-pill-row>
+  <docs-pill href="guide/legacy-animations" title="Introduction to Angular animations"/>
+  <docs-pill href="guide/legacy-animations/complex-sequences" title="Complex animation sequences"/>
+  <docs-pill href="guide/legacy-animations/reusable-animations" title="Reusable animations"/>
+  <docs-pill href="guide/routing/route-transition-animations" title="Route transition animations"/>
+  <docs-pill href="guide/animations/migration" title="Migrating to Native CSS Animations"/>
+</docs-pill-row>