sprite.js é uma pequena, mas poderosa biblioteca JavaScript para animações baseadas em sprites.


Download .zip Download .tar.gz View on GitHub

build status dependencies status devDependency status views

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.

@Veja também:

[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.