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