Ext.form.TextField 是 Ext JS 表單中最基礎的輸入元件,支援驗證、遮罩、提示等豐富功能。以下整理最常用屬性與最小可用範例,方便開發快速查閱。
最小可用範例
Ext.onReady(function() {
Ext.QuickTips.init(); // 啟用提示功能
var textfieldName = new Ext.form.TextField({
renderTo: 'Bind_TextField', // 渲染目標容器 ID
fieldLabel: '使用者名稱',
name: 'username',
allowBlank: false, // 必填
blankText: '請輸入使用者名稱',
maxLength: 20,
maxLengthText: '長度不可超過 20 字元',
regex: /^[a-zA-Z0-9_]+$/, // 僅允許英數字底線
regexText: '僅限英數字與底線',
width: 300
});
});
核心屬性分類速查
1. 基本顯示與行為
| 屬性 | 型別 | 預設 | 說明 |
id | String | 自動產生 | 元件唯一識別碼,建議自行指定便於 Ext.getCmp() 取得。 |
fieldLabel | String | '' | 標籤文字,配合 FormLayout 顯示。 |
hideLabel | Boolean | false | true 時隱藏標籤但保留間距。 |
hidden | Boolean | false | true 時完全隱藏元件。 |
disabled | Boolean | false | true 時禁用輸入,表單提交時不包含此欄位。 |
readOnly | Boolean | false | true 時唯讀,但表單提交仍包含值。 |
inputType | String | 'text' | 'text'|'password'|'file'|'hidden' 等原生 type。 |
width/height | Number/String | 'auto' | 寬高,數值為像素,'auto' 自適應。 |
2. 空值與提示
| 屬性 | 型別 | 預設 | 說明 |
allowBlank | Boolean | true | false 表示必填,配合 blankText。 |
blankText | String | 'This field is required' | 空值錯誤提示。 |
emptyText | String | null | 輸入框為空時顯示的灰色提示文字(HTML5 placeholder 效果)。 |
validateOnBlur | Boolean | true | 失去焦點時驗證。 |
validationDelay | Number | 250 | 驗證延遲毫秒數(配合 keyup 事件)。 |
validationEvent | String/Boolean | 'keyup' | 觸發驗證事件:'keyup'、'blur'、false 關閉即時驗證。 |
3. 長度與格式驗證
| 屬性 | 型別 | 說明 |
minLength | Number | 最小長度,配合 minLengthText。 |
maxLength | Number | 最大長度,配合 maxLengthText;注意:原文重複定義 maxLengthText,應分別對應 min/max。 |
regex | RegExp | 正則驗證,不符合時顯示 regexText。 |
regexText | String | 正則失敗提示。 |
maskRe | RegExp | 輸入遮罩,僅允許符合字元輸入(如 /[0-9]/ 僅限數字)。 |
stripCharsRe | RegExp | 自動移除不符合字元(如 /[^0-9]/g 只保留數字)。 |
4. 進階自訂驗證
| 屬性 | 型別 | 說明 |
validator | Function | 自訂驗證函式,回傳 true 通過,回傳字串視為錯誤訊息。範例:
validator: function(v) { return v.length >= 6 ? true : '至少 6 字元'; } |
vtype | String | 內建驗證類型:'email'、'url'、'alpha'、'alphanum' 等;可自訂 Ext.apply(Ext.form.field.VTypes, {...})。 |
5. 狀態與渲染
| 屬性 | 型別 | 說明 |
value | Mixed | 初始值。 |
hideMode | String | 'display'|'offsets'|'visibility' 隱藏模式。 |
renderTo | String/HTMLElement | 指定渲染容器,或加入 Container/FormPanel 的 items 陣列。 |
常見坑點提醒
- 必須呼叫
Ext.QuickTips.init(),否則 blankText、regexText 等提示不會顯示。
maxLength 僅做前端驗證,資料庫仍需設定欄位長度約束。
regex 使用正則字面量 /pattern/,勿用字串 '/pattern/'。
- 表單提交時,
disabled:true 的欄位不會送出,readOnly:true 會送出。
延伸閱讀: Ext JS 6+ 現代工具包建議改用 Ext.field.Text(Modern toolkit),API 相似但支援觸控優化與雙向綁定(ViewModel)。