掩码转换器

在 JSF 格式化带掩码字符串值与 JavaScript™ 字符串之间进行转换。例如,字符串转换器先验证字符是否与掩码所指定的模式匹配,然后将字符串“171-38-4339”转换为“171384339”。

掩码转换器将验证字符串的内容是否与模式匹配。模式由“标记”和“字面值”组成。“标记”指定一些位置,这些位置必须包含属于指定字符集的字符。“字面值”也是一些位置,这些位置必须包含所指定的字符。除了检查字符是否有效以外,转换器还将插入文字以从字符串转换为带掩码字符串,或者除去文字以从带掩码字符器转换为字符串。

注意,成功地执行转换后,内容始终会“填满”整个掩码。例如,如果掩码允许尾部带有空格,则 valueToString 的结果将具有掩码长度并根据需要填充空格,而 stringToValue 的结果将是掩码长度减去字面值长度并同样填充空格。

JavaScript 构造函数

hX_5.addConverter("id", new hX_5.MaskConverter(attributes)); 其中

id

组件所连接至的 HTML 标记的 ID。

属性

表 1. 掩码转换器属性

属性名称

描述

掩码

字符串必须匹配的模式。请参阅下面的内容以了解详细信息。

protect-mask

保护“标记”位置中的字符免遭验证和输入,即,您可以“保护”字符串中包含标记(#、?、! 和 ~)的位置以便用户不能输入字符,取而代之的是按程序方式来设置该位置的值,该值通常在初始值中。这可以有效地将值中的字符转换为文字。如果提供了 protect-mask,则它与掩码应该是长度相同的字符串。如果位置中有 X(大写 X),则此位置已标记为“受保护”。不保护没有 X 的位置。

char1-regexpression

Java™ 正则表达式,用于对掩码中使用 # 字符进行标记的一些字符进行测试。如果未提供,则使用表达式 [0-9],即,该字符必须是一个数字。

char2-regexpression

Java 正则表达式,用于对掩码中使用 ? 字符进行标记的一些字符进行测试。如果未提供,则使用表达式 [A-Za-z],即,该字符必须是一个拉丁字母字符。

char3-regexpression

Java 正则表达式,用于对掩码中使用 ! 字符进行标记的一些字符进行测试。如果未提供,则不会将 ! 字符视为掩码字符。

char4-regexpression

Java 正则表达式,用于对掩码中使用 ~ 字符进行标记的一些字符进行测试。如果未提供,则不会将 ~ 字符视为掩码字符。

Mask

掩码定义一个值中的哪个位置允许哪些字符,并指定该位置包含的“字面值”字符。掩码包含以下内容:
  • 输入标记 - 特殊字符,指定掩码中的一个位置,在该位置允许任何与所指定字符集匹配的字符。
  • 字面值字符 - 掩码中的所有其他字符都被视为字面值。字符串的此位置必须包含字面值字符,并且只能包含该字符。

缺省情况下,允许使用两个输入标记字符,即 # 和 ?。并且,# 表示此处允许数字字符 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 字母字符

除了指定掩码中 # 和 ? 标记字符的出现位置所允许的字符以外,通过指定与这两个字符配合使用的正则表达式,还可以最多定义两个附加掩码字符 ! 和 ~。

例如,掩码 #???-!!!!! 以及:
  • char1-regexpression = [A-Z](char1 是 # 标记)
  • char2-regexpression = [A-Za-z0-9](char2 是 ? 标记)
  • char3-regexpression = [A-Za-z0-9 ](char3 是 ! 标记)

这表示字符串必须以大写字母开头,后跟至少三个字母数字字符,再后跟连字符。接着,最多可以后跟 5 个字母数字字符。

API 调用

表 2. 掩码转换器 API 调用

API 调用

描述

number = stringToValue(string)

将字符串转换为 JavaScript 数字对象。失败时返回 NULL。

string = valueToString(number)

将 JavaScript 数字转换为字符串。失败时返回 NULL。

string = lastError()

如果转换失败,则将失败原因作为本地化字符串返回。

object = setAttribute(attribute)

设置属性,或如果以前已设置属性,则更改其值。

string = getAttribute(attribute-name)

检索属性的当前值。

局限性

示例代码

将输入字段的带掩码值转换为字符串,“增大”结果值的其中一部分,然后返回该值。

// Construct the converter with a format of '?# feet ?#
inches' where # is any digit and ? is any non-zero digit or
space 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);

// Check for errors
if (d==null)
    alert ("ERROR: " + cvt.lastError());

// Increment the "inches" and put it back
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 页面

反馈