表单

Form Panel（表单面板） 只是一个基本 Panel（面板），添加了表单处理能力。Form Panel（表单面板）可以在 Ext application（应用程序） 的任何需要从用户收集数据的地方使用。

此外，Form Panel（表单面板）可以使用任何 Container Layout（容器布局），从而提供一种方便灵活的方式来处理其字段的定位。Form Panel（表单面板）也可以绑定到 Model（模型），从而轻松地从服务器加载数据并将数据提交回服务器。

在底层，Form Panel（表单面板）包装了一个 Basic Form（基本表单），它处理其所有输入字段管理、验证、提交和表单加载服务。这意味着 Basic Form（基本表单）的许多配置选项可以直接在 Form Panel（表单面板）上使用。

基本表单面板

首先，以下是如何创建一个简单的表单来收集用户数据

Ext.create('Ext.form.Panel', {
    renderTo: document.body,
    title: 'User Form',
    height: 350,
    width: 300,
    bodyPadding: 10,
    defaultType: 'textfield',
    items: [
        {
            fieldLabel: 'First Name',
            name: 'firstName'
        },
        {
            fieldLabel: 'Last Name',
            name: 'lastName'
        },
        {
            xtype: 'datefield',
            fieldLabel: 'Date of Birth',
            name: 'birthDate'
        }
    ]
});

此表单将其自身渲染到文档正文，并具有三个 Field（字段） - “First Name”（名字）、“Last Name”（姓氏）和 “Date of Birth”（出生日期）。字段使用 items（项目） 配置添加到 Form Panel（表单面板）。

fieldLabel（字段标签） 配置定义了将显示在字段旁边标签中的文本，并且 name（名称） 配置成为底层 HTML 字段的 name 属性。

请注意，此 Form Panel（表单面板）的 defaultType（默认类型） 为 'textfield'（文本字段）。这意味着其任何没有指定 xtype（xtype） 的项目（本示例中的“First Name”（名字）和 “Last Name”（姓氏）字段）都是 Text Field（文本字段）。

另一方面，“Date of Birth”（出生日期）字段将其 xtype 显式配置为 'datefield'（日期字段），这使其成为 Date Field（日期字段）。Date Field（日期字段）期望仅包含有效的日期数据，并附带一个 DatePicker（日期选择器） 用于选择日期。

字段

字段类型

Ext JS 开箱即用地提供了一组标准字段类型。Ext.form.field 命名空间中的任何字段都可以在 Form Panel（表单面板）中使用。有关更多信息，请参阅每个字段类型的 API 文档

• Ext.form.field.Checkbox（复选框）
• Ext.form.field.ComboBox（组合框）
• Ext.form.field.Date（日期）
• Ext.form.field.Display（显示）
• Ext.form.field.File（文件）
• Ext.form.field.Hidden（隐藏）
• Ext.form.field.HtmlEditor（HTML 编辑器）
• Ext.form.field.Number（数字）
• Ext.form.field.Radio（单选按钮）
• Ext.form.field.Text（文本）
• Ext.form.field.TextArea（文本区域）
• Ext.form.field.Time（时间）

验证

1. 内置验证

Ext JS 内置了对任何类型的字段的验证支持，并且某些字段具有内置的验证规则。

例如，如果在 Date Field（日期字段） 中输入一个值，并且该值无法转换为 Date，则该字段的 HTML 元素将添加 x-form-invalid-field CSS 类。

如有必要，可以使用 invalidCls（无效类） 配置更改此 CSS 类。添加 invalidCls 会向输入字段添加红色边框（以及在使用 Classic 主题时添加红色“无效下划线”装饰）

包含无效数据的字段还将显示错误消息。默认情况下，此消息显示为工具提示

使用 msgTarget（消息目标） 配置可以轻松更改字段错误消息的位置，而 invalidText（无效文本） 配置会更改错误消息。

每个字段都提供了自己的 invalidText 实现，并且许多字段都支持错误消息中的令牌替换。

例如，在 Date Field（日期字段）的 invalidText 中，任何出现的“{0}”都将被字段的值替换，任何出现的“{1}”都将被必需的日期 format（格式） 替换。

以下代码演示了将错误消息直接放置在字段下方，并自定义错误消息文本

{
    xtype: 'datefield',
    fieldLabel: 'Date of Birth',
    name: 'birthDate',
    msgTarget: 'under', // location of the error message
    invalidText: '"{0}" bad. "{1}" good.' // custom error message text
}

2. 自定义验证

某些验证要求无法使用内置验证来满足。实现自定义验证的最简单方法是使用 Text Field（文本字段） 的 regex（正则表达式） 配置来应用验证规则，并使用 maskRe（掩码正则表达式） 配置来限制可以键入到字段中的字符。以下是一个验证时间的 Text Field（文本字段）示例。

{
    xtype: 'textfield',
    fieldLabel: 'Last Login Time',
    name: 'loginTime',
    regex: /^([1-9]|1[0-9]):([0-5][0-9])(\s[a|p]m)$/i,
    maskRe: /[\d\s:amp]/i,
    invalidText: 'Not a valid time.  Must be in the format "12:34 PM".'
}

虽然上述方法非常适合验证单个字段，但对于具有许多共享相同自定义验证的字段的应用程序来说，它并不实用。

Ext.form.field.VTypes（VTypes） 类提供了一种创建可重用自定义验证的解决方案。以下是如何创建自定义“time”（时间）验证器

// custom Vtype for vtype:'time'
var timeTest = /^([1-9]|1[0-9]):([0-5][0-9])(\s[a|p]m)$/i;
Ext.apply(Ext.form.field.VTypes, {
    //  vtype validation function
    time: function(val, field) {
        return timeTest.test(val);
    },
    // vtype Text property: The error text to display when the validation function returns false
    timeText: 'Not a valid time.  Must be in the format "12:34 PM".',
    // vtype Mask property: The keystroke filter mask
    timeMask: /[\d\s:amp]/i
});

一旦创建了自定义验证器，就可以在整个应用程序的 Text Field（文本字段）中使用 vtype（验证类型） 配置。

{
    fieldLabel: 'Last Login Time',
    name: 'loginTime',
    vtype: 'time'
}

有关工作演示，请参阅 Validation Example（验证示例）。有关自定义验证的更多信息，请参阅 VTypes（VTypes） 的 API 文档。

处理数据

提交表单

将数据提交到服务器的最简单方法是使用 Basic Form（基本表单） 的 url（URL） 配置。由于 Form Panel（表单面板） 包装了一个 Basic Form（基本表单），因此我们可以直接在 Form Panel（表单面板）上使用 Basic Form（基本表单）的任何配置选项

Ext.create('Ext.form.Panel', {
    ...
    url: 'add_user',
    items: [
        ...
    ]
});

表单的 submit（提交） 方法可用于将数据提交到配置的 url

Ext.create('Ext.form.Panel', {
    ...
    url: 'add_user',
    items: [
        ...
    ],
    buttons: [
        {
            text: 'Submit',
            handler: function() {
                var form = this.up('form'); // get the form panel
                if (form.isValid()) { // make sure the form contains valid data before submitting
                    form.submit({
                        success: function(form, action) {
                           Ext.Msg.alert('Success', action.result.msg);
                        },
                        failure: function(form, action) {
                            Ext.Msg.alert('Failed', action.result.msg);
                        }
                    });
                } else { // display error alert if the data is invalid
                    Ext.Msg.alert('Invalid Data', 'Please correct form errors.')
                }
            }
        }
    ]
});

在上面的示例中，按钮配置了一个 handler（处理程序），用于处理表单提交。处理程序执行以下操作

1. 首先，必须获取对 Form Panel（表单面板）的引用。
2. 然后在提交之前调用 isValid（isValid） 方法，以验证所有字段都没有验证错误。
3. 最后，调用 submit 方法，并传递两个回调函数 - success（成功） 和 failure（失败）。在这些回调函数中，action.result 指的是解析后的 JSON 响应。

上面的示例期望一个如下所示的 JSON 响应

{ "success": true, "msg": "User added successfully" }

将表单绑定到模型

Model（模型） 类在整个 Ext JS 中用于表示各种类型的数据以及检索和更新服务器上的数据。表示 User（用户） 的 Model（模型）将定义 User（用户） 拥有的 fields（字段） 以及用于加载和保存数据的 proxy（代理）

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',
    fields: ['firstName', 'lastName', 'birthDate'],
    proxy: {
        type: 'ajax',
        api: {
            read: 'data/get_user',
            update: 'data/update_user'
        },
        reader: {
            type: 'json',
            root: 'users'
        }
    }
});

可以使用 loadRecord（loadRecord） 方法直接从 Model（模型） 将数据加载到 Form Panel（表单面板） 中

MyApp.model.User.load(1, { // load user with ID of "1"
    success: function(user) {
        userForm.loadRecord(user); // when user is loaded successfully, load the data into the form
    }
});

最后，不是使用 submit（提交） 方法来保存数据，而是使用 Form Panel（表单面板）的 updateRecord（updateRecord） 方法来使用表单数据更新记录，并调用 Model（模型）的 save（保存） 方法将数据保存到服务器

Ext.create('Ext.form.Panel', {
    ...
    url: 'add_user',
    items: [
        ...
    ],
    buttons: [
        {
            text: 'Submit',
            handler: function() {
                var form = this.up('form'), // get the form panel
                    record = form.getRecord(); // get the underlying model instance
                if (form.isValid()) { // make sure the form contains valid data before submitting
                    form.updateRecord(record); // update the record with the form data
                    record.save({ // save the record to the server
                        success: function(user) {
                            Ext.Msg.alert('Success', 'User saved successfully.')
                        },
                        failure: function(user) {
                            Ext.Msg.alert('Failure', 'Failed to save user.')
                        }
                    });
                } else { // display error alert if the data is invalid
                    Ext.Msg.alert('Invalid Data', 'Please correct form errors.')
                }
            }
        }
    ]
});

模型绑定示例

布局

布局用于处理 Ext JS 应用程序中组件的大小调整和定位。Form Panel（表单面板） 可以使用任何 Container Layout（容器布局）。有关布局的更多信息，请参阅 布局和容器指南。

例如，使用 HBox 布局可以轻松地水平定位表单中的字段

Ext.create('Ext.form.Panel', {
    renderTo: document.body,
    title: 'User Form',
    height: 300,
    width: 585,
    defaults: {
        xtype: 'textfield',
        labelAlign: 'top',
        padding: 10
    },
    layout: 'hbox',
    items: [
        {
            fieldLabel: 'First Name',
            name: 'firstName'
        },
        {
            fieldLabel: 'Last Name',
            name: 'lastName'
        },
        {
            xtype: 'datefield',
            fieldLabel: 'Date of Birth',
            name: 'birthDate'
        }
    ]
});