Dojoに付属する各種ユーティリティ

Dojoのコアライブラリには、文字列、日付、数値、JSONなどに関するユーティリティも含まれている。使用法は非常に簡単なので、簡単に紹介しておこう。

文字列ユーティリティ

文字列に関するユーティリティは、dojo.stringというモジュールに含まれている。このモジュールは、通常のビルドではdojo.jsに含まれていない。そのため、以下のように同モジュールを動的に読み込む必要がある。

 <script type="text/javascript">

   // requireを使用したモジュールの読み込み
   dojo.require("dojo.string");

   ...(以下、dojo.stringを利用可能)
 </script>

dojo.stringに含まれるメソッドは以下のようなものがある。

dojo.string.pad(text, size, ch, end)

sizeで指定された長さまで、chで指定された文字列を、textの前に付与する。引数endにtrueを指定すると、textの後に文字が付与されるようになる。chとendは省略可能で、chを省略した場合は'0'が付与される。 使用例は以下のようになる。

 dojo.string.pad("123", 5);            // "00123"
 dojo.string.pad("123", 5, "X");       // "XX123"
 dojo.string.pad("123", 5, "X", true); // "123XX"

dojo.string.substitute(template, map, transform, thisObject)

「${ }」という形式でプレースホルダを埋め込まれた文字列を、mapに与えられたオブジェクトの情報で置換した結果を返す。プレースホルダは「${0}」のように数値を指定するか、「${name}」のように文字列を指定することができる。mapには配列かオブジェクトを指定でき、数値指定のプレースホルダは配列のインデックスと、文字列指定のプレースホルダはオブジェクトのプロパティと対応する。説明するよりも、使用例を見た方がわかりやすいだろう。

 dojo.string.substitute("Hello, ${0}!", ["白石"]); // "Hello, 白石
 dojo.string.substitute("Hello, ${name}!", {name: 白石}); // "Hello, 白石

また第三引数には、マッチした文字列をさらに変換するための関数を指定できる。たとえば、「<」を「&lt;」に変換したり、URI形式にエンコードしたり、といった事が可能だ。第四引数には、その関数内で使用するthisオブジェクトを指定できる。

 // encodeURIComponentを使用して変換
 // 結果は"http://example.jp/?name=%E4%BF%8A%E5%B9%B3"
 dojo.string.substitute("http://example.jp/?name=${0}",
                       ["白石"], encodeURIComponent);

dojo.trim(str), dojo.string.trim(str)

これらはどちらも、文字列の前後から空白を取り除くためのメソッドだ。前者はdojo.jsに含まれているため、dojo.require()が必要ない。 また、パフォーマンスも前者の方が良好とのことなので、dojo.string.trim()を使用する機会は皆無に等しい。

日付ユーティリティ

日付に関するユーティリティは、dojo.dateモジュール内にある。「dojo.require("dojo.date")」の呼び出しが必要だ。

dojo.date.getDaysInMonth(dateObject)

指定された日付オブジェクトの、月が何日まであるかを返す(1月→31日など)。

dojo.date.isLeapYear(dateObject)

指定された日付がうるう年かどうかを返す

dojo.date.compare(date1, date2, portion)

date1がdate2よりも後の日付/時刻なら正の値、同じなら0、前の日付なら負の値が返る。portionに指定できる値は"date", "time", "datetime"。

dojo.date.add(date1, interval, amount)

日時を指定した数値分操作する。intervalには操作する単位を指定する。intervalに指定できる値は"year", "month", "day", "hour", "minute", "second", "millisecond", "quarter", "week", "weekday"のいずれか。

 // 同じ時刻で、日付を1日前にずらす
 var now = new Date();
 var yesterday = dojo.date.add(now, "day", -1);

dojo.date.difference(date1, date2, portion)

二つのDateオブジェクト間の差分を数値で取得する。第三引数には、上のdojo.date.add()のintervalに指定した文字列と同じものを使用でき、差分をとる単位を指定する。

 // 時間の差を秒単位で取得する
 dojo.date.difference(now, yesterday, "second")

dojox.date.posix.strftime(dateObject, format, locale)

日付オブジェクトを文字列にフォーマットする。この関数はコアライブラリではなく「dojox.date」モジュールに含まれている (dojo.requireが必要)。フォーマット文字列に指定できる文字は、POSIXで規定されたC言語のstrftime()関数の仕様 に準ずる。また、日付のフォーマット用に「dojox.date.php」モジュールも用意されているが、こちらには現在のところバグがあるようなので、使用はお薦めしない。

 // 日付を「2007年11月13日 17時54分32秒」のようにフォーマットする
 dojox.date.posix.strftime(yesterday, "%Y年%m月%d日 %H時%M分%S秒")

数値ユーティリティ

ここでは、数値のフォーマットやパースに使用する関数を紹介しておこう。

dojo.number.format(num, options)、dojo.number.parse(numStr, options)

format()は数値のフォーマット、parse()は数値文字列の解析に使用するメソッドだ。使用するためには「dojo.require("dojo.number")」が必要。省略可能なoptionsは、フォーマット/解析のパターンなどを指定する。使用されるパターンは以下のように決定される。

  1. 「options.pattern」が存在すれば、それが利用される
  2. 「options.type」が存在する場合、それに「Format」を付けた文字列をキーとし、「dojo/cldr/nls/number.js」からパターンが検索され、利用される (国際化フレームワークを利用)
  3. 上の二つを満たさない場合は、2で述べたリソースファイルから、「decimalFormat」で取得できるパターンが利用される

少し複雑なようだが、以下の使用例を見て理解を深めていただきたい。完全に理解するには、国際化フレームワーク (後述) に関する知識が不可欠だ。パターンは、こちらのページ に書かれた仕様に則って解釈される。

 // 1,054.60
 dojo.number.format(1054.6, {pattern: "#,##0.00"});
 // 105,460%
 dojo.number.format(1054.6, {type: "percent"});
 // 1,054.6 (decimalFormatは#,##0.##と定義されている)
 dojo.number.format(1054.6);

 // パターンを指定して数値文字列を解析。
 // 解析に失敗するとNaNが返る。
 dojo.number.parse("1,054.60", {pattern: "#,##0.00"});

JSONユーティリティ

JavaScriptとJSON文字列を相互に変換する関数が、dojo.js内で提供されている。dojo.require()は必要ない。

toJson(obj, prettyPrint, _indentStr)

オブジェクトをJSON文字列に変換する。第二、第三引数は省略可能。prettyPrintを指定すると、インデント付きの、人が読みやすい形式で文字列が構築される。_indentStrは、インデントに使用する文字列を使用する (デフォルトはタブ)。ただ、_indentStrは意図したとおりに動かない (2レベル目以降のインデントはやはりタブになってしまう) ので、使わない方が無難だ。

fromJson(json)

JSON文字列をJavaScriptオブジェクトに変換する。json.jsなどと違い、内部ではeval()を呼び出しているので、高速に動作する。