javax.swing.text
类 MaskFormatter

java.lang.Object
  javax.swing.JFormattedTextField.AbstractFormatter
      javax.swing.text.DefaultFormatter
          javax.swing.text.MaskFormatter

所有已实现的接口：

Serializable, Cloneable

public class MaskFormatter
extends DefaultFormatter

MaskFormatter 用于格式化和编辑字符串。MaskFormatter 的行为通过 String 掩码控制，该掩码指定可以包含在 Document 模型中特定位置的有效字符。可以指定以下字符：

字符	描述
#	任何有效数字，使用 Character.isDigit。
'	转义字符，用于避开任何具有特殊格式的字符。
U	任何字符 (Character.isLetter)。将所有小写字母映射为大写。
L	任何字符 (Character.isLetter)。将所有大写字母映射为小写。
A	任何字符或数字（Character.isLetter 或 Character.isDigit）
?	任何字符 (Character.isLetter)。
*	所有字符。
H	任何十六进制字符（0-9、a-f 或 A-F）。

字符通常对应于一个 char，但在某些语言中不是这样。掩码是以单个字符为基础的，因此可以任意调整 char 数量来满足需要。

可以进一步限制可通过 setInvalidCharacters 和 setValidCharacters 方法输入的字符。setInvalidCharacters 允许指定哪些字符无效。setValidCharacters 允许指定哪些字符有效。例如，以下代码块与具有无效/有效字符的 '0xHHH' 掩码等效：

 MaskFormatter formatter = new MaskFormatter("0x***");
 formatter.setValidCharacters("0123456789abcdefABCDEF");
 

最初格式化值时，如果字符串的长度小于掩码的长度，则可能发生以下两种情况。要么使用占位符字符串，要么使用占位符字符。优先考虑使用占位符字符串。例如：

   MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   formatter.getDisplayValue(tf, "123");
 

可能生成字符串 '123-____'。如果已调用 setPlaceholder("555-1212")，则生成 '123-1212'。占位符字符串只用于初始格式，后续格式只使用占位符字符。

如果 MaskFormatter 配置为只允许有效字符 (setAllowsInvalid(false))，则在编辑时将根据需要跳过字面值字符。假定 MaskFormatter 带有掩码 "###-####"，且当前值为 "555-1212"。使用右箭头键通过字段导航将生成（| 指示插入符的位置）：

   |555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212
 

'-' 为字面值（不可编辑的）字符，将跳过这一字符。

编辑时会导致类似行为。假定在前一示例中将字符串 '123-45' 和 '12345' 插入 MaskFormatter。两项插入都将导致相同的字符串 '123-45__'。MaskFormatter 在字符位置 3（即 '-'）处理插入时，可能发生以下两种情况：

1. 如果插入的字符是 '-'，则接受它。
2. 如果插入的字符与下一个非字面值字符的掩码匹配，则在新位置接受它。
3. 其他任何情况都将导致无效的编辑

默认情况下，MaskFormatter 将不允许无效编辑，您可以使用 setAllowsInvalid 方法更改此设置，并在有效编辑状态提交编辑（使用 setCommitsOnValidEdit 更改此设置）。

默认情况下，MaskFormatter 处于改写模式。也就是说，键入字符时不插入新字符，而是使用新键入的字符替换当前位置的字符。可以通过方法 setOverwriteMode 更改此行为。

警告：此类的已序列化对象与以后的 Swing 版本不兼容。当前序列化支持适用于短期存储或运行相同 Swing 版本的应用程序之间的 RMI。从 1.4 版本开始，已在 java.beans 包中添加了支持所有 JavaBeans^TM 长期存储的功能。请参见 XMLEncoder。

从以下版本开始：

1.4

构造方法摘要

MaskFormatter()
创建一个不带掩码的 MaskFormatter。

MaskFormatter(String mask)
创建具有指定掩码的 MaskFormatter。

方法摘要

String	getInvalidCharacters() 返回输入无效的字符。
String	getMask() 返回格式化掩码。
String	getPlaceholder() 如果值未完全填充掩码，则返回要使用的 String。
char	getPlaceholderCharacter() 返回用来替代值中没有的字符的字符（即用户必须填充它们）。
String	getValidCharacters() 返回可以输入的有效字符。
boolean	getValueContainsLiteralCharacters() 如果 stringToValue 应该返回掩码中的字面值，则返回 true。
void	install(JFormattedTextField ftf) 将 DefaultFormatter 安装在特定的 JFormattedTextField 上。
void	setInvalidCharacters(String invalidCharacters) 允许进一步限制可以输入的字符。
void	setMask(String mask) 设置指示合法字符的掩码。
void	setPlaceholder(String placeholder) 设置值未完全填充掩码时要使用的字符串。
void	setPlaceholderCharacter(char placeholder) 设置一个字符，用来替代值中不存在的字符（即用户必须填充它们）。
void	setValidCharacters(String validCharacters) 允许进一步限制可以输入的字符。
void	setValueContainsLiteralCharacters(boolean containsLiteralChars) 如果为 true，则返回的值和设置的值还将包含掩码中的字面值字符。
Object	stringToValue(String value) 解析文本，返回 String value 的适当 Object 表示形式。
String	valueToString(Object value) 返回基于掩码的 Object value 的 String 表示形式。

从类 javax.swing.text.DefaultFormatter 继承的方法

clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass

从类 javax.swing.JFormattedTextField.AbstractFormatter 继承的方法

getActions, getFormattedTextField, invalidEdit, setEditValid, uninstall

从类 java.lang.Object 继承的方法

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

MaskFormatter

public MaskFormatter()

创建一个不带掩码的 MaskFormatter。

MaskFormatter

public MaskFormatter(String mask)
              throws ParseException

创建具有指定掩码的 MaskFormatter。如果 mask 不是有效掩码，则抛出 ParseException。

抛出：

ParseException - 如果掩码不包含有效掩码字符

方法详细信息

setMask

public void setMask(String mask)
             throws ParseException

设置指示合法字符的掩码。如果 mask 无效，这将抛出一个 ParseException。

抛出：

ParseException - 如果掩码不包含有效掩码字符

getMask

public String getMask()

返回格式化掩码。

返回：

指示合法字符值的掩码。

setValidCharacters

public void setValidCharacters(String validCharacters)

允许进一步限制可以输入的字符。只允许输入在掩码中指定的（不是 invalidCharacters，而是 validCharacters）字符。传入 null（默认）意味着有效字符只由掩码和无效字符限定范围。

参数：

validCharacters - 如果为非 null，则指定合法字符。

getValidCharacters

public String getValidCharacters()

返回可以输入的有效字符。

返回：

合法字符

setInvalidCharacters

public void setInvalidCharacters(String invalidCharacters)

允许进一步限制可以输入的字符。只允许输入在掩码中指定的（不是 invalidCharacters，而是 validCharacters）字符。传入 null （默认）意味着有效字符只由掩码和有效字符限定范围。

参数：

invalidCharacters - 如果为非 null，则指定非法字符。

getInvalidCharacters

public String getInvalidCharacters()

返回输入无效的字符。

返回：

非法字符。

setPlaceholder

public void setPlaceholder(String placeholder)

设置值未完全填充掩码时要使用的字符串。null 值意味着应该使用占位字符。

参数：

placeholder - 值未完全填充掩码的情况下格式化时使用的字符串

getPlaceholder

public String getPlaceholder()

如果值未完全填充掩码，则返回要使用的 String。

返回：

如果值未完全填充掩码，则返回格式化时使用的 String

setPlaceholderCharacter

public void setPlaceholderCharacter(char placeholder)

设置一个字符，用来替代值中不存在的字符（即用户必须填充它们）。默认值为一个空格。

此方法仅适用于占位符字符串尚未指定，或未完全填充掩码的情况。

参数：

placeholder - 如果值未完全填充掩码，则为格式化时使用的 Character

getPlaceholderCharacter

public char getPlaceholderCharacter()

返回用来替代值中没有的字符的字符（即用户必须填充它们）。

返回：

如果值未完全填充掩码，则返回格式化时使用的 Character

setValueContainsLiteralCharacters

public void setValueContainsLiteralCharacters(boolean containsLiteralChars)

如果为 true，则返回的值和设置的值还将包含掩码中的字面值字符。

例如，如果掩码为 '(###) ###-####'，当前值为 '(415) 555-1212'，且 valueContainsLiteralCharacters 为 true，则 stringToValue 将返回 '(415) 555-1212'。另一方面，如果 valueContainsLiteralCharacters 为 false，则 stringToValue 将返回 '4155551212'。

参数：

containsLiteralChars - 用于指示掩码中的字面值是否应该在 stringToValue 中返回。

getValueContainsLiteralCharacters

public boolean getValueContainsLiteralCharacters()

如果 stringToValue 应该返回掩码中的字面值，则返回 true。

返回：

如果掩码中的字面值应该在 stringToValue 中返回，则返回 True

stringToValue

public Object stringToValue(String value)
                     throws ParseException

解析文本，返回 String value 的适当 Object 表示形式。此方法将在必要时将字面值字符分开并调用超类 stringToValue，所以，如果已指定了值类 (setValueClass)，则将创建它的一个实例。如果该值与当前掩码不匹配，这将抛出一个 ParseException。有关如何处理字面值的详细信息，请参阅 setValueContainsLiteralCharacters(boolean)。

覆盖：

类 DefaultFormatter 中的 stringToValue

参数：

value - 要转换的字符串

返回：

文本的 Object 表示形式

抛出：

ParseException - 如果在转换时发生错误

另请参见：

setValueContainsLiteralCharacters(boolean)

valueToString

public String valueToString(Object value)
                     throws ParseException

返回基于掩码的 Object value 的 String 表示形式。有关如何处理字面值的详细信息，请参阅 setValueContainsLiteralCharacters(boolean)。

覆盖：

类 DefaultFormatter 中的 valueToString

参数：

value - 要转换的 Value

返回：

值的 String 表示形式

抛出：

ParseException - 如果在转换时发生错误

另请参见：

setValueContainsLiteralCharacters(boolean)

install

public void install(JFormattedTextField ftf)

将 DefaultFormatter 安装在特定的 JFormattedTextField 上。这将调用 valueToString，将 JFormattedTextField 中的当前值转换为 String。此方法稍后将会把 getActions 返回的 Action、getDocumentFilter 返回的 DocumentFilter 和 getNavigationFilter 返回的 NavigationFilter 安装到 JFormattedTextField 上。

如果子类希望在 JFormattedTextField 上安装其他侦听器，则通常只需要重写此方法。

如果在将当前值转换为 String 时存在 ParseException，则这会将文本设置为空 String，并将 JFormattedTextField 标记为正处在无效状态。

尽管这是一个公共方法，但通常仅供 JFormattedTextField 的子类使用。当值发生更改，或内部状态发生更改时，JFormattedTextField 将在适当的时候调用此方法。

覆盖：

类 DefaultFormatter 中的 install

参数：

ftf - 要格式化为的 JFormattedTextField，可以为 null，这指示从当前的 JFormattedTextField 卸载。