Documentation

Original: http://spritely.net/documentation/

Joyeux est un plugin simple avec seulement deux méthodes principales, sprite() et pan() les deux dont simplement animent la propriété css background-image d’un élément. La différence entre les deux est qu’une image « sprite » contient deux ou plusieurs « cadres » de l’animation, alors qu’une « casserole » image contient une image continue quelles casseroles à gauche ou à droite et puis répète. En général, dans les deux cas, vous utiliserez un fichier png (avec ou sans transparence) pour cela. Vous souhaitez utiliser un gif transparent pour Internet Explorer 6, bien qu’il ne sera pas sans doute chercher aussi bon. Vos éléments html doivent déjà être à la bonne taille que vous voulez le sprite à comparaître, mais l’image d’arrière-plan sera généralement plus grand que l’élément html, et les méthodes vive repositionner l’image d’arrière-plan dans l’élément html.
Pour la documentation dans des langues autres que l’anglais, s’il vous plaît voir Documentation Unoffical.
Démarrage rapide
Si vous êtes impatient d’essayer Spritely et voulez voir quelques exemples de travail autonome, vous pouvez télécharger un exemple 0,4 de code comme un fichier zip.
Quoi de neuf dans la version 0.6 ?
Animation d’une image avec la méthode « sprite() »
Voici un petit exemple pour vous aider à démarrer… La méthode suivante anime l’un de l’oiseau « sprites » voler autour de cette page. Le « sprite » est composé de trois images dans une image png transparent, chaque image est côte à côte :
Maintenant, nous avons simplement besoin de créer un div appelé « oiseau », style ça a exactement la bonne taille (180 x 180 pixels dans ce cas) et l’animer avec la méthode sprite(). Les deux options, que nous devons utiliser sont “fps” (frames per second) et « no_of_frames », par exemple trois cadres pour l’image ci-dessus :

$('#bird').sprite({fps: 12, no_of_frames: 3});
Pour rendre la souris attirer le sprite, lorsque vous cliquez sur l’écran, utilisez ceci :
$('#bird').sprite({fps: 12, no_of_frames: 3}).activeOnClick().active();
$('body').flyToTap();
La méthode active() rend ce sprite sprite actif sur lancement sinon un sprite avec activeOnClick() devient actif uniquement lorsque vous cliquez dessus (ou le toucher à l’aide d’un iPhone/iPad).
Montres de la méthode $(‘body’).flyToTap() pour un clic sur la page à quel point, après que tout déplacement actuel est terminé, le sprite se déplace vers l’endroit cliqué. Après quelques seconde, si une méthode de mouvement aléatoire a été appliquée (voir ci-dessous), elle puis s’éloigne à nouveau.
Pour faire le sprite à bouger de manière aléatoire, au sein de contraintes de pixel (les vitesses sont en millisecondes), utilisez ceci :
$('#bird')
      .sprite({fps: 8, no_of_frames: 3})
      .spRandom({
          top: 70,
          left: 100,
          right: 200,
          bottom: 340,
          speed: 4000,
          pause: 3000
      });
Panoramique une image d’arrière-plan avec la méthode « pan() »
Voici comment vous pouvez « pan » une image de fond, comme les collines dans la démo en haut de cette page :

Pour rendre l’image d’arrière-plan pan continuellement vers la gauche, créez un élément div html plus petit que l’image elle-même et l’utilisation de css pour placer votre image comme image d’arrière-plan, veillant à ce que vous définissez l’image d’arrière-plan répète « horizontale », par exemple il répète continuellement dans l’axe horizontal.
Maintenant animer avec vive s méthode « pan() » :

$('#trees').pan({fps: 30, speed: 2, dir: 'left'});
Vous pouvez régler la vitesse (pixels par image) et les images par seconde, indépendamment l’un de l’autre. Pourquoi ? Car une vitesse inférieure se traduira par un pan plus lisse, cependant un supérieur images par seconde peuvent entraîner une exécution plus lente (surtout sur les appareils comme l’iPhone). Vous aurez besoin d’expérimenter pour obtenir le bon équilibre entre animation fluide et les performances de la page.
Pour des images de fond de la couche sur l’autre, simplement placer les images html au-dessous de l’autre, ou ajuster la propriété « z-index », puis définissez les propriétés de fps et de vitesse pour donner l’illusion de profondeur. Une image de fond plus éloignée doit se déplacer plus lentement (plus faible fps) qu’un gros plan.
Quoi de neuf dans la version 0.6 ?
Nous sommes enthousiastes de la version 0.6. Pourquoi ? Parce que Spritely a maintenant des événements !
Vive 0,6 introduit la possibilité d’appeler une fonction lorsqu’un sprite atteint le premier, dernier ou tout autre cadre. Trois nouvelles options sont introduites pour cela : on_first_frame, on_last_frame et on_frame. C’est extrêmement utile, car cela signifie que vous pouvez changer le « état » d’un sprite sur n’importe quelle image donnée, ou arrêter l’animation tout à fait.
Voici un exemple :
$('#sprite').sprite({
    fps: 9, 
    no_of_frames: 24, 
    on_first_frame: function(obj) {
        obj.spState(1); // change to state 1 (first row) on frame 1
    }, 
    on_last_frame: function(obj) {
        obj.spStop(); // stop the animation on the last frame
    },
    on_frame: { // note - on_frame is an object not a function
        8: function(obj) { // called on frame 8
            obj.spState(2); // change to state 2 (row 2) on frame 8
        },
        16: function(obj) { // called on frame 16
            obj.spState(3); // change to state 3 (row 3) on frame 16
        }
    }
});
Également nouveau à 0,6 :
Vous pouvez maintenant indiquer un sprite pour commencer à jouer sur une trame particulière :

$('#sprite').sprite({fps: 9, no_of_frames: 24, start_at_frame: 8});
Ce qui est nouveau dans la version 0.5 ?
Nouvelle méthode : destroy()
Vive 0,5 introduit la méthode destroy(). Cela réinitialise un élément tout à fait et il supprime toute animation.
Par exemple,
$('#balloons').destroy();
Ce qui était nouveau dans la version 0.4 ?
Deux nouvelles fonctionnalités sont disponibles dans la version 0.4 :
Panoramique vertical
Le panoramique vertical tant attendu est maintenant disponible. Cela signifie que vous pouvez spécifier « up » ou « down » comme indications lors de l’appel pan().
Par exemple,

$('#balloons').pan({fps: 30, speed: 3, dir: 'up', depth: 70});
Animer des sprites en arrière
Il est maintenant possible de jouer un sprite en sens inverse (par exemple rebobinage). Ceci est réalisé avec l’option « rewind ». Par exemple,
    $('#bird')
        .sprite({fps: 1, no_of_frames: 3, rewind: true})
        .spRandom({top: 50, bottom: 200, left: 300, right: 320})
        .isDraggable()
        .activeOnClick()
        .active();
Changer les images par seconde
Vous pouvez maintenant modifier les images par seconde avec la méthode fps() :
$('#bird').fps(30);
$('#hills').fps(12);
Changement de vitesses de fond par rapport à leur profondeur
Maintenant que nos milieux ont une profondeur, nous pouvons facilement changer leur vitesse, par rapport à l’autre avec la méthode $.spRelSpeed().
Placez le curseur dans la démo ci-dessus pour vérifier la profondeur de l’effet sur la vitesse des objets de l’arrière-plan, en le comparant avec cette image :

Depth explained

Pour changer le fond des vitesses relativement, allient toutes les compétences dans un sélecteur jQuery simple et utilisent la méthode spRelSpeed() :

$('#clouds, #hills').spRelSpeed(30);
lorsque la valeur de « spRelSpeed » est le nombre de pixels pour se déplacer, par image, étant donné que c’est par rapport à la profondeur de l’élément. Ainsi spRelSpeed(30), appliqué à un objet à profondeur 100 se déplacera l’objet à 30 pixels par image. Appliqué à un objet à profondeur 50, que l’objet se déplace à 15 pixels par image. Vous pouvez modifier les images par secondes séparément voir ci-dessus.
Changement de vitesse de fond absolument
La méthode $.spSpeed() permet de modifier une vitesse fond absolument (ce qui équivaut à une profondeur de 100) :
$('#hills').spSpeed(20);
Une fois de plus, la valeur de la vitesse est le nombre de pixels pour le déplacer, par image.
Changement de direction d’animations d’arrière-plan
Les méthodes spChangeDir(‘left’) ou spChangeDir(‘right’) peuvent servir sur une animation d’arrière-plan à changer de direction gauche ou droite respectivement :
$('#hills').spChangeDir('left'); // change background direction left (travel right!)
$('#hills').spChangeDir('right'); // change background direction right (travel left!)
Changement de direction ou « état » d’animations sprite
Pour modifier la direction de sprites, vous devez utiliser une méthode différente, $.spState(), et vous avez besoin d’une image différente, avec plusieurs lignes de trames, une ligne pour chaque État, conformément à l’exemple suivant :

Two-state sprite image

La deuxième rangée (battant en arrière) représente la deuxième « État » du sprite et que vous modifiez donc sa direction avec :
$('#bird').spState(2); // fly backwards (row 2 of the sprite)
$('#bird').spState(1); // fly forwards (row 1 of the sprite)
Arrêt et le démarrage des animations
Pour arrêter et démarrer les animations sprite et arrière-plan, utilisez les méthodes spStop(), spStart() et spToggle() :
$('#bird').spStop(); // stop a sprite or background animation at the current frame
$('#bird').spStop(true); // stop a sprite or background animation, returning to frame 1
$('#bird').spStart(); // start a sprite or background animation
$('#bird').spToggle(); // toggle a sprite or background animation on or off
Faire un sprite déplaçable
La méthode isDraggable() permet un sprite à être déplacés vers un point quelconque de l’écran. Il y a aussi trois paramètres qui peuvent être utilisés avec cette méthode ; start, stop, et drag. Ces rappels en option seront déclenche dès le début, fin, ou alors que vous faites glisser l’élément. Voir l’exemple ci-dessous :
$('#bird').isDraggable({
    start: function() {
        // Fade sprite to 70% opacity when at the start of the drag
        $('#bird').fadeTo('fast', 0.7);
    },
    stop: function() {
        // Return sprite to 100% opacity when finished
        $('#bird').fadeTo('fast', 1);
    },
    drag: function() {
        // This event will fire constantly whilst the object is being dragged
    }
});
Veuillez noter que la méthode de isDraggable() exige jQueryUI.
Combinant des actions visant à produire une seule action
Vous pouvez bien sûr combiner les actions dans une seule méthode, afin que vous pouvez contrôler le mouvement de votre ensemble de la scène. Le code suivant, par exemple, définit une méthode « fly_forwards_quickly() » qui vous pouvez de contrôler d’un simple clic :
var fly_quickly_forwards = function() {
    $('#bird')
        .fps(20)
        .spState(1);
    $('#clouds, #hills')
        .spRelSpeed(30)
        .spChangeDir('left');
};
Notez qu’il est recommandé de construire toutes vos méthodes en un seul objet plutôt que de créer des variables de page, cependant, nous incluons l’exemple ci-dessus par souci de simplicité.
Faisant un jeu de sprite pour un nombre fixe d’images
Une autre méthode de nouveau disponible dans la version 0.2, si ne pas démontré dans la démo, est la possibilité de créer un sprite qui joue pour un nombre fixe d’images et puis s’arrête :
// play a sprite for a maximum of 30 frames
$('#my_sprite').sprite({fps: 9, no_of_frames: 3, play_frames: 30});
Plus d’exemples
On trouvera des exemples de code plus en lisant le code source de cette page et n’oubliez pas vous pouvez combiner Spritely avec d’autres méthodes de jQuery pour produire des animations complexes.
WordPress
Nous avons implimented Spritely dans TwentyEleven WordPress thème par défaut comme un exemple pour montrer comment vous pouvez ajouter Spritely à vos thèmes WordPress personnalisés.
Un dernier mot de prudence…
Utilisez Spritely avec modération. Spritely un peu va un long chemin, mais trop ambitieuse utilisation de ces techniques peut entraîner des performances médiocres, surtout sur les appareils mobiles. Un petit mouvement sur une grande page peut-être mieux que beaucoup de mouvement sur un petit. S’il vous plaît tester Spritely soigneusement votre auditoire/plates-formes cibles avant que vous développez votre site comme les performances peuvent varier de plateforme en plateforme.
Documentation non officielle
Nous avons la liste des documents officieux et ressources ici. Cela inclut aussi les traductions des documents officiels.