Velocity.js よみほぐし

#概要

巷で今話題の Velocity.js がどんなもんかをメモっていく。
追記しながら完成させる予定…

####原典
http://julian.com/research/velocity/

# 使う前のところのよみほぐし

## 動作環境

jQueryがあるかないかで多少違う模様。
jQueryありだとIE8でも動き、jQueryがないとIE8はサポートから外れる。
ZeptoでもjQueryありと同様のことができる。

### jQueryないとき

```js
Velocity(document.getElementById("dummy"), { opacity: 0.5 }, { duration: 1000 });
```
Velocity(〜)で書く。

## RequireJS

```js
require.config({
    paths: {
        "jquery": "/path/to/jquery-x.x.x",
        "velocity": "path/to/velocity",
        // Optional, if you're using the UI pack:
        "velocity-ui": "path/to/velocity.ui"
    },
    shim: {
        "velocity": {
            deps: [ "jquery" ]
        },
        // Optional, if you're using the UI pack:
        "velocity-ui": {
            deps: [ "velocity" ]
        }
    }
});
require([ "jquery", "velocity", "velocity-ui" ], function ($, Velocity) {
    /* Your app code here. */
    $("body").velocity({ opacity: 0.5 });
});
```
普通に設定できる。

## 引数について

###基本

```js
$element.velocity(propaties, options);
```
アニメーションさせるプロパティと値を定義したObjectと
オプション設定を定義したObjectを入れる。

###1つだけ入れたい場合
設定したObject「１」つだけいれたい。

```js
$element.velocity(props);
```

→ こうする。

```js
$element.velocity({ 
    properties: { opacity: 1 },
    options: { duration: 500 }
});
```

「p」と「o」で書くこともできる。

```js
$element.velocity({ 
    p: { opacity: 1 },
    o: { duration: 500 }
});
```

### jQueryのanimateの引き継ぎ

```js
$element.velocity({ top: 50 }, 1000);
$element.velocity({ top: 50 }, 1000, "swing");
$element.velocity({ top: 50 }, "swing");
$element.velocity({ top: 50 }, 1000, function() { alert("Hi"); });
```
$element.animateで書ける書き方は踏襲できる。

## 設定可能なプロパティ

多岐に渡るが、CSSでサポートしているプロパティは大抵可能。
[本家](http://julian.com/research/velocity/#cssSupport)のサンプルを参照されたし。

padding、marginにて

```css
{padding:"1,1,1,1"}
```
みたいなのはサポートしていない。

```js
{ paddingLeft: 1, paddingRight: 1 }
```
のように指定する。

## 設定値について

以下の場合の数字指定は「50px」として判別する。

```js
{top:50}
```

単位はpx, em, rem, %, deg, and vw/vhに対応。
degはrotateZ等の指定のみ対応。通常のCSSのルールに沿えば動く。
remやらvw/vhはIE9未満は対応してないし、Android 4.4未満も対応してないよ。

特徴の一つとして、その場からどの程度変化するかを指定できる。
「"+=5"」のように指定することで5ずつ増やすことができる。
+=,-=,*=,/=に対応しているよ。

## アニメーションチェーン

ドットシンタックスでつなげることで
A→B→C→…　のようにアニメーションをつなげることができる。

```js
$element
    /* Animate the width property. */
    .velocity({ width: 75 })
    /* Then, when finished, animate the height property. */
    .velocity({ height: 0 });
```

# Option設定

## duration
アニメーション時間をミリ秒で指定する。jQueryで使うような"slow"とかも可能。

```js
$element.velocity({ opacity: 1 }, { duration: 1000 }); 
$element.velocity({ opacity: 1 }, { duration: "slow" });
```

## easing

### easeなんとかかんとか

* CSS3で使うような"ease-in","ease-out","ease-in-out"が可能。
* [ここ](http://easings.net/)にあるような"easeInOutCubic"のような指定が可能。
ただし、Back系、Elastic系、Bounce系は使えない。

### spring

Elastic系の代わりに、springがある。"spring"もしくは数値が2つ入っている配列を入れる。

```js
$element.velocity({ width: 50 }, {easing:[ 250, 15 ]});
```
配列の中身の意味は[張力,減衰]だが、直感的でないので[ここ](http://codepen.io/julianshapiro/pen/hyeDg)で試すとよい。

### ステップ

数値が1つ入っている配列を入れる

```js
$element.velocity({ width: 50 }, {easing:[ 3 ]});
```

例で言うと、50pxまで3回にわけてカクカクと大きくしていく。サンプル見たほうがわかりやすい。

## beginとcomplete
開始時、終了時コールバックを取る。

```js
$element.velocity({
    opacity: 0
}, {
    begin: function(elements) { console.log(elements); },
    complete: function(elements) { console.log(elements); }
});
```

## progress
アニメーションをフレーム単位でコールバックを返す。fpsはわからないが、推定60くらい。

```js
$element.velocity({
    opacity: 0,
    tween: 1000 // Optional
}, {
    progress: function(elements, complete, remaining, start, tweenValue) {
        console.log((complete * 100) + "%");
        console.log(remaining + "ms remaining!");
        console.log("The current tween value is " + tweenValue)
    }
});
```


### プロパティ名「tween」について
pregressを使用する際に、実際のビューに関わるようなCSSパラメーターとは別にtweenというパラメーターの値を取ることができる。

#### 何に使うか？

* 数値表示のカウントアップ、ダウン
* 値を元にした独自の動き付け、ビューの切り替え

意外と応用が効く。
tweenというプロパティ名だけこれができるようだ。

## delay
指定ミリ秒後にアニメーション開始。ここでは前delayにあたる。
beginコールバックはdelayの後になる。

```js
$element.velocity({ height: "+=10" }, { delay: 100 });
```

## loop
ループの回数を指定。true指定で永遠くりかえす。
delayがある場合の扱いは
delay→begin→animation→delay→animation:reverse→complete
の流れになり、前後にdelayが入る

```js
$element.velocity({ height: "10em" }, { loop: 2 });
$element.velocity({ height: "10em" }, { loop: true });
```

## queue
アニメーションのキューの設定。
$element.dequeue()で実行できる。
false指定で直ちに実行される。

つかいどころは、複数のアニメーションパターンをキュー名を付けて作り、これをdequeueで同時、時間差実行ができる。
false指定でdequeue使わなくても複数のアニメーションパターンを同時実行できる。

```js
var properties = {
            translateX: "+=100px"
};
var options = {
            queue:"a",
            duration:1000,
            easing:"easeOutCubic",
};
$element.velocity(properties, options);
        
var _properties = {
            width:"+=50px",
            height:"+=50px"
};
var _options = {
            queue:"b",
            //queue:false,//すぐに
            duration:500,
            easing:[ 300, 8 ]
};
        
$element.velocity(_properties, _options);
    
$element.dequeue("a");
$element.dequeue("b");
```

## displayとvisibility

```js
/* Animate down to zero then set display to "none". */
$element.velocity({ opacity: 0 }, { display: "none" });

/* Animate down to zero then set visibility to "hidden". */
$element.velocity({ opacity: 0 }, { visibility: "hidden" });
```

使い方を見ると…

opacityが0になった後displayをnoneにしたり、visibilityをhiddenにしたり
する場合に使う。

```js
/* Set display to "block" then animate from opacity: 0. */
$element.velocity({ opacity: 1 }, { display: "block" });
```
opacityが0から動くときdisplayをblockにして動かす。

単純にアニメーションのcompleteの時に表示状態をどうするかとかではなく
opacityのコントロールと密接していて、これが0になったときや0から動くときに作用するようだ。
なので、opacityが0.2とかでは動かない。
そして後述するReverseにも対応してないようだ。

ちゃんと仕様を理解しないとバグの原因になるので使う際は気をつけるべし。

## mobileHA

主にiOSでtransitionを使う場合の強制的にGPUレンダリングさせる方法に関する設定

```css
translate3d(0,0,0);
```
```css
-webkit-transform-style:"preserve-3d";
```
このへんの設定のはなし。
iOSだとこの設定を使うと高速にレンダリングされるが、GPU描画の開始の際チラつきが出る。
また、Androidにこれを使うとフォームがバグったりする。
そういうところでこの設定を使う場面が出てくる。

使い方は以下、Boolean値を入れる。

```js
$element.velocity(propertiesMap, { mobileHA: false });
```

# コマンド

命令セット
Fade系、Slide系、Scroll、Stop、Finish、Reverseがある。
第一引数に指定のStringを入れて実行する。

## Fade

* fadeIn
* fadeOut

```
$element
    .velocity("fadeIn", { duration: 1500 })
    .velocity("fadeOut", { delay: 500, duration: 1500 });
```
jQueryにもあるやつ。


## Slide

* slideDown
* slideUp

```
$element
    .velocity("slideDown", { duration: 1500 })
    .velocity("slideUp", { delay: 500, duration: 1500 });
```

うん、jQueryにもあるやつ。

## Scroll


### jQueryでの実装

```
$("html, body").animate({scrollTop: position}, speed, "ease-out");
```

$("html, body")のpositionへスクロールする、という意味の実装。

### velocity.jsでの実装

```
$element
    .velocity("scroll", { duration: 1500, easing: "spring" });
```

velocityの場合は
$elementへスクロールする、という意味の実装。
主語が変わっているので注意。


### 指定のスクロールのあるオブジェクト内の$elementへのスクロール方法

```
/* Scroll $element into view of $("#container"). */
$element.velocity("scroll", { container: $("#container") });
```
containerを指定する。

### ヨコ方向のスクロール

```
/* Scroll the browser to the LEFT edge of the targeted div. */
$element.velocity("scroll", { axis: "x" });
```

axisに"x"を入れることでヨコ方向へスクロール指定できる


### ズレの設定
```
$element
    /* Then scroll to a position 250 pixels BELOW the div. */
    .velocity("scroll", { duration: 750, offset: 250 })
    /* Scroll to a position 50 pixels ABOVE the div. */
    .velocity("scroll", { duration: 750, offset: -50 });
```

offsetを入れると$elementからずれた位置へスクロールさせられる。

## Stop

アニメーションの中断

```
$element.velocity("stop"); // Normal stop
$element.velocity("stop", "myQueue"); // Custom queue stop
```

jQuery Elementに対してのStopが主な機能
queueを作っている場合は名指しでStopがかけられる。

> **雑感**
> 何が理由か不明だが、stopでうまく止められない時がある。
> 
> ```
> $element.stop().velocity("stop");
> ```
> 上記のようにしないと止まらない場合がある。
> また、stopはコストが数フレームかかる場合があり、requestAnimationFrameでのフレーム更新を利用しても1フレーム待ちだとだめな場合がある。
> 確実にアニメーションがStopした、というタイミングが非常に取りにくいので、アニメーション設計するときに注意を要する。


## Finish

```
$element.velocity("finish");
```

強制的に最終フレームまで飛ばしてアニメーションを終了させる。

```
$element.velocity( { opacity: 0 }, 2000).velocity({opacity:0.2});
```
上記のような場合にfinishを適応するとopacityは0.2になる。
派生先含めてFinishした時のプロパティとなる。

## Reverse

```
$element.velocity("reverse");
or
$element.velocity("reverse", { duration: 2000 });
```

アニメーションの逆再生。parallel再生のアニメーション(queue: falseで再生させるアニメーション)には適応できない。

# Feature
## Transforms
## Colors
## SVG
## Hook
## Promises
## Mock
## Utility Function

# Advanced
## Value Functions
## Forcefeeding
## Sequences

# Plugins
## UI Pack
## VMD
## Ember & Misc.