筆者自作のプラグインについて

Snap.svgの現バージョンに存在せず，これ面白いとか，あったらいいなという機能，あったほうが良いと思われる機能を実装してみたものです．ファイル名としてSnap.snip.jsとしているのは語呂が良いからで，特に意味はありません．

ファイルの入手

ここからダウンロードしてください．

プラグインの導入

Snap.svgの後でプラグインスクリプトファイルを読み込んでください．

ライセンスと免責

Snap.svgと同じライセンス(Apacheライセンス2.0)とします．なお，本プログラムを使用することで発生したいかなるバグ・不具合・損害については作者は一切関知しません．そのため，スクリプトを直接利用するのではなく，Snap.svgの使い方例もしくはプラグインの作成例としてコードを切り貼りして利用することをお勧めします．また，そもそもの由来が筆者の学習目的なので，致命的な不具合が含まれていたり，予告無く仕様変更されることも考えられ，バージョン管理とかもずさんです．それでよければご利用ください．

※動作検証はfirefox/chrome上で行っていますが，他の環境でどこまで動作するかは不明です．

カスタム属性の定義

Snap.defineAttr(attrName, func, isList, beforeDOMWrite, getter)

Snap.defineAttrメソッドは新たにカスタム属性を定義します．attrNameには定義したい属性名を，funcには値設定時に呼び出される関数を指定します．isListには設定値がリスト形式かどうかを指定します．beforeDOMWriteにtrueを指定するとDOMへの値書き込み前に関数を呼び出します．getterにはDOMアクセスの前に値を取得するための関数を指定します．

図形オブジェクトの追加

Snap.defineShape(funcName, template, attrs)

Snap.defineShapeメソッドは新たにカスタム図形を定義します．funcNameには図形の名称を，templateにはテンプレートとなるpath文字列もしくはpath文字列を生成する関数を，attrsには図形を定義するための属性のリストを指定します．登録したカスタム図形はPaper.[カスタム図形名]として呼び出すことが出来ます．なお，既に図形が登録済みだった場合は例外を発生します．

templateに関数を指定した場合，引数としてattrsに指定したオブジェクトの形式でパラメータが渡されます．このパラメータを元にパス文字列を返すようにします．なお，文字列を受ける属性を定義する場合は"string"を，数値リストを受ける属性を定義する場合は"list"をattrオブジェクトに指定します．

上手く使えば吹き出し等のオートシェイプ的な図形を再利用可能な形で定義することが可能です．

下記の図形はこのSnap.defineShapeメソッドを使って実装されています．

Paper.lineLike(x1,y1,x2,y2)

Paper.lineLikeメソッドは線分をpath要素で描画します．

Paper.rectLike(x,y,width,height)

Paper.rectLikeメソッドは矩形をpath要素で描画します．

Paper.circleLike(cx,cy,r)

Paper.circleLikeメソッドは円形をpath要素で描画します．

Paper.ellipseLike(cx,cy,rx,ry,rotate)

Paper.ellipseLikeメソッドは楕円をpath要素で描画します．

Paper.polylineLike(points)

Paper.polylineLikeメソッドは折れ線をpath要素で描画します．

Paper.polygonLike(points)

Paper.polygonLikeメソッドは多角形をpath要素で描画します．

Paper.arc(cx,cy,r,start,end)

Paper.arcメソッドは円弧を描画します．

Paper.bow(cx,cy,r,start,end)

Paper.bowメソッドは弓形を描画します．

Paper.pie(cx,cy,r1,r2,start,end)

Paper.pieメソッドは扇型を描画します．{cx,cy}を中心とし，半径r1〜r2の範囲かつstart〜end角の範囲を囲む扇形をpath要素として描画します．各プロパティはアニメーション化可能です．角度方向はSVG標準に準拠しているためSnap.svgのUコマンドよりも使いやすくしています．

Paper.rpolygon(n,cx,cy,r)

Paper.rpolygonメソッドは正多角形を描画します．頂点の数と中心座標，半径を指定します．(※rはreglarの頭文字)

Paper.rstar(n,cx,cy,r)

Paper.rstarメソッドは星形を描画します．頂点の数と中心座標，半径を指定します．

Paper.star(n,cx,cy,r,spoke)

Paper.starメソッドは星形を描画します．頂点の数と中心座標，半径及びスポーク比(凹み部の割合)を指定します．

Paper.radar(cx,cy,rs)

Paper.radarメソッドはレーダー図形を描画します．中心座標と頂点との距離のリストを指定します．

Paper.smoothRpolygon(n,cx,cy,r)

Paper.smoothRstar(n,cx,cy,r)

Paper.smoothStar(n,cx,cy,r,spoke)

Paper.smoothRadar(cx,cy,rs)

Paper.smoothrpolygon,Paper.smoothrstar,Paper.smoothstar,Paper.smoothradarメソッドは頂点が滑らかな図形を描画します．

テキスト操作の拡張

Element.textLength()

Element.textLengthメソッドは文字列の長さを返します．

Element.substr(i,len)

Element.substrメソッドは文字列に対する部分文字列を返します．

Element.getBBoxOfChar(i)

Element.getBBoxOfCharメソッドは文字の描画範囲を取得します．なお環境等の問題により正しい値が取得できない場合があります．

Element.attr({skipx: value})

Element.attr({skipy: value})

skipx/skipy属性は文字の配置間隔を与えます．文字列の配置が終わったあとで値を設定して下さい．自動的に文字を配置します．

なおこのプロパティはアニメーションできます．

Element.attr({skipdx: value})

Element.attr({skipdy: value})

skipdx/skipdy属性は文字の間隔を与えます．文字列の配置が終わったあとで値を設定して下さい．自動的に文字を配置します．

※上記はtext要素のx,y,dx,dy属性の値生成をサポートするカスタム属性です．複雑な内容にすると(ブラウザごとの解釈の違いから)上手く制御できないかもしれません．

画像読み込みに関わる拡張

Paper.imageAsDataScheme(src, x, y, width, height)

Paper.imageAsDataSchemeメソッドはsrcの画像をurlデータスキーム形式に変換してから読み込みます．SVG画像に直接画像を埋め込むため，ファイルの外部参照に依る不具合がなくなります．

属性操作の拡張

Element.copyAttr(obj, func)

Element.copyAttrメソッドはElementオブジェクトの属性値を抽出します．

Element.attr({strokeDasharray: "pattern"})

Element.attrメソッドにおけるstrokeDasharray属性設定ではRaphael形式の点線書式を指定できます．ですが，直接数値で指定したほうが簡単なので，滅多に利用することはないでしょう．

DOM操作の拡張

Snap.setter(template, func, thisArg)

Snap.setterメソッドは繰り返し処理を行うためのサポートメソッドです．パラメータの内容が前回呼び出し時から変化した時のみ，funcを実行します．

Element.setter(template)

Element.setterメソッドはattrメソッドの呼び出し関数を生成します．内部で現在値を保持しており，値が変更された場合に限りattrメソッドを実行します．何度も同じプロパティにアクセスする場合や，アニメーション等における実際のDOM操作回数を減らすために利用します．返された関数fについて，f.elementには元のElementオブジェクトが，f.currentには現在の値が設定されています．

Element.replaceWith(elem)

Element.replaceWithメソッドは現在の位置に引数の要素を挿入し，自身をdomから削除します．つまり，要素を入れ替えます．

Element.wrap(elem)

Element.wrapメソッドは指定したElementオブジェクトもしくは要素名で現在の要素を囲みます．誤った要素で囲んでしまった場合，正しい動作とならない可能性があります．

Element.prev()

Element.prevメソッドは現在の要素に対する前の要素を取得します．

Element.next()

Element.nextメソッドは現在の要素に対する後の要素を取得します．

Element.children()

Element.childrenメソッドは現在の要素の子要素をSetオブジェクトとして取得します．

Element.toFront()

Element.toFrondメソッドは要素をその階層の最も前面に移動します．

Element.toBack()

Element.toBackメソッドは要素をその階層の最も背面に移動します．

Element.forward()

Element.forwardメソッドは要素を一つ後（上）に移動します．

Element.backward()

Element.forwardメソッドは要素を一つ前（下）に移動します．

Set/Fragmentオブジェクトに関わる拡張

Set.toArray()

Set.toArrayメソッドはSetオブジェクトの内容を配列に変換して返します．

Snap.fragment()

Snap.fragmentメソッドは空のFragmentオブジェクトを生成します．元のSnap.fragmentメソッドにおけるSnap.fragment("")と同じ動作を採ります．

Fragment.append(elem)

Fragment.appendメソッドはElementオブジェクトをFragmentに追加します．副次的にElement.appendToメソッドにFragmentオブジェクトを渡せるようになります．

Fragment.prepend(elem)

Fragment.prependメソッドはElementオブジェクトをFragmentの先頭に追加します．副次的にElement.prependToメソッドにFragmentオブジェクトを渡せるようになります．

リンク設定に関わる拡張

Element.link(src, target)

Element.linkメソッドは要素をa要素で囲み，リンクとします．

Element.unlink()

Element.unlinkメソッドは親要素がa要素だった場合，もしくは自身がa要素だった場合にリンク設定を削除します．

パス操作に関わる拡張

Snap.path.invert(pathStr)

Snap.path.invertメソッドは与えられたパスデータの内容を逆方向に変換します．

通常fill-ruleプロパティで行う白抜き設定をパス方向の逆転で行えるようになります．

Element.toPathString()

Element.toPathStringメソッドは与えられた図形要素(rectやcircle要素を含む)に対するパス文字列表現を返します．変換できない場合は空文字列が返されます．

座標取得に関わる拡張

Paper.getSVGPoint(e)

Paper.getSVGPointメソッドはカーソル座標からSVGグラフィック内部の座標を取得します．

Paper.getSVGPoint(clientX, clientY)

Paper.getSVGPointメソッドはクライアント座標（カーソル座標）からSVGグラフィック内部の座標を取得します．

Element.getStartPoint()

Element.getStartPointメソッドは(path要素の場合)，開始位置の座標情報を取得します．

Element.getEndPoint()

Element.getEndPointメソッドは(path要素の場合)，終了位置の座標情報を取得します．

Element.getPointAtRate(rate)

Element.getPointAtRateメソッドは(path要素の場合)，指定したパス道のりの指定割合の座標を取得します．

図形の表示に関わるメソッド

Element.hide()

Element.hideは要素を隠します．

Element.show()

Element.showは要素を表示します．

Set.hide()

Set.hideメソッドは管理している全ての要素を隠します．

Set.show()

Set.showメソッドは管理している全ての要素を表示します．

図形の操作に関わる拡張

Element.toggle(onFunc,offFunc,isOn)

Element.toggleメソッドは要素にトグル処理を設定します．スイッチ等の機能を実装する場合に利用します．onFuncはスイッチがoffからonの状態に移る際の処理を指定します．offFuncはスイッチがonからoffの状態に移る際の処理を指定します．isOnはメソッド呼び出し時の初期状態を指定します．

メソッドにisOn(boolean)値を渡すとトグル状態を指定の状態に遷移します．

isOn未指定の場合はon(true)状態として扱われます．

直接メソッドを実行するとトグル状態を変化させます．

Element.toggleState()

Element.toggleStateメソッドは現在のトグル状態を取得します．

関数未指定の場合はElement.show/Element.hideが割り当てられます．

図形加工に関わる拡張

Element.stack(count)

Element.stackメソッドは元の要素のコピー(use要素)を指定した数だけ重ねたものをg要素として返します．元々のElementオブジェクトは得られたg要素に対してselect("[group-type=stack]>g>*")を実行します．

Element.snip(xcnt,ycnt,pathStr)

Element.snipメソッドは縦横指定した数でグラフィックを分割します．pathStrが指定されていた場合は，このパス図形でグラフィックを分割します．得られたg要素の内部構造はElement.stackメソッドと同じです．

pathStrに指定する図形は10×10四方を基準にタイル敷き詰め可能な形を指定します．

Element.snipAt(x,y)

Element.snipAtメソッドは指定した座標でグラフィックを分割します．

Element.interpolate(attrs, p)

Element.interpolateメソッドは現在のプロパティ状態から指定した状態との間の線形補間を行います．p値(0〜1)の内容に従い，値を按分したものでプロパティ値を上書きします．

Element.animateメソッドでアニメーション化可能なプロパティが対象です．

図形の配置に関わる拡張

Snap.limitToPath(pathStr, x, y, pt)

Snap.limitToPathメソッドは指定した座標をパス図形の範囲に制限します．凹んだ図形を指定した場合は例外を発生する場合があります．

Snap.limitToRange(start, end, value)

Snap.limitToRangeメソッドは値を指定した範囲に制限します．

処理の自動実行に関わる拡張

Snap.do(func)

Snap.doメソッドは指定したメソッドを繰り返し実行します．戻り値として返されるanimオブジェクトを操作することで処理の一時停止，再開，停止（終了）させることが出来ます．主に特定の終了タイミングを持たないアニメーション目的で用います．

Element.do(func)

Element.doメソッドは指定したメソッドを繰り返し実行します．メソッド内のthis変数はdoメソッドを実行した主体となります．

この処理は例えばアンカー機構に使います．

DOMを書き換える操作は本質的に重い操作ですから，状態が変化した場合に限って再描画させるような工夫が必要となるでしょう．

Element.pause()

Element.pauseメソッドはElement.doメソッドで実行している処理の全てを一時停止します．

Element.resume()

Element.pauseメソッドはElement.resumeメソッドで実行している処理の全てを再開します．

Element.stop()

Element.stopメソッドはElement.doメソッドで実行している処理の全てを終了します．

Element.doings()

Element.doingsメソッドは現在実行中の処理に対応するanimオブジェクトの配列を取得します．自動実行している処理を個別操作する場合に利用します．

Snap.watch(template, knock, func, thisArg)

Snap.watchメソッドはオブジェクトの内容を監視し，その内容が変化されていた場合に関数を呼び出します．template/func/thisArgにはSnap.setterメソッドと同じ形式のパラメータを渡します．すると，knockメソッドに生成されたsetter関数が渡されるため，監視対象のオブジェクトの値を渡します．

• [こんなイメージ]Snap.watchさんは値の変化を見るのが得意です．
• Snap.watchさん，頼むから処理を手伝ってくれよ．
• template:これからこう言った[形式]のデータを使いたいんだ．
• knock:気がついたらでいいからこの[扉を叩いてね]．君に現在のデータをしゃべるから．
• func:それで，前と値が変化していたらさっきの形式で[ポストに投函]して欲しいんだ．
• thisArg:そうそう，できれば[この家]のポストにね．

先ほどのアンカー処理をSnap.watchメソッドを使って書き換えると次のようになります．

内部でSnap.doメソッド(つまり，minaによるアニメーション機構)を利用しているため，anim.pauseメソッド等で動作を制御できます．

Element.watch(template, knock)

Element.watchメソッドは他のオブジェクトの内容を監視し，その内容が変化されていた場合に自身のプロパティを書き換えます．templateにはElement.setterメソッドと同じ形式のパラメータを渡します．すると，knockメソッドに生成されたsetter関数が渡されるため，監視対象のオブジェクトの値を渡します．

先ほどのアンカー処理をElement.watchメソッドを使って書き換えると次のようになります．

内部でElement.doメソッドを利用しているため，Element.pauseメソッド等で処理の有無を指定できます．

特殊なアニメーションを実現する拡張

Element.animateCustom(func, dur, easing)

Element.animateCustomメソッドはElement.animateメソッドを拡張します．funcに指定した関数を元にアニメーションを実行します．funcには0〜1の値が渡されるため，この内容を使ってグラフィックを書き換えます．

Element.animateMotion(path,orient,dur,easing,calback)

Element.animateMotionメソッドは図形を指定したパスに沿って動かします．orientに"auto"を指定するとパス方向に沿って図形が表示されます．"auto-reverse"を指定するとパス方向とは逆向きに沿って図形が表示されます．

イージング関数のデコレータ

以下のメソッドは与えられたイージング関数を元に新しいイージング関数を合成します．

Paper.displayEasing(easing, x, y, width, height)

Paper.displayEasingメソッドはイージング関数の内容を確認するための補助メソッドです．イージング関数の形状をpath図形で取得し，アニメーション量を視覚化します．

Snap.easing.times(easing, times)

Snap.easing.timesメソッドは与えられたイージング関数を指定された回数反復します．なお，その分動作速度が上がるため，全体としてのアニメーション時間を調整する必要があります．

Snap.easing.delay(easing, delay, duration, cooldown)

Snap.easing.delayメソッドは与えられたイージング関数について指定した時間の分アニメーションの開始/終了のタイミングをずらします．なお，その分全体としての動作速度が上がるため，アニメーション時間を調整する必要があります．

Snap.easing.shift(easing, shift, scale)

Snap.easing.delayメソッドは与えられたイージング関数について開始値と終了値とを変更します．これは後述するjoinメソッドと組み合わせることでイージング関数を連結際に利用します．

Snap.easing.reverse(easing)

Snap.easing.reverceメソッドはイージング関数の方向を逆転(増加から減少)します．

return 1 - easing(t);

Snap.easing.mirror(easing)

Snap.easing.mirrorメソッドはイージング関数の時間軸を反転します．

return easing(1 - t);

Snap.easing.join(easings)

Snap.easing.joinメソッドはイージング関数の配列を結合し，一つのイージング関数とします．

デコレータは構造上幾らでも重ねることが出来ますが，過剰な装飾はアニメーションのパフォーマンスに影響します．

タイムラインアニメーションを実現する拡張

Snap.translateTimeline(settings,delay,total,callback)

Snap.translateTimelineメソッドは引数のデータを元にタイムライン情報オブジェクトを生成します．下記のSnap.animateTimelineメソッドを繰り返す場合に利用すると事前処理を省くことが出来ます．

Snap.animateTimeline(settings,delay,total,callback)

Snap.animateTimelineメソッドはタイムラインアニメーションを実現します．settingsにはjson形式のアニメーション定義を指定します．delayはアニメーション開始までの時間を，totalはアニメーション持続時間を指定します．

Snap.animateTimeline(timeline)

Snap.animateTimelineメソッドにはSnap.translateTimelineメソッドで生成したタイムライン情報を元にアニメーションを実行します．

これらのアニメーションは戻り値のanimオブジェクトを操作することで一時停止などの処理を行うことが出来ます．

アニメーション定義オブジェクトの形状

settingsには下の形式のオブジェクト(アニメーション設定オブジェクト)の配列を指定します．アニメーション設定オブジェクトは通常1要素1属性に一つ用意します．

アニメーション設定オブジェクトの定義には次の3つの方法があります．

• 関数指定
  フレームワーク側から0〜1の値が渡されます．この値を元に要素の内容を書き換えます．自由度の高いアニメーションを定義できます．
• シンプル指定
  変化値がアニメーション開始時〜終了時の二つの値から構成されるものです．
• キーフレーム指定
  値の変化をキーフレームとして指定し，より複雑な動作を指定するものです．

以下にそれぞれのプロパティの意味合いについて説明します．

共通設定

何れの方法を用いても必要となるプロパティです．

setting.begin

アニメーション開始のタイミング

setting.dur

アニメーションの持続時間．0を指定すると即時変位．

関数指定

setting.func

フレームごとに呼び出される関数．0〜1の値が渡されます．

setting.easing

利用するイージング関数

シンプル指定

setting.elem

アニメーション対象の要素

setting.attr

アニメーション対象の属性

setting.from

アニメーション開始値

setting.to

アニメーション終了値

setting.easing

利用するイージング関数

キーフレーム指定

setting.elem

アニメーション対象の要素

setting.attr

アニメーション対象の属性

setting.keyframes

アニメーション値のキーフレーム毎の指定

keyframe.rate

キーフレーム値

keyframe.value

属性値

keyframe.easing

キーフレーム間に適用されるイージング関数

keyframe.discrete

線形補間を行わず，直接値を設定する場合にtrueを指定します．

値の即時設定，文字列などの設定

値を直接指定する場合や，数値以外の線形補間が出来ないプロパティをアニメーション化する場合は，durプロパティを指定しないか，discreteプロパティにtrueを指定します．

シンプル指定の場合

キーフレーム指定の場合

タイムラインアニメーションの実行例

アニメーション設定を作るのは面倒なので，それをサポートするメソッドを用意しました．

Snap.copy(obj)

Snap.copyメソッドは与えられたオブジェクトの浅いコピーを返します．※プロパティに配列などが含まれていた場合は意図した通りとなりません．またコピーされたオブジェクトには勝手にsetメソッドが追加され，値の設定をこのメソッド経由で行えます．

Snap.copies(obj,count)

Snap.copyメソッドは与えられたオブジェクトの浅いコピーの配列を返します．

出力に関わる拡張

Paper.toDataURL()

Paper.toDataURLメソッドは現在のsvg要素をスタンドアロンのsvg文書に変換します．a要素のhref属性に設定したり，window.openメソッドに渡すことでsvg画像を外部に保存することが可能になります．