JS: jquery spriteMe

Il y a quelque année, j’ai écris un petit plugin jQuery pour gérer des animations de sprites. A l’origine ce plugin était un petit exercice personnel pour apprendre comment fonctionne le requestAnimationFrame en javaScript. Puis j’ai pu l’utiliser sur quelques projets. Le plugin fonctionne plutôt bien mais son utilisation est progressivement devenu obsolète dans la majorité des cas avec l’arrivée des animations en CSS. Le plugin offre néanmoins des possibilités sympathiques:

• Gestion du nombre d’images par seconde
• Jouer le sprite l’envers ou à l’endroit
• Permet de boucler ou non
• Sauter directement à l’image numero X
• Play & Pause
• Supporte le pixelratio pour les images retina

Concrètement il s’agit de changer la propriété « background-image » d’un élément HTML en utilisant requestAnimationFrame.  Voici une petite démo avec le lien de téléchargement:

Utilisation

Définir une div avec width et height plus un background-image. la div affichera donc la 1er frame du sprite.

#cheval{
  width: 288px;
  height: 254px;
  background-image: url(../images/cheval.jpg);
}
          

Puis ajoutez jQuery et le plugin spriteMe.

<script src="//code.jquery.com/jquery-1.11.2.min.js"></script>      
<script src="js/libs/jquery.spriteme.js" type="text/javascript"></script>   

Enfin, initialisez le plugin.

$(function() {   
  $("#cheval").spriteMe();
});

Ici la demo utilise les paramètres suivants:

//pour le css : width: 144px;height: 127px;
//et pour le JS
$("#cheval").spriteMe({
  loop:true,
  fps: 12,
  pixelratio: 2,
});

Options

Le plugin possède plusieurs options. Voici la liste avec les valeurs par défaut.
Remarque :Le plugin compte les images à partir de 0.

$(function() {  
  $("#cheval").spriteMe({
    fps: 12,
    loop: false,
    autoplay: true,
    gotoframe: false,
    reverse: false,
    maxframe: false, 
    pixelratio: 0,
    complete: function(){  
      console.log('This is the end.');
    }
});

• fps: Le nombre d’image par seconde. INT
• loop: L’animation doit-elle jouer en boucle? BOOLEAN
• autoplay: Faut-il vraiment l’expliquer? BOOLEAN
• gotoframe: Permet de sauter directement à une image. La première image est 0. INT
• reverse: Joue l’animation à l’envers. BOOLEAN
• maxframe: Défini l’image de fin de l’animation. Maxframe compte a partir de 0 (voir la fin de la page). Mettre sur FALSE pour désactiver. INT ou BOOLEAN
• pixelratio: Défini si la taille du sprite est X fois plus grande que la taille du container ( Pour les device dont le pixelratio est supérieur à 1 )
• complete: Exécute un bloc de code quand l’animation arrive à la fin ET que loop = false.

Méthodes | API

Les méthodes peuvent étre appellées pendant la lecture de l’animation, ou non.

//les deux méthodes ne sont pas identiques, play() est a utiliser après un stop(). Si loop = false et que l'animation est arrivée au bout; alors il faut utiliser resume().
  $("#cheval").spriteMe("play");
  $("#cheval").spriteMe("resume");
  
  // stop l'animation
  $("#cheval").spriteMe("stop");
  
  //relance l'animation depuis le debut
  $("#cheval").spriteMe("restart");
  
  //change les fps : INT
  $("#cheval").spriteMe("fps",30);
  
  //saute vers la frame : INT
  $("#cheval").spriteMe("gotoframe",30);

  // inverse le sens de lecture du sprite
  $("#cheval").spriteMe("reverse");

  // inverse le sens de lecture du sprite
  $("#cheval").spriteMe("setreversestate", false);

  // change le nombre de frame de l'animation INT
  $("#cheval").spriteMe("setmaxframe",42);

  // supprime la limitation de frame: BOOLEAN
  $("#cheval").spriteMe("setmaxframe",false);
  
  // change l'etat de la répétition automatique BOOLEAN
  $("#cheval").spriteMe("setloop",false);

Le fichier image

Le fichier image peut avoir une ou plusieurs colonnes, peut importe. le sprite sera affiché de gauche à droite, ligne par linge. Le plugin calcule seul les démentions de l’image et donc le nombre de frame total dans l’animation.

Ici, notre image peut contenir 15 frame. Mais notre animation n’en possède que 14. Il faut donc utiliser maxframe.
Attention: maxframe compte a partir de 0. Il faudra donc définir maxframe sur 13 et non pas 14.