Screw-Axis /螺旋軸/

jQuery Spin

概要

jQuery Spinは、jQueryのプラグインとして動作します。
入力フォームで数値を扱うことがありますが、その際の入力補助用のインターフェースです。

動作

以下のフィールドに、数値を入力します。右側の上下のスピンボタンを使うと便利です。

マウスを押したままにすると、連続して値が変化します。

使い方

まずjQuery本体が必要になります。
jQueryそのものの導入については、別途ドキュメントなどを参照してください。

jQuery Spinは、Google Codeから入手してください。

まず最初にスクリプトの配置と共に、スピンボタンの表面画像を配置しなければなりません。
画像は「押されていない状態」「上が押された状態」「下が押された状態」の3枚が必要です。
サンプルとして、ダウンロードファイルにも画像が入っているので、参考にしながら独自の見た目を作ってください。

3枚の画像は、同じディレクトリに置かなければいけません。ここでは仮に、”/images/spin/”に配置したとします。

スピンボタンの設定は、spinメソッドを呼ぶだけで簡単に行うことが出来ます。
オプションには様々なものがありますが、画像の場所指定だけはきちんと行わないと、全く動作しなくなってしまいます。

$('input').spin({imageBasePath: '/images/spin/'});

画像の場所を示すimageBasePathオプションの初期値は”/img/spin/”です。この場所に置いた場合のみ、指定は省略できます。

しかし、ページに複数のスピンボタンを設置する場合など、毎回同じオプションを指定するのも馬鹿馬鹿しい場合があります。
そんな時は、$.spinオブジェクトに値を設定することで、すべての呼び出しの初期値を変えることができます。

$.spin.imageBasePath = '/images/spin/';
$('#sample1').spin();
$('#sample2').spin();
$('#sample3').spin();

この例では、3つのspinの呼び出し全てに”/images/spin/”が適用されます。

オプション

jQuery Spinは、多くのオプションで動作を指定することができます。
オプションは多くのプラグイン同様に、メソッドの引数としてオブジェクトを渡してやることで指定できます。
指定可能なオプションは、次の通りです。

imageBasePath

スピンボタンの表面画像の配置場所を示します。初期値は”/img/spin/”ですが、ここに運良く置けるのでない限り、必須指定項目lとなるでしょう。

spinBtnImage/spinUpImage/spinDownImage

順に、「通常時」「上を押した時」「下を押した時」の画像ファイル名です。通常は変える必要は無いはずです。

interval

値の増減幅です。例えばここに”3″と指定すれば、上下ボタンで3ずつ値が変化します。小数値を設定することも可能です。
初期値は1です。

max/min

入力可能な値の最大/最小値です。但し、直接入力の値を制限したりするものではないので、バリデーションには注意してください。値を設定しない場合、制限無しを意味します。

timeInterval

スピンボタンをマウスで押しっぱなしの状態にした際に、値の変化していく時間を決めます。小さな値を設定するほど、短い間隔で値が変化します。
初期値は500(ミリ秒)です。

timeBlink

見栄えとしての上が押された/下が押された状態の画像を表示する時間です。
初期値は200(ミリ秒)です。

btnClass

ボタン画像にあてられるクラス名です。

btnCss

ボタン画像にあてられるスタイルです。指定はCSSオブジェクトの形です。

txtCss

テキストエリアにあてられるスタイルです。

lock

テキストエリアへの直接入力を禁止したい場合にtrueにします。完璧に直接入力を防げるわけではなく、過信しすぎないよう注意してください。

decimal

小数点を”.”ではなくしたい場合に指定します。例えば”,”を指定すれば、”1.8″は”1,8″になります。

beforeChange

値がスピンボタンによって変更される前に呼ばれるコールバック関数です。
第一引数にこれから変更されようとしている新しい値、第二引数には現時点の値が渡されます。戻り値にfalseを返した場合、その変更はキャンセルされます。

changed

値が変更された後に呼び出されるコールバック関数です。

buttonUp/buttonDown

上下のスピンボタンが押された際に呼び出されるコールバック関数です。値が上限を超えているなどの理由で変更されない場合にも呼び出されます。

$.spinオブジェクトの値を変えることで、オプションの初期値を変えてしまうことも可能です。

ここでは、幾つかのオプションを組み合わせた例を見てみましょう。

$('#sample1').spin({
  imageBasePath: 'http://dev.screw-axis.com/jquery-spin/demo/img/spin2/',
  interval: 10,
  max: 300,
  min: 0,
  timeInterval: 250
});

[実行結果]

プロジェクトサイト

• 本家プラグインリポジトリ
• Google Code
• github

ライセンス

コードにも記載していますが、MITとGPLのデュアルライセンスとします。
全く自由に使っていただいて構いませんが、どこかで利用したり紹介していただいた際は、ご一報いただけると喜ぶと思います。