AnimateItem Command

---

AnimateItem requires APL 1.1 or later. Provide an alternate experience for devices running older versions of APL.

Runs a fixed-duration animation sequence on one or more properties or bound values of a single component.

Properties

The AnimateItem command has the properties shown in the following table, in addition to the common command properties. Set the type property to AnimateItem.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property	Type	Default	Description
componentId	Selector	:source	The component to animate.
duration	Integer	REQUIRED	The duration of the animation (in milliseconds)
easing	linear, ease-in, …	linear	Specify an easing curve.
repeatCount	Integer	0	Number of times to repeat.
repeatMode	restart, reverse	restart	How repeated animations will play.
value	Array of animated properties	REQUIRED	An array of animated component properties.

In fast mode, the AnimateItem command jumps ahead to the end state of the animation. When an AnimateItem command stops, the animation jumps ahead to the end state; refer to repeatMode for a discussion of how to calculate the end state.

componentId

A selector that identifies the component to animate. When not provided, defaults to :source. The :source selector targets the component that issued the AnimateItem command.

duration

The duration in milliseconds of a single pass of the animation. If the repeatCount property is set to greater than 0, the total duration of the animation will be the product of the duration and one more than the repeat count. For example, the following animation will have a total duration of 10 seconds:

easing

An easing curve specifies how the value of the parameter changes over time. The curve must be a function starting at (0,0) and ending at (1,1). Two standard general ways of writing an easing curve are defined:

1. cubic-bezier(x1,y1,x2,y2): Following the CSS standard, this defines a cubic Bézier curve with starting point (0,0) and ending point (1,0). The parameterized values (x1, y1) and (x2, y2) defined the interior control points of the curve and are normally between 0 and 1.
2. path(x1,y1,...,xN,yN): A linear-piecewise function from (0,0) to (1,1). The x values must be in ascending order and between 0 and 1; the y values may be arbitrary. The end values of (0,0) and (1,1) are implicit.

The following easing curves are pre-defined:

Name	Equal to
linear	path()
ease	cubic-bezier(0.25, 0.10, 0.25, 1.00)
ease-in	cubic-bezier(0.42, 0.00, 1.00, 1.00)
ease-out	cubic-bezier(0.00, 0.00, 0.58, 1.00)
ease-in-out	cubic-bezier(0.42, 0.00, 0.58, 1.00)

The following example shows a custom easing curve.

repeatCount

The repeatCount defines how many times an animation will repeat before the command stops. By default, the repeatCount is set to 0; the animation will play through once and stop.

repeatMode

The repeatMode defines whether animations will be played from start to finish each time or if the animation will play backwards to the start each alternative time. The following repeat modes are defined:

Name	Description
restart	The animation starts over from the original value on each repeat.
reverse	The animation reverses direction each time.

The end state of an animation is a function of the repeatCount and repeatMode. If the repeatMode is reverse and the repeatCount is an odd number, the animation end state will be the same as its starting state. In all other cases the end state will be the "natural" end state assigned as the to value.

A prematurely stopped animation always "jumps" to its end state.

value

The array of animated properties. Each element in the array has the following form:

Property	Type	Required	Description
from	Number	No	The starting value of the property
property	String	Yes	The name of the property to animate
to	Number	Yes	The ending value of the property

A property animation is defined by the to/from properties or the inputRange/outputRange properties. If you don't specify a "from" value, the current value of the property is used.

There are a few special cases to consider with the transform property. First, the transform property does not implicitly define a from property; both the from and to properties must be set.

Second, interpolating between smoothly between transformations requires that the same series of transformation operations appear in the from list and the to list and in the same order. For example:

"from": [ { "translateX": 30 }, { "rotate": 90 }],
"to": [ { "translateY": 30 }, { "rotate": 45 }]

is a valid from/to transformation because each array contains a translation followed by a rotation. A non-working example:

"from": [ { "translateX": 30 }, { "scale": 1 }, { "rotate": 90 }],
"to": [ { "scale": 2 }, { "rotate": 45 }]

In this case the arrays don't match; they have different lengths and the first element differs between the arrays. The APL author may expect the system to automatically fill in the "missing" { "translateX": 0 } transformation at the start of the to array, but the APL runtime is not clever enough to automatically find and fix the difference.

Component properties you can animate

Components support animating opacity and transform properties. The from value isn't required for opacity, but you must provide it for transforms.

You can animate bound properties. The following example displays a Frame as a green box in the center of the viewport. The Frame defines an animation in which tapping the component animates the SIDE bound value. The animation changes the size and color of the Frame smoothly over one second.

Click the green box in the simulator pane to see the animation. Click a second time to see the same animation in reverse.

---

You can also animate parameters passed to a vector graphic.

The following example defines a box with a thin stroke value as a vector graphic. Tapping the vector graphic starts an animation in which the line thickness of the box expands until the box is solid. Then the animation reverses to return to the original shape.

Click the blue box in the simulator pane to see the animation.

---

Reinflation strategy

When the Reinflate command runs, the AnimateItem can resume after Alexa reinflates the document. The command resumes when it runs on a sequencer that is specified in the preservedSequencers array on Reinflate.

The following properties are saved:

• repeatCount
• value
• componentId

This is the same behavior as preserving each of these properties for the target Component. For details about preserving component properties, see the preserve property.

If the target component doesn't exist in the reinflated hierarchy or if the property does not exist, then the command is ignored.

For example, assume the following AnimateItem command is running on the EXAMPLE_SEQUENCER sequencer (t = 0 ms).

At t = 500 ms, Reinflate command runs and preserves the EXAMPLE_SEQUENCER sequencer. The document reinflates and the reinflated document has a component with the id MyComponent and bound value PROPERTY. The value for this property of MyComponent is set to 0.5 and the AnimateItem command continues to run its first iteration.

At t = 1 s, the second iteration of the command runs, setting the bound value to 0 and animating the value to 1.

---

---

Last updated: frontmatter-missing