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.