Java javax.swing.text 类 MaskFormatter（JDK5）

所有类

概述  软件包   类  使用  树  已过时  索引  帮助
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

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()

返回输入无效的字符。

返回：

非法字符。