Tween object
Tween any object deeply while disregarding non numeric values
Example
Basic Usage
Give any equivilant primitive (same type) or object (same structure) as from an to parameter. Objects will be recursively parsed and every found number will be interpolated. Any non numeric values will be ignored.
let from = 0let to = 100// optional: let duration = 1let x let tween = from to duration easing
Easing must be given as a function recieving a number between 0
and 1
and returning one between 0
and 1
. To generate such functions from bezier easing declarations programatically, have a look at bezier-easing.
You can control a tween instance via update(at?: number)
. at
spans from 0 to duration
, thus in this case 0 .. 1. Parameters exceeding this limit will be kept at the maximum.
When omiting the at
parameter, the time delta from the inital update will be taken to calculate the progress.
Results can be recieved directly as returned property on the update call, or via a registered onUpdate
listener. The unregister call offUpdate(func)
.
tween console
To use Tween object as an animation interpolator use animation-frame-delta as animation loop handler, as it has been extensively tested to work well in combination.
let from = 250let to = 500let duration = 1000let tween = from to duration // or the more cool but less readable version
Advanced Options
Instead of the shortcuts duration and easing, a object containing more advanced options can be given.
let opions = start: 0 end: 1 a iterations: 1 fill: true let tween = from to options
The values displayed above are the defaults, you may omit any of the properties to fall back to these values.
The used config can be read like so
Note that this is a readonly object. You are unable to change an instantiated tween.
let usedOptions = tweenoptions console
These are the given options merged with the default config. This is potentually interesting if youd like to rely on the built in option resolution of tween object as it supports duration
& easing
as standalone properties.
Multiple Keyframes
To interpolate over multiple keyframes set the first constructor argument to true and give a list of keyframes as second.
let multipleKeyframes = truelet keyframes = prop: 100 offset: 0 prop: 250 offset: 3 prop: 300 prop: 500 offset: 1 let tween = multipleKeyframes keyframes
The offset property on a keyframes indecates the position in the animation (0 beeing the begin and 1 the end), similar to the WAAPI implementation. Offset can be omit as it will be filled by equally distributed values (thus, 0.65
for the above example).
Side Note: Single property keyframes can be given not nested inside a explicit object. This notation (useing wrapped primitives) works as well
let multipleKeyframes = truelet specialPropWithOffset = 250specialPropWithOffsetoffset = 3let keyframes = 100 specialPropWithOffset 300 500 let tween = multipleKeyframes keyframes
Extention
A use case for Tween object could be the interpolation of svg paths. There is already a library with a more polished implementation of what will be shown here (tween-svg-path) out there, but for the sake of getting familiar with the concept I will stick to this use case.
As you want to abstract the inner workings of tweening as far as possible, in order to give the user / developer using it an as easy to understand as possible interface to work with, we will now absract the parsing from the svg-path string to a interpolatable object structure.
Note: the actual parsing to an object structure will be done by the libraries parse-svg-path, abs-svg-path and normalize-svg-path.
Note: This example uses typescript to display the point of parsing better.
// The default export (TweenObject) used in the last examples is an implementation of the abstract class Tween without any parsing.
This way TweenSvgPath
can be interacted with just by using svgpaths, and never having to parse anything manually.
animationFrameDeltatween.update.bindtween, duration // Note to select to pathtween.onUpdate
Conribute
All feedback is appreciated. Create an pull request or write an issue.