事実上、JSF 数値コンバーターは Java™ DecimalFormat クラスの JavaScript 実装です。
NumberConverter は、 ストリング (入力フィールドの値であることが多い) を JavaScript 数値オブジェクトに変換し、また、その逆を行います。この変換は、数値のフォーマット (例えば、通貨記号、小数点、グループ化、 負符号) を記述する Java DecimalFormat パターンによって管理されています。
2 つの Java DecimalFormat クラスがサポートされています。Java 1.4x/1.5x には標準クラスが、 ICU4J には拡張クラスが提供されています。ICU4J クラスは、Java クラスの拡張 (およびバグ修正) です。
NumberConverter が使用するパターンは「ロケール中立」です。パターンは、 小数点を表示する場所、グループ化記号を表示する場所などを示す「論理」マーカーを使用します。 コンストラクターに渡される別個の属性は、 フィールドに表示されるロケール依存記号を、パターンで論理マーカーによって示される位置に指定します。 例えば、パターンは . 文字 (ピリオド文字) を使用して、 数値内で小数点を表示する場所を記述します。 ロケールは、値とストリングの間で変換が行われるときに、 小数点として使用する文字 (例えば、スペース文字) を別個に指定します。
NumberConverter は、Java NumberFormat クラスで使用されるのと同じアルゴリズムを使用して数値/ストリングを変換するため、クライアント・サイド変換とサーバー・サイド変換は同じになり、非常に実用的です。
コンバーターは、JSFBehaviorValidate、NumberAssist (数値入力のキーボード補助機構)、 クライアント・サイド・データ・キャッシングなどの他のクライアント・サイド・コンポーネントによって使用されます。 また、フォーマット済みの数値が含まれるストリングを JavaScript 数値オブジェクトに 「キャスト」する必要があるプログラマーが直接使用することもできます。
hX_5.addConverter("id", new hX_5.NumberConverter(attributes)); 各部の意味は次のとおりです。
id |
コンポーネントが付加される HTML タグの ID。 |
属性名 |
説明 |
||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pattern |
この値を変換するときに 使用する Java の 数値パターン。 |
||||||||||||
ICU4J |
この属性が提供されている (かつ false でない) 場合、 アスタリスクとプラス記号がパターン文字として解析され、 さらにパターン内の 2 次グループ化記号が解析されます。 |
||||||||||||
digits |
西ヨーロッパ言語の「0」文字以外で、Unicode 文字セットにおいて 有効なゼロ数字を表す、単一文字の表記 (表記を指定する場合)。 この文字と、Unicode 文字セット内の以下の 9 文字とが、 値のフォーマット設定時に「digits」として出力され、 ストリングから値を変換するときに数字として解析されます。 これにより、 正式のアラビア数字および/またはインド・アラビア数字などの、 西ヨーロッパ言語以外の数字をサポートできるようになります。 この値は、この文字の Unicode コード・ポイントによって、10 進数で表されます。 例えば、アラビア数字のゼロは 16 進数では 660 になります。 この場合、1632 がこの属性の値になります。 |
||||||||||||
locale |
値の変換時に使用されるロケール情報。 クライアントの JavaScript では、 マシン上のローカライズ情報にアクセスできないため、 この情報を提供する必要があります (通常は、 クライアントのロケール情報と Java DecimalFormatSymbols クラスを 使用することによって、この情報をサーバー上で派生させます)。 この情報は、6 文字以上の GDMPINC という
フォーマットのストリングとして提供されます。
各部の意味は以下のとおりです。
例えば、「 ,%‰-FR」とある場合、 グループ化セパレーターとしてスペースを、桁区切り記号としてコンマを、 パーセント記号としてパーセント符号を、 千分率記号として千分率符号を、 負記号として負符号を、通貨記号として FR を、 それぞれ使用することを意味します。 したがって、フォーマットが「¤ #,##0.00」であった場合、 例で示される数値は「FR 1 23,45」になります。 |
||||||||||||
strict |
ストリングを数値に変換する際の、変換の厳密性を定義します。 この値が高ければ高いほど、 より正確にパターンに適合する必要がある、ということになります。 数値の場合、厳密性のレベル 0 と 1 は、現在のところ同等になっています。 厳密性を 2 にすると、 数値に符号が付いているときは、 その符号を指定する必要があります (指定されていない場合は、 正の値であると見なされます)。 |
Java 10 進形式数値パターンについて詳しくは、http://java.sun.com/j2se/1.4.2/docs/api/java/text/DecimalFormat.html (ICU4J 属性セットなしで稼働している場合) および http://icu.sourceforge.net/apiref/icu4j/ (ICU4J 属性が設定されている場合) を参照してください。構文を要約するため、パターンは、 フォーマット文字のシーケンスで構成されています。ここでの各文字は、数値内のその位置で許可されるものを表しています。 基本的なフォーマット文字は以下のとおりです。
0 |
数字。ゼロの場合は表示されます。 |
# |
数字。先行または末尾ゼロの場合、表示されません (抑止されます)。 |
. |
小数点または通貨の小数点。 |
, |
グループ化セパレーター。 |
* |
ICU4J がオンの場合は、埋め込みエスケープ文字。埋め込みが行われるマスク。 * の後に続く文字は、埋め込み文字として使用されます。 |
E |
浮動小数で小数部と指数を分離します。 |
+ |
ICU4J がオンの場合は E の後に配置する必要があり、存在する場合は、 正の指数は先頭に正符号が付いて表示されることを意味します。 |
; |
サブパターン境界マーカー。 ; の前のサブパターンは正の値を定義し、 ; の後のサブパターンは負の値を定義します。 |
/ |
JSF 拡張マーカー。存在する場合は、最後のサブパターンの後に配置します。 使用法については、以下を参照してください。 |
ICU4J 記号 1 から 9 (丸め) および @ (有効数字) はサポートされていないことに注意してください。
パターンは、数値内の最大桁数を定義する 0 と # 記号のシーケンスで構成されています。 # 記号は、 先行/末尾ゼロである場合には抑止される桁を示します。0 記号は、 抑止されない桁を示します。 # 記号は、小数点の左では 0 記号より前、 小数点の右側では 0 記号より後になければなりません (例えば、#0# は許可されません)。10 進記号は、(ローカライズされた) 10 進数が表示される位置に マークを付けます。3 桁マーカーは、ローカライズされたグループ化記号が表示される場所を 定義します (グループ化文字が提供されている場合、小数点の左にある最初の「グループ」は、 全般に使用されるグループ化パターンを定義します)。 ICU4J がオンになっている場合、(1 つではなく) 最大 2 つの 3 桁マーカーが使用されます。 ここで、2 つの記号は 1 次グループと 2 次グループのマークを付けます (インド語以外のすべての言語で、 2 つのマーカーが提供されている場合は、同じグループ化 (例えば、3 桁) を持ち、 インド語では、異なるグループ化を指定する場合があります)。指数マーカーは、 この数値が指数フォーマットを使用することを示します。 (サブパターン境界マーカーを使用して) パターンのペアが提供されている場合、最初のパターンは正の値を定義し、 2 番目のパターンは負の値を定義します。数値が指数フォーマットの場合、 正符号は E の後 (唯一の有効な位置) に置かれ、指数が常に符号 (正または負) とともに 表示されることを示します。
例えば、パターン「###」は、この数値が、先行ゼロが抑止される最大 3 つの数字 で構成されることを意味します。パターン ##0.00 は、 この数値が、最大 3 つの数字、小数点、および 2 つの小数桁で構成されることを意味します。 小数桁は常に表示されます。パターン ###,###,##0.00 は、 小数点の左側に最大 9 つの数字と、小数位 3 桁ごとにグループ化 (3 桁) セパレーターが 表示されることを意味します。小数点の左には、常に少なくとも 1 つの数字が表示され (追加の先行ゼロは抑止されます)、小数点の右には常に 2 つの数字が表示されます。
それ以外の文字は、 リテラル接頭部または接尾部としてパターンに追加できます。 例えば、$ ### は、リテラル文字「$」が数値の前に表示されることを意味します。 接頭部/接尾部での以下の文字には、特殊な意味があります。
各部の意味は次のとおりです。
' |
接頭部または接尾部で特殊文字を引用符で囲むために使用し、 例えば、「'#'#」は 123 を「#123」とフォーマットします。単一引用符自体を作成するには、 1 行で 2 つ使用し、「# o''clock」とします。 |
% |
数値はパーセント (1/100) として処理されます。つまり、100 で乗算され、 パーセント記号がこの位置に表示されます。 |
‰ |
数値は 1000 分の 1 (千分率) として処理されます。つまり、 1000 で乗算され、千分率の記号がこの位置に表示されます。 |
¤ |
ロケール情報で指定された通貨記号が、この位置に表示されます。 |
これらの記号 (引用符を除く) は、左または右接頭部のいずれかのみで表示されるのであり、 両方ではないという Java 制限に注意してください。
埋め込みを値に追加する方法は 2 つあります。ICU4J がオンになっている場合、 接頭部の前、接頭部の直後、 接尾部の直前、またはサブパターンの最後にアスタリスクが挿入されます。アスタリスクの後には、 値を埋め込むために使用される文字が続きます。マークが付けられた位置に埋め込み文字を挿入することによって、 値は最大幅まで埋め込まれます。 最大幅は、正のパターンの接頭部、接尾部、数字、小数点、および 3 桁マーカーの幅を 数えて決定されます。
言い換えると、これらの拡張は (提供された文字を使用して) 数値を「埋め込む」ために使用されます。 例えば、値 1 に 000/* を適用すると、 **1 と表示されます。
API 呼び出し |
説明 |
---|---|
number = stringToValue(string) |
ストリング を JavaScript の 数値オブジェクトに変換します。 失敗した場合は NULL を戻します。 |
string = valueToString(number) |
JavaScript の 数値を、ストリングに変換します。 失敗した場合は NULL を戻します。 |
string = lastError() |
変換が失敗すると、 失敗の理由をローカライズされたストリングとして戻します。 |
object = setAttribute(attribute) |
属性を設定します。 属性がすでに設定されたものである場合は、 その値を変更します。 |
string = getAttribute(attribute-name) |
属性の現行値を取得します。 |
入力フィールドの値を JavaScript 数値に変換し、 1 を加算し、結果を保管します。
// パターン $ ###,##0.00;($ ###,##0.00) でコンバーターを構成します。 hX.addConverter("AZ0", new hX.NumberConverter("pattern:$ ###,##0.00;($ ###,##0.00)", "strict:2", "locale:,.%‰-$")); // 入力フィールドの値を、このパターンを使用してフォーマットされたストリングから JS 数値に変換します。 var x = document.getElementById("form1:text0"); var cvt = hX.getConverterById("AZ0"); var num = cvt.stringToValue(x.value); // エラーを検査します if (num==null) alert ("ERROR: " + cvt.lastError()); // 値を増分して戻します else { num++; x.value = cvt.valueToString(num);
上記のように、 ただし、アラブ・インド数字を許可し、2 つの 3 桁グループ化を指定し、 ICU4J 埋め込みを使用して通貨記号の後に数値を埋め込みます。
// 埋め込み文字および代替グループ化として、アスタリスクを使用してコンバーターを構成します hX.addConverter("AZ0", new hX.NumberConverter("ICU4J", "digits:1632", "pattern:$ **###,##,##0.00;($ ###,##0.00)", "strict:2", "locale:,.%‰-$"));