マスク・コンバーター

JSF 形式のマスクされたストリング値と JavaScript™ ストリングの間の変換を行います。 例えば、ストリング・コンバーターは、マスクで指定されたパターンに文字が一致することを検証した後、 ストリング「171-38-4339」を「171384339」に変換します。

マスク・コンバーターは、ストリングのコンテンツがパターンに一致することを 検証します。パターンは、指定された文字セットに属する文字が存在しなければならない位置を 指定する「マーカー」、および指定された文字そのものが存在しなければならない位置である「リテラル」 で構成されています。 有効な文字を検査する他に、コンバーターはリテラルを挿入するか (ストリングから マスクされたストリングに変換)、リテラルを削除します (マスクされたストリングから ストリングへ変換)。

正常な変換の結果は、常にマスクのフルサイズまで 「埋め込み」が行われます。例えば、マスクが末尾のスペースを許可する場合、 valueToString の結果はマスクの長さで (必要に応じてスペースが埋め込まれます)、 stringToValue の結果はマスクなしのリテラルの長さです (スペースが埋め込まれます)。

JavaScript コンストラクター

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

id

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

属性

表 1. マスク・コンバーター属性

属性名

説明

mask

ストリングの一致が必要なパターン。 詳しくは、以下を参照してください。

protect-mask

「マーカー」の位置にある文字を保護し、 検証や入力の対象にならないようにします。 つまり、ストリング中のマーカー (#、?、!、~) を含む 位置が保護されるため、ユーザーが文字を入力できなくなる、 ということです。 この文字位置の値は、プログラマチックに 設定することもできます (通常は、初期値で設定します)。 これにより、値の文字は実質上リテラルとなります。 protect-mask が指定されている場合、 マスクと同じ長さのストリングにする必要があります。 特定の桁に X (大文字) を指定すると、プロテクト対象としてマークすることができます。 X が指定されていない桁はプロテクトされません。

char1-regexpression

マスク内の # というマークの付いた文字の テストに使用する、Java™ の 正規表現。 特に指定がない場合は、式 [0-9] が 使用されます (つまり、対象となる文字は数字でなければなりません)。

char2-regexpression

マスク内の ? というマークの付いた文字の テストに使用する、Java の 正規表現。 特に指定がない場合は、 式 [A-Za-z] が使用されます (つまり、対象となる文字は ローマ英字でなければなりません)。

char3-regexpression

マスク内の ! というマークの付いた文字の テストに使用する、Java の 正規表現。 これが指定されないと、! 文字はマスク文字として処理されません。

char4-regexpression

マスク内の ~ というマークの付いた文字の テストに使用する、Java の 正規表現。 これが指定されないと、~ 文字はマスク文字として処理されません。

マスク

マスクは、値のどの位置でどの文字を許可するかを定義し、 そこに表示される「リテラル」文字を指定します。 マスクの構成は次のとおりです。
  • 入力マーカー - 指定された文字セットと一致するすべての文字が許可される マスクでの位置を指定する特殊文字。
  • リテラル文字 - マスク内のその他のすべての文字はリテラルとして 処理されます。リテラル文字 (この文字のみ) は、ストリングでこの位置に表示される 必要があります。

デフォルトでは、2 つの入力マーカー文字 # および ? (ポンド記号および疑問符) があります。デフォルトでは、# は、「0 から 9 の数字」が 許可されることを意味し、? は、「a から z および A から Z のラテン英字」が許可されることを 意味します。

このマーカーとリテラルを組み合わせた マスク「###-##-####」は、米国の社会保障番号を定義します。 つまり、値では、マスク内の # のある各場所には数字が入り、 マスク内の - のある各場所には - が入ります。 そのため、「191-33-1897」はこのマスクに一致します。「191 33 1897」は マスクに一致せず、「191-33-189」も一致しません。

# および ? マーカー文字 (数字および英字) に割り当てられた デフォルトの文字セットを使用する代わりに、マークが付けられた位置で文字をテストするために実行する Java 正規表現を指定することによって、 各マーカーに対して独自の文字セットを定義することができます。正規表現は、 単一文字が一致するか、一致しないかを評価します。 例えば、次のようにします。

[A-Z]

この位置では、大文字のラテン英字が許可されます

[A-Za-z ]

大文字および小文字のラテン英字とスペースが許可されます

[A-Za-z¥u00C0-¥u00D6¥u00D8-¥u00F6¥u00F8-¥u00FF]

ISO 8859-1 英字が許可されます

マスク内では、 # および ? マーカー文字によって許可される文字を指定できるだけでなく、最大 2 つのマーカー文字 (! および ~) を追加して定義し、これらの 2 つの文字で使用される正規表現を指定 することができます。

例えば、マスク #???-!!!!! と以下を組み合わせます。
  • char1-regexpression = [A-Z] (char1 は # マーカー)
  • char2-regexpression = [A-Za-z0-9] (char2 は ? マーカー)
  • char3-regexpression = [A-Za-z0-9 ] (char3 は ! マーカー)

ストリングは、 大文字で始まり、その後に少なくとも 3 つの英数字、およびダッシュが続くことを意味します。この後に、最大で 5 つの英数字が 続きます。

API 呼び出し

表 2. マスク・コンバーター API 呼び出し

API 呼び出し

説明

number = stringToValue(string)

ストリング を JavaScript の 数値オブジェクトに変換します。 失敗した場合は NULL を戻します。

string = valueToString(number)

JavaScript の 数値を、ストリングに変換します。 失敗した場合は NULL を戻します。

string = lastError()

変換が失敗すると、 失敗の理由をローカライズされたストリングとして戻します。

object = setAttribute(attribute)

属性を設定します。 属性がすでに設定されたものである場合は、 その値を変更します。

string = getAttribute(attribute-name)

属性の現行値を取得します。

制限

サンプル・コード

入力フィールドの (マスクされた) 値をストリングに変換し、結果値の一部を「増分」し、 結果を戻します。

 // フォーマット「?# feet ?#
inches」を使用してコンバーターを作成します。ここで、# は任意の数字、? はゼロ以外の任意の数字または
スペース hX.addConverter("AZ1", new hX.MaskConverter
("mask:?# feet ?# inches", "strict:2", 
"char2-regexpression:[1-9 ]"));

var x = document.getElementById("form1:textA");
var cvt = hX.getConverterById("AZ1");
var d = cvt.stringToValue(x.value);

 // エラーを検査します
if (d==null)
    alert ("ERROR: " + cvt.lastError());

 // 「inches」を増分して戻します。
else {
	var n = parseInt(d.substr(2),10)+1;
	if (n <= 12)
		d = d.substr(0,2)+((n<10)?" ":"")+n;
	else {
		d = (parseInt(d.substr(0,2),10)+1)+"";
		if (d.length==1) d = " " + d;
		d = d.substr(0,2)+" 1";
	}
    x.value = cvt.valueToString(d);
}
関連タスク
Faces JSP ページへの入力コンポーネントの追加

フィードバック