数値コンバーター

JSF 形式のストリング値と JavaScript™ 数値オブジェクトの間の変換を行います。例えば、数値コンバーターはストリング「$ 1,000.00」(入力フィールドの値の場合があります) を JavaScript 数値に変換します。

事実上、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 数値オブジェクトに 「キャスト」する必要があるプログラマーが直接使用することもできます。

JavaScript コンストラクター

hX_5.addConverter("id", new hX_5.NumberConverter(attributes)); 各部の意味は次のとおりです。

id

コンポーネントが付加される HTML タグの ID。

属性

表 1. 数値コンバーター属性

属性名

説明

pattern

この値を変換するときに 使用する Java の 数値パターン。

ICU4J

この属性が提供されている (かつ false でない) 場合、 アスタリスクとプラス記号がパターン文字として解析され、 さらにパターン内の 2 次グループ化記号が解析されます。

digits

西ヨーロッパ言語の「0」文字以外で、Unicode 文字セットにおいて 有効なゼロ数字を表す、単一文字の表記 (表記を指定する場合)。 この文字と、Unicode 文字セット内の以下の 9 文字とが、 値のフォーマット設定時に「digits」として出力され、 ストリングから値を変換するときに数字として解析されます。 これにより、 正式のアラビア数字および/またはインド・アラビア数字などの、 西ヨーロッパ言語以外の数字をサポートできるようになります。 この値は、この文字の Unicode コード・ポイントによって、10 進数で表されます。 例えば、アラビア数字のゼロは 16 進数では 660 になります。 この場合、1632 がこの属性の値になります。

locale

値の変換時に使用されるロケール情報。 クライアントの JavaScript では、 マシン上のローカライズ情報にアクセスできないため、 この情報を提供する必要があります (通常は、 クライアントのロケール情報と Java DecimalFormatSymbols クラスを 使用することによって、この情報をサーバー上で派生させます)。

この情報は、6 文字以上の GDMPINC という フォーマットのストリングとして提供されます。 各部の意味は以下のとおりです。

G

DecimalFormatSymbols.getGroupingSeparator (1 文字)。 グループ化セパレーター文字、すなわち「3 桁セパレーター」です。 例えば 1,000 における「,」が、これに当たります。

D

DecimalFormatSymbols.getDecimalSeparator (1 文字)。 小数点文字 (例えば 123.45 の場合の「.」)。
注: フォーマットが通貨の場合は、DecimalFormatSymbols.getMonetaryDecimalSeparator の方が 適しています。

P

DecimalFormatSymbols.getPercent (1 文字)。 パーセント文字。

I

DecimalFormatSymbols.getPerMill (1 文字)。 千分率記号。

N

DecimalFormatSymbols.getMinusSign (1 文字)。 負の符号文字 (例えば、-3.0 の場合の「-」)

C

DecimalFormatSymbols.getCurrencySymbol (ストリング)。 通貨記号 (例えば、$ (US))

例えば、「 ,%‰-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 桁マーカーの幅を 数えて決定されます。

JSF はまた、小数点の両側での埋め込みの指定を処理するために、 標準の Java 数値パターンを 拡張します。JSF 拡張マーカーが最後のサブパターンより後にある場合、 そのマーカーの後の文字は以下のように解釈されます。
  • 1 つの文字がマーカーの後に続き、数値に先行ゼロがある (つまり、 パターンに先行する 0 の文字がある) 場合、先行ゼロは表示されず、 各ゼロの代わりに提供された文字が表示されます。
  • 2 つの文字がマーカーの後に続き、数値に先行ゼロおよび末尾ゼロ (またはそのいずれか) がある (つまり、 パターン内に先行する 0 および末尾の 0 (またはそのいずれか) の文字がある) 場合、これらのゼロは表示されず、 各先行ゼロの代わりに最初に提供された文字が表示され、各末尾ゼロの代わりに 2 番目の文字が 表示されます。 値がゼロの場合、最初の文字によって小数点が置き換えられます。

言い換えると、これらの拡張は (提供された文字を使用して) 数値を「埋め込む」ために使用されます。 例えば、値 1 に 000/* を適用すると、 **1 と表示されます。

API 呼び出し

表 2. API 呼び出し

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:,.%‰-$"));
関連タスク
Faces JSP ページへの入力コンポーネントの追加

フィードバック