MaskFormatter

目录搜索

文字

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

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"。使用右箭头键通过字段导航将生成（| 指示插入符的位置）：

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

编辑时会导致类似行为。假定在前一示例中将字符串 '123-45' 和 '12345' 插入 MaskFormatter。两项插入都将导致相同的字符串 '123-45__'。MaskFormatter 在字符位置 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`

构造方法详细信息

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 卸载。

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

javax.swing.text 类 MaskFormatter

MaskFormatter

MaskFormatter

setMask

getMask

setValidCharacters

getValidCharacters

setInvalidCharacters

getInvalidCharacters

setPlaceholder

getPlaceholder

setPlaceholderCharacter

getPlaceholderCharacter

setValueContainsLiteralCharacters

getValueContainsLiteralCharacters

stringToValue

valueToString

install

javax.swing.text
类 MaskFormatter