Animation

Simple Animation

The most common use-case for character animation is animating character strokes in order, so CdlUtils.Animator is designed to make that task simple. Below is an example animating the strokes of the character 我 in a loop:

CdlUtils.Animator.animateCharacter('target-element-id', '我', {
  width: 200, // px
  height: 200, // px
  apiKey: 'your-api-key',
  loopAnimation: true
});

In this case, the HTML would look like:

<div id="target-element-id"></div>

And here's what it looks like in action:

While animating each stroke you can also modify their SVG styles by passing in an animateStyles object with start and end objects containing the properties you want to transition. For example, we can create a subtle ink drying effect by transitioning the fill of each stroke as its being drawn from black to gray like below:

CdlUtils.Animator.animateCharacter('target-element-id', '我', {
  width: 200, // px
  height: 200, // px
  apiKey: 'your-api-key',
  loopAnimation: true,
  // ink drying effect
  animateStyles: {
    start: {
      fill: '#111'
    },
    end: {
      fill: '#494949'
    }
  }
});

And here's what it looks like in action:

You can control how fast or slow the character animates as well as tweaking any other SVG styles you'd like. For more info on all the available options to the CdlUtils.Animator.animateCharacter method check out the CdlUtils.Animator API docs

Animating individual strokes

If you need more control over each stroke than is provided by CdlUtils.Animator.animateCharacter you can instantiate a CdlUtils.Animator instance and manage each stroke's animation yourself. Each CdlUtils.Animator instance contains a strokes array of CdlUtils.StrokeAnimator instances which you can use to animate and control each stroke individually as needed. For instance, if you'd like to animate a specific stroke, you could do something like the following:

// create a new CdlUtils.Animator instance
var animator = new CdlUtils.Animator('target-element-id', {
  width: 200, // px
  height: 200, // px
  apiKey: 'your-api-key'
});
// load a character
animator.renderCharacter('我').then(function() {
  // show the rendered character
  animator.show();
  // make the character blue
  animator.setStrokeStyles({ fill: '#008CBA' });

  // animate the second stroke in this character
  animator.strokes[3].animate({
    animateStyles: {
      start: {
        fill: '#00C0FF' // highlightwhile drawing
      },
      end: {
        fill: '#008CBA'
      }
    },
    strokeAnimationVelocity: 0.3 // animate slowly
  });
});

Try it out:

The code above is a bit more complicated than the just animating the whole chracter, but it gives a lot more control as well. First, we created a new CdlUtils.Animator instance. When, we needed to load and render the character 我. This returned a promise which resolves when the animater has loaded the character and is ready to go. In that promise, we first show the character (by default the chracter renders to the screen hidden). Then, we made the whole character blue via the setStrokeStyles method, and then animate the fourth stroke from the strokes array. We slowed down the animation velocity of the stroke and tweened the stroke fill color while animating.

For more info on all the available methods and parameters you can use check out the API docs for CdlUtils.Animator and CdlUtils.StrokeAnimator

Accessing raw SVG

If you want still more control you can access the underlying SVG DOM nodes themselves in each individual stroke. You can use these references to tweak the SVG to your liking, or add event listeners, or anything else that SVG allows you to do. For instance, we can add click event listeners to each stroke and then animate the stroke when it's clicked.

// create a new CdlUtils.Animator instance
var animator = new CdlUtils.Animator('target-element-id', {
  width: 200, // px
  height: 200, // px
  apiKey: 'your-api-key'
});
// load a character
animator.renderCharacter('我').then(function() {
  // show the rendered character
  animator.show();

  // add click handlers to each stroke
  animator.strokes.forEach(function(stroke) {
    var pathSvgNode = stroke.path;
    pathSvgNode.addEventListener('click', function() {
      stroke.animate();
    });
  });
});

Try clicking on the strokes below: