sprite.js é uma pequena, mas poderosa biblioteca JavaScript para animações baseadas em sprites.
Criando animações
Animações em AM são manipuladas com uma instância de AM.Sprite - Uma classe que manipula uma grande imagem que contém todos os quadros da animação.
O número do quadro de um AM.Sprite começa em 1 no canto superior esquerdo e continua em sentido de leitura horizontal ou vertical.
Para criar uma instância de AM.Sprite, você especifica um elemento html onde poderá também definir propriedades de animação (e.g. data-fps*, data-totalFrames, data-currentFrame, data-vertical, data-tileW, data-tileH, data-columns* e data-rows*):
HTML
<div class="mushroom" data-totalFrames="14" data-columns="5" data-rows="3"> </div><!--/mushroom-->
Este elemento deve ser formatado com o sprite (background), e opcionalmente a altura (height) e largura (width) para cada quadro da imagem via css e.g.:
CSS
.mushroom {
background: url("mushroom.png") no-repeat 0 -10px;
width: 189px; /* deixa opcional o uso de tileW */
height: 233px; /* deixa opcional o uso de tileH */
}
Você deve também espeficar seu comportamento, fazendo uso de AM.Sprite que espera dois argumentos, o primeiro é um objeto DOM, que é o nosso html já interpretado pelo browser e o segundo um objeto com uma série de opções i.e.:
JavaScript
{
fps: 24, // Frames Per Second.
totalFrames: 1, // O número total de quadros no sprite.
currentFrame: 1, // O quadro onde começará a animação.
vertical: false, // Leitura vertical ou horizontal
tileW: 0, // A largura de um único frame do sprite.
tileH: 0, // A altura de um único frame do sprite.
columns: 0, // O número de colunas no sprite.
rows: 0 // O número de linhas no sprite.
}
Quando você cria um AM.Sprite, e entrega um objeto HTMLElement, e algumas informações sobre o sprite, isso dá todo o controle do sprite e torna possível sua animação e.g.:
JavaScript
// Cria uma instância de AM.Sprite com o arquivo mushroom.png
// que possui 189x233 pixels em cada quadro definido no css. O sprite
// possui 5 colunas de quadros na horizontal e 3 na vertical com
// apenas 14 quadros de animação especificados no html via dataset.
// Também foi declarado 32 quadros por segundo em nossa instância.
var mushroom = new AM.Sprite(document.querySelector('.mushroom'), { fps: 32 });
// Roda a animação até o final, que, quando chega no último
// quadro, volta para o primeiro até que se defina uma pausa.
mushroom.play();
Depois de você ter criado uma animação básica, você deve estar apto a usar AM.Sprite, mas vale dar uma conferida nas propriedades e métodos abaixo para ter um controle maior de suas animações.
Construtor
AM.Sprite(element:HTMLElement, options:Object):void
Cria uma nova instância de AM.Sprite.
Propriedades
[somente leitura] .fps:Number = 24
Frames Per Second - Obtém e define a velocidade de projeção da animação.
[somente leitura] .columns:uint = 0
O número de colunas no sprite.
[somente leitura] .rows:uint = 0
O número de linhas no sprite.
[somente leitura] .column:uint = 0
A coluna atual.
[somente leitura] .row:uint = 0
A linha atual.
[somente leitura] .vertical:Boolean = false
Define a ordem de leitura.
[somente leitura] .tileW:Number = 0
A largura de um único frame do sprite.
[somente leitura] .tileH:Number = 0
A altura de um único frame do sprite.
[somente leitura] .timeline:Array = []
Uma matriz com as informações dos quadros do sprite.
[somente leitura] .lastFrame:uint = 0
[somente leitura] .targetNextFrame:uint = 0
[somente leitura] .targetFrame:uint = 0
[somente leitura] .offsetX:Number = 0
[somente leitura] .offsetY:Number = 0
[somente leitura] .reverse:Boolean = false
[somente leitura] .running:Boolean = false
Valor booleano que indica se uma animação está sendo reproduzida.
[somente leitura] .looping:Boolean = false
Valor booleano que indica se uma animação está sendo repetida.
[somente leitura] .yoyo:Boolean = false
Trabalha em conjunto com o estabelecimento de repetição, a determinação do comportamento de cada ciclo. Quando yoyo é true, a interpolação vai ir e voltar, revertendo qualquer outro ciclo (embora este não tenha efeito sobre a propriedade reverse).
Então, se repeat é 2 e yoyo é false, ele vai olhar como:
início - 1 - 2 - 3 - 1 - 2 - 3 - 1 - 2 - 3 - fim.
Entretanto, se repeat é 2 e yoyo é true, ele vai olhar como:
início - 1 - 2 - 3 - 3 - 2 - 1 - 1 - 2 - 3 - fim.
[somente leitura] .currentFrame:uint = 1
Especifica o número do quadro no qual o indicador de reprodução está localizado na linha do tempo na instância da animação.
@Exemplo:
O código a seguir usa o método gotoAndStop() e a propriedade currentFrame para direcionar o indicador de reprodução da animação robot de forma a mover cinco quadros à frente do seu local atual e interromper:
JavaScript
robot.gotoAndStop(robot.currentFrame + 5);@Veja também:
[somente leitura] .totalFrames:uint = 0
O número total de quadros na instância da animação.
Se a animação tiver vários quadros, a propriedade totalFrames retornará o número total de quadros carregados em todas as cenas na animação.
@Exemplo:
O código a seguir ilustra o uso da propriedade totalFrames de um objeto AM.Animation denominado robot:
JavaScript
console.log(robot.totalFrames);
[somente leitura] .duration:Number = 0
O tempo total da animação em segundos. Note que a duração não inclui qualquer repetição ou tempo de espera.
Métodos
.gotoAndPlay(frame:uint, scene:String = null):void
Inicia a reprodução a partir do quadro especificado. Para especificar uma cena e um quadro, especifique um valor para o parâmetro cena.
@Parâmetros:
frame:Object — Um número que representa o número do quadro, ou uma string que representa o rótulo do quadro, ao qual o indicador de reprodução é enviado. Se você especificar um número, ele será relativo ao palco especificado. Se você não especificar uma cena, a cena atual determinará o número do quadro global a ser reproduzido. Se você especificar uma cena, o indicador de reprodução saltará para o número do quadro na cena especificada.
scene:String (default = null) — O nome da cena a ser reproduzida. Este parâmetro é opcional.
@Exemplo:
O código a seguir usa o método gotoAndPlay() para direcionar o indicador de reprodução da animação queen de forma a mover cinco quadros à frente do seu local atual:
JavaScript
queen.gotoAndPlay(queen.currentFrame + 5);@Veja também:
.gotoAndStop(frame:uint):void
Traz o indicador de reprodução para o quadro especificado da animação e o interrompe nesse local.
@Parâmetros:
frame:Object — Um número que representa o número do quadro, ou uma string que representa o rótulo do quadro, ao qual o indicador de reprodução é enviado. Se você especificar um número, ele será relativo ao palco especificado. Se você não especificar uma cena, a cena atual determinará o número do quadro global a ser acessado e no qual parar. Se você especificar uma cena, o indicador de reprodução irá para o número do quadro na cena especificada e será interrompido.
scene:String (default = null) — O nome da cena. Este parâmetro é opcional.
.nextFrame():void
Envia o indicador de reprodução ao próximo quadro e o interrompe.
@Exemplo:
No exemplo a seguir, dois botões controlam a linha do tempo. O botão prev move o indicador de reprodução até o quadro anterior, enquanto o botão next move o indicador de reprodução até o próximo quadro.
JavaScript
next.addEventListener('click', goForward);
prev.addEventListener('click', goBack);
function goForward(ev) {
char.nextFrame();
}
function goBack(ev) {
char.prevFrame();
}
@Veja também:.prevFrame():void
Envia o indicador de reprodução ao quando anterior e o interrompe.
@Exemplo:
No exemplo a seguir, dois botões controlam a linha do tempo. O botão prev move o indicador de reprodução até o quadro anterior, enquanto o botão next move o indicador de reprodução até o próximo quadro.
JavaScript
next.addEventListener('click', goForward);
prev.addEventListener('click', goBack);
function goForward(ev) {
boat.nextFrame();
}
function goBack(ev) {
boat.prevFrame();
}
@Veja também:.play(...frame:uint, ...options:Object):void
Move o indicador de reprodução na linha do tempo da animação.
@Exemplo:
O código a seguir usa o método stop() para interromper um clipe de filme denominado lazy e para reiniciar a reprodução quando o usuário clicar no botão alarmClock:
JavaScript
lazy.stop();
alarmClock.addEventListener('click', pushLazy);
function pushLazy(ev) {
lazy.play();
}
.stop():void
Para o indicador de reprodução na animação.