customShapes.jsの使い方はその特性上３つに分けられます.
以下, これらについて解説していきます.
カスタム図形の記述の仕方
SVG要素内にカスタム図形を記述するのは簡単です. customShapes.jsはtype属性をもつpath要素をカスタム図形要素として解釈します. そのpath要素にはグラフィックの描画に必要となるパラメータを属性として記述しておきます. するとcustomShapes.jsはその内容に従って自動的に図形を描画していきます.
- type属性
- カスタム図形の識別子を指定します. 例えば扇型を描画するのであれば
type="pie"を記述します.
- パラメータ属性
- 図形を描画するために必要となるデータはpath要素の属性として記述します. この内容は図形によって異なります.
例えば扇型を描画するには, 中心座標, 半径, 開始角及び終了角の情報が必要です. これらをpath要素の属性値として記述しておきます.
パラメータ属性に対する単位の指定
属性値には一般のSVG要素と同様に単なる数値の他に単位を指定することも出来ます.
パラメータ属性に対するjavascriptコードの挿入
カスタム図形要素のculc属性にtrueを指定しておくと, パラメータ属性値内の{{}}で囲まれた部分はjavascriptコードとして解釈し, 計算結果を元に図形を描画します. 1行として解釈可能なコードを挿入してください.
上位g要素の参照
カスタム図形要素において図形描画に足りないパラメータは1段上のg要素の同名の属性を参照します. この仕組みを利用すると, 例えば中心を同じくする扇型を複数描画する場合, 下の例のように図形要素たちをグループ化して中心座標の記述を一箇所にまとめることが出来ます.
標準提供のカスタム図形
customShapes.jsではよく使われる図形, もしくはカスタム図形実装のサンプルを兼ねて幾つかの図形が予め定義されています. 以下に一覧を示します.
- path
- line
- polyline
- polygon
- rect
- circle
- ellipse
- pie
- arc
- bow
- moon
- rpolygon
- star
- rstar
- radar
- circles
- grid
- radial
- stamp
- repeatstamp
- arcstamp
- pathstamp
- direction
- balloon
- fit
- parameter
- bbox
- box
- autoballoon
- anchor
基本図形の代替
以下はSVG標準の図形要素をcustomShapes.jsを使って再定義したものです. 図形描画に必要となる属性はSVG標準の図形要素の属性と同じですが, 元の図形要素と異なり各属性値にはマイナス値を指定することもできます. また図形の中には機能が追加されているものもあります.
- path…パス図形
path…パス文字列
- line…直線
x1,y1…始点の座標, x2,y2…終点の座標
- polyline…折れ線
points…頂点座標のリスト, closed…trueで折れ線を閉じる, smooth…trueで滑らかする
polyline要素と異なり, 座標には単位を指定することも出来ます.
closed属性にtrueを指定することで折れ線を閉じます. 図形的にはpolygon型と同じものになります. (要素の入れ替えが不必要となります. )
smooth属性にtrueを指定することで滑らかな曲線とします(Catmull-Rom曲線).
- polygon…多角形
points…頂点座標のリスト, smooth…trueで滑らかする
smooth属性にtrueを指定することで滑らかな曲線とします(Catmull-Rom曲線).
- rect…矩形
x,y…左上頂点の座標, width…矩形の幅, height…矩形の高さ, rx,ry…頂点の丸め半径, hollow…trueで丸めの部分を凹ませる
width,heightには負値を指定することも出来ます.
hollow属性にtrueを指定することで角が凹みます.
- circle…円
cx,cy…中心座標, r…半径
- ellipse…楕円
cx,cy…中心座標, rx,ry…半径
customShape.js独自の図形群
以下は本スクリプトが独自に定義した図形です．
pie…扇型
type="pie"は扇型を表します. circle型と同じく中心座標と半径に加え, 円弧の開始角と終了角を指定します.
cx,cy…中心座標, r,r2…半径(外径, 内径), start…開始角, end…終了角
arc…円弧
type="arc"は円弧を表します. circle型と同じく中心座標と半径に加え, 円弧の開始角と終了角を指定します. なお, パスは閉じられません.
cx,cy…中心座標, r…半径, start…開始角, end…終了角, closed…trueで円弧を閉じる
closed属性にtrueを指定すると円弧が閉じられ, 図形的には下記のbow型と同等になります.
bow…弓形
type="bow"は弓形を表します. circle型と同じく中心座標と半径に加え, 円弧の開始角と終了角を指定します. なお, パスが閉じられる点でarc図形と異なります.
cx,cy…中心座標, r…半径, start…開始角, end…終了角
moon…月形
type="moon"は月形を表します. circle型と同じく中心座標と半径に加え, 欠けている部分の半径と円弧の選択を指定します.
cx,cy…中心座標, r…半径, start…開始角, end…終了角, r2…欠けている部分の半径, larc…trueで長い方の円弧を用いる(SVGのlargeArcFragパス仕様に準じます. )
rpolygon…正多角形
type="rpolygon"は正(regular)多角形を表します. circle型と同じく中心座標と半径及び頂点の数を指定します.
cx,cy…中心座標, r…半径, n…頂点の数, rotate…回転角, smooth…trueで滑らかする
smooth属性にtrueを指定することで滑らかな曲線とします(Catmull-Rom曲線).
star…星形
type="star"は星型を表します. circle型と同じく中心座標と半径及び頂点の数を指定します.
cx,cy…中心座標, r,r2…半径(長径/短径), n…頂点の数, rotate…回転角, smooth…trueで滑らかする
smooth属性にtrueを指定することで滑らかな曲線とします(Catmull-Rom曲線).
rstar…星形
type="rstar"は星型を表します. circle型と同じく中心座標と半径及び頂点の数を指定します. star型と異なり, 短径の長さを指定する必要がありません.
cx,cy…中心座標, r…半径, n…頂点の数, rotate…回転角, smooth…trueで滑らかする
smooth属性にtrueを指定することで滑らかな曲線とします(Catmull-Rom曲線).
radar…レーダー
type="radar"はレーダー図形を表します. circle型と同じく中心座標と中心からの距離のリストを指定します.
cx,cy…中心座標, rs…距離のリスト, rotate…回転角, smooth…trueで滑らかする
smooth属性にtrueを指定することで滑らかな曲線とします(Catmull-Rom曲線).
circles…同心円
type="circles"は同心円を表します.
cx,cy…中心座標, sr…開始半径, dr…半径の差分, times…繰り返す回数
grid…格子
type="grid"は格子図形を表します.
x,y,width,height…格子範囲, sx,sy…格子数, frame…trueで枠を付ける
radial…放射状図形
type="radial"は放射状図形を表します.
cx,cy…中心座標, r,r2…線の描画範囲, n…分割数, rotate…回転角
stamp…スタンプ
type="stamp"は指定した座標にスタンプ図形を配置します. スタンプ図形にはパス文字列を指定します.
points…図形を配置する位置, stamp…配置するスタンプ図形, rotate…回転角
culc属性と組み合わせるとstamp属性に他のカスタム図形を指定することが可能となります. 形式は次のとおりです.
{{gp('[型名]', {[パラメータ]})}}
下はスタンプ図形として星形を指定したものです.
rotate属性を指定するとスタンプ図形を回転します.
repeatstamp…スタンプを繰り返す
type="repeatstamp"は指定した座標を基準にスタンプ図形を繰り返し配置します.
x,y…図形を配置する基準位置, dx,dy…図形を配置する座標の差分値, count…繰り返しの回数, rotate…回転角, stamp…配置するスタンプ図形
arcstamp…スタンプを円弧に沿って繰り返す
type="arcstamp"は指定した中心座標を基準とした円弧にスタンプを等角度に配置します.
cx,cy…図形を配置する基準位置, r…図形を配置する円の半径, t…図形を配置開始角, dt…角度の差分値, count…繰り返しの回数, rotate…スタンプ図形の回転角, sync…trueで図形をスタンプ図形を回転する, stamp…配置するスタンプ図形
sync属性にtrueを指定すると, スタンプ図形も合わせて回転していきます.
pathstamp…パスに沿った図形配置
type="pathstamp"は指定したパスに沿ってスタンプ図形を配置します.
path…パス文字列, stamp…スタンプ図形, offset…図形配置の開始位置, space…図形の配置間隔, rotate…図形の回転角, sync…trueでパスの向きに沿う
g要素とpath型と組み合わせると, パス図形の定義を一箇所にまとめることが出来ます.
direction…有向線分
type="direction"は指定した座標から指定した角度・長さへの線分を表します.
x,y…線分の開始位置, length…線分の長さ, angle…角度
balloon…吹き出し
type="balloon"は吹き出し図形を描画します.
x,y…指し示す位置, cx,cy,rx,ry…楕円のパラメータと同様
fit…自動リサイズ
type="fit"はパス図形を指定した矩形範囲にフィットするように自動的にサイズを調整します. transform属性による変形と異なり, 直接パスを変形しているため, stroke幅等の制御を行う必要がありません.
x,y,width,height…図形を挿入する矩形範囲, path…図形を定義するパス文字列, preserveAspectRatio…アスペクト比の制御指定, bbox…path図形の描画範囲(x,y,width,height)
preserveAspectRatio値はSVG仕様と同じものを渡します. 例えば値をnoneを渡すことで枠いっぱいに図形を引き伸ばすことが可能です.
fit型はツールで生成したようなパス図形をカスタム図形化する際に便利です.
図形の描画範囲(bounding box/bbox)をbboxパラメータに設定しておくことが可能です.
parameter…パラメータ化したパス
type="parameter"はパラメータ化したパスを描画します. path属性に(そのままでは描画できない){p[0〜9]}というキーワードを挿入しておくと, 図形描画時にp0〜p9属性で指定した内容で置き換えた上で図形を描画します.
path…パラメータ化したパス, p0〜p9…パラメータの値. 全て数値として解釈されます.
この機能はツールから出力したSVGをスクリプトから操作するケースを想定しており, ある意味使い捨ての図形を用いる際に有効です.
f(x)…関数グラフ
type="f(x)"は関数グラフを描画します. 折れ線に依る近似図形を生成します. グラフを描く際の基準値を指定可能です.
f…関数式(変数名はx固定), from,to…変数xの定義域, count…折れ線に依る近似頻度, smooth…trueで滑らかに繋ぐ, origin…グラフを描く上での原点, units…グラフの単位描画サイズ(負値を指定することで軸を反転可能)
f(t)…関数グラフ(媒介変数形式)
type="f(t)"は媒介変数tによる関数グラフを描画します. 折れ線に依る近似図形を生成します.
fx,fy…関数式(変数名はt固定), from,to…変数tの定義域, count…折れ線に依る近似頻度, smooth…trueで滑らかに繋ぐ, origin…グラフを描く上での原点, units…グラフの単位描画サイズ(負値を指定することで軸を反転可能)
他の図形の形状を参照するもの
以下の図形はこれまでとは異なり, 別の図形の形状などから自身を描画します.
bbox…バウンディングボックス
type="bbox"は指定した図形要素のバウンディングボックスを描画します.
target…図形の参照先(省略すると直後の要素を参照)#[id]として指定
box…ボックス
type="bbox"は指定した図形要素を囲む矩形を描画します.
target…図形の参照先(省略すると直後の要素を参照)#[id]として指定, padding-x/y…余白, rx/ry…角の丸め半径
text要素に対してbox図形を描画することで文字列を枠で囲むことができます.
target属性を省略すると直後の図形を参照します.
autoballoon…自動吹き出し
type="autoballoon"は指定した図形要素に外接する吹き出しを描画します.
target…図形の参照先(省略すると直後の要素を参照)#[id]として指定, x,y…吹き出しの参照先
anchor…アンカー
type="anchor"は指定した図形要素に対して線分を引きます. 座標は参照している図形要素のバウンディングボックスを基準とします.
from…始点の参照先, to…終点の参照先, x1,y1…始点座標の直接指定, x2,y2…終点座標の直接指定, sref/eref…座標の指定基準. (t…上, b…下, l…左, r…右)
上手く組み合わせることで, 吹き出しのようなグラフィックを描くことが可能です.
カスタム図形を変形する
生成したカスタム図形はeffect属性を指定することで更に変形することが可能です． effect属性には変形毎に必要となるパラメータをCSSの書式に似たkey-value形式で記述します． typeプロパティに適用したい変形の名称を指定します．
none…無変換
type:none変形は変形を施しません． この値はg要素でeffect属性を集約した際， 一部のカスタム図形に限り変形を適用したくない場合に指定します．
2d…2d変形
type:2d変形はパス図形に平面変形を施します． 変形関数にはCSSのtransform関数と同じものを指定することが出来ます．
transform…変形関数
3d…3d変形
type:3d変形はパス図形に3D変形を施します． 変形関数にはCSSのtransform関数と同じものを指定することが出来ます．
transform3d…変形関数, torigin…変形の原点座標, perspective…視点の高さ, porigin…視点の座標
projection…射影変形
type:projection変形はパス図形に対して指定した矩形領域を任意の4点にマッピングするように3D変形を施します．
box…元となる矩形領域, p1,p2,p3,p4…矩形領域に対応する座標(左上，右上，右下，左下)
polar…極座標変換
type:polar変形はパス図形の座標情報を極座標(つまり， xを角度， yを原点からの距離)として解釈し， グラフィックを描画します．
cx,cy…極（原点）の座標, ut…1回転の長さ, ur…距離値の倍率, rotate…極変換の開始角, anticlock…trueで逆回転, delta…パスの精度
wavy…波状変換
type:wavy変換はパス図形を波打たせます．
ampx, lengthx, phasex…x軸方向の振幅幅, 波長, 位相(振幅のずれ)ampy, lengthy, phasey…y軸方向の振幅幅, 波長, 位相, delta…パスの精度
shapepath…パスに沿った変形
type:shapepath変換はパス図形をパスに沿って変形します．
path…変形の基準となるパス文字列， delta…パスの精度
freetransform…フリー変形
type:freetransform変形はパス図形を指定した関数で変形します． 関数指定の変数にはxとyを用います．
f…x座標を求める関数f(x,y), g…y座標を求める関数g(x,y) , delta…パスの精度
変形パスの精度
変形の種類・パスの内容によっては出力結果が美しく見えない場合があります． この場合， deltaプロパティの値に適当な値を設定することで改善するでしょう． (初期値は15)
effectプロパティの集約
カスタム属性と同様に, (1段に限り)上位g要素のeffect属性にプロパティ値を集約することが可能です． 下では5つの矩形に3d変形を施していますが， 図形のサイズ・視点・消失点の設定をg要素に集約しています． なお， transform属性などのような変形の掛け合わせはサポートしていません．