Field - FineUI.js

Field

FineUI. Field

表单字段基类（所有可放入 Form 的字段控件的共同父类）。

抽象基类，不能直接实例化（~~FineUI.create({ type: 'Field' })~~）。此类提供字段共有能力：fieldLabel 标签、value 读写、必填/正则验证、只读、name 属性、字段比较等。

直接子类：

FineUI.TextBox —— 文本输入框（进一步派生：）
- FineUI.TextArea —— 多行文本
- FineUI.FileUpload —— 文件上传
- FineUI.TriggerBox —— 触发器输入框（进一步派生 FineUI.DatePicker / FineUI.DropDownList / FineUI.NumberBox / FineUI.DropDownBox / FineUI.TimePicker）
FineUI.CheckBox —— 复选框（进一步派生 FineUI.RadioButton）
FineUI.CheckBoxList —— 复选框列表（进一步派生 FineUI.RadioButtonList）
FineUI.Label —— 标签
FineUI.Hidden —— 隐藏字段
FineUI.HtmlEditor —— 富文本编辑器

Constructor

(abstract) new Field(options)

Parameters:

Name Type Description

options

Object

初始参数

Properties

Name	Type	Default	Description
`hideEmptyLabel`	boolean	`true`	是否隐藏空白标签
`fieldLabel`	string	`''`	字段标签
`hideLabel`	string	`false`	是否隐藏字段标签
`readonly`	boolean	`false`	是否只读（不可以响应触发按钮，注意和 editable 的区别）
`msgTarget`	string	`'side'`	无效字段提示消息的位置（可选项为：side, qtip, title, none）
`labelWidth`	number	`100`	字段标签的宽度
`labelSeparator`	string	`'：'`	字段标签的分隔符
`redStar`	boolean	`false`	是否在标签上显示红色的星号，用来标识必填项
`redStarPosition`	string	`'afterText'`	红色星号的显示位置（可选项为：afterText, beforeText, afterSeparator）
`labelAlign`	string	`'left'`	字段标签的显示位置（可选项为：left, top, right）
`enablePrefix`	boolean	`false`	是否启用字段前缀
`prefix`	string	`''`	字段前缀的内容
`enableSuffix`	boolean	`false`	是否启用字段后缀
`suffix`	string	`''`	字段后缀的内容
`compareControl`	string	`''`	需要比较的控件标识符（对值进行验证）
`compareValue`	string		需要比较的值（对值进行验证）
`compareOperator`	string	`'=='`	比较操作符（可选项为：==, >, >=, <, <=, !=）
`compareType`	string	`'string'`	比较的类型（可选项为：string, int, float）
`compareMessage`	string	`''`	不满足比较条件时提示信息
`validateTrim`	boolean	`true`	验证时去除文本的前后空白字符
`tabIndex`	number	`0`	TAB键导航的顺序
`name`	string	`''`	表单字段的名称（name属性用于对提交到服务器的表单数据进行标识，留空则使用id属性）
`type`	string	`'Field'`	控件类型

Extends

FineUI.Container

Members

bodyEl :jQuery

Description:

字段主体对应的jQuery节点对象

字段主体对应的jQuery节点对象

Type:

jQuery

el :jQuery

Description:

控件对应的jQuery节点对象

Inherited From:

FineUI.Component#el

控件对应的jQuery节点对象

Type:

jQuery

items :Object

Description:

子控件列表

Inherited From:

FineUI.Container#items

子控件列表

Type:

Object

Methods

add(value)

Description:

添加新的子控件到当前控件（追加到子项末尾）

Inherited From:

FineUI.Container#add

Examples

向菜单末尾追加一个分隔符和一个新菜单项（'-' 是 MenuSeparator 的快捷字符串形式）：

// 假设 menu1 当前 items 为：[菜单1, 菜单2]
FineUI.ui.menu1.add([
    '-',
    { type: 'MenuItem', text: '新菜单项', iconFont: 'plus' }
]);
// 追加后 items 顺序：[菜单1, 菜单2, ----, 新菜单项]

动态在工具栏末尾追加一个按钮：

FineUI.ui.toolbar1.add({
    type: 'Button', text: '导出', iconFont: 'download',
    handler: function () {
        FineUI.alert('导出');
    }
});

Parameters:

Name	Type	Description
`value`	Object \| Array.<Object>	控件实例（或控件实例数组，一次添加多个，按数组顺序追加）

blur()

Description:

取消焦点

clearDirty()

Description:

清空已改变状态（接受当前值为新的初始值；提交服务端成功后调用，isDirty随后返回 false）

Overrides:

FineUI.Container#clearDirty

Example

保存成功后清除单字段脏标记（更常用form.clearDirty()一次性清整表）：

$.ajax({
    url: '/api/save', method: 'POST', dataType: 'json',
    success: function () {
        FineUI.ui.tbxName.clearDirty();
    }
});

clearInvalid()

Description:

清空无效标记

clearValue()

Description:

清空值（重置为空字符串/null；常用于"重置某字段"或"清空搜索条件"按钮，但不会改变字段的"初始值"——reset会恢复到初始值）

Example

清空所有筛选字段：

['tbxKeyword', 'datepickerFrom', 'datepickerTo'].forEach(function (id) {
    FineUI.ui[id].clearValue();
});

disable()

Description:

禁用控件

Overrides:

FineUI.Container#disable

doLayout(startFormTopmostComonentopt)

Description:

执行布局操作

Inherited From:

FineUI.Component#doLayout

Parameters:

Name	Type	Attributes	Default	Description
`startFormTopmostComonent`	boolean	<optional>	`false`	从最顶层的控件开始布局

enable()

Description:

启用控件（与disable对应）

Inherited From:

FineUI.Component#enable

focus(selectTextopt, delayMillisecondsopt)

Description:

设置焦点（典型场景：服务端校验出错回显时聚焦到第一个错误字段）

Example

校验失败后聚焦：

if (FineUI.ui.tbxUserName.getValue() === 'admin') {
    FineUI.ui.tbxUserName.markInvalid('admin 是保留字');
    FineUI.ui.tbxUserName.focus(true, 200);  // 选中文本，延迟 200ms 等动画
}

Parameters:

Name	Type	Attributes	Default	Description
`selectText`	boolean	<optional>	`false`	是否同时选中文本（适用于`TextBox`系列）
`delayMilliseconds`	number	<optional>	`0`	设置焦点前延迟的毫秒数（用于动画完成后再聚焦）

getAttr(key) → {string}

Description:

获取节点属性

Inherited From:

FineUI.Component#getAttr

Parameters:

Name	Type	Description
`key`	string	节点属性键

Returns:

节点属性值

Type: string

getEncodedText(text) → {string}

Description:

获取编码后的字符串

Inherited From:

FineUI.Component#getEncodedText

Parameters:

Name	Type	Description
`text`	string	原始字符串

Returns:

编码后的字符串

Type: string

getFieldLabel() → {string}

Description:

获取字段标签

Returns:

字段标签

Type: string

getFormFields() → {Array.<FineUI.Field>}

Description:

获取容器内（深度遍历）所有表单字段实例（FineUI.Field的子类，如TextBox/NumberBox/DatePicker等）

Inherited From:

FineUI.Container#getFormFields

Example

遍历表单全部字段，序列化为 name → value 的对象（用于自定义 ajax 提交；字段未声明name时改用id）：

var values = {};
FineUI.ui.form1.getFormFields().forEach(function (field) {
    values[field.name || field.id] = field.getValue();
});
// values 形如：{ tbxUserName: 'FineUIPro', numberAge: 30, ... }

Returns:

表单字段数组

Type: Array.<FineUI.Field>

getHeight() → {number}

Description:

获取控件高度

Inherited From:

FineUI.Component#getHeight

Returns:

高度

Type: number

getItem(value) → {FineUI.Component}

Description:

获取子控件（按索引/标识符/匹配函数查找；通常配合items无显式 id 的场景，比按FineUI.ui[id]更精准）

Inherited From:

FineUI.Container#getItem

Examples

按索引取第一个子控件：

var firstChild = FineUI.ui.toolbar1.getItem(0);

按 id 取子控件：

var btn = FineUI.ui.toolbar1.getItem('btnSave');

按匹配函数找第一个匹配的子控件（函数对每项返回 true 即匹配）：

var btn = FineUI.ui.toolbar1.getItem(function (item) {
    return item.type === 'Button' && item.text === '保存';
});

Parameters:

Name	Type	Description
`value`	number \| string \| function	子控件索引、标识符或者匹配函数

Returns:

子控件实例

Type: FineUI.Component

getText() → {string}

Description:

获取显示文本（区别于getValue：value 是用于提交的原始数据，text 是给用户看的展示文本；DropDownList下二者通常不同：value 是 key，text 是显示名）

Examples

下拉框场景：value 与 text 不同：

FineUI.create({
    type: 'DropDownList', id: 'ddlCity',
    data: [['bj', '北京'], ['sh', '上海']],
    value: 'bj'
});
FineUI.ui.ddlCity.getValue();  // 'bj'
FineUI.ui.ddlCity.getText();   // '北京'

DatePicker 场景：getValue 返回 Date 对象，getText 返回按 format 格式化的字符串：

FineUI.ui.dp1.getValue();  // Sat May 22 2026 ...
FineUI.ui.dp1.getText();   // '2026-05-22'

Returns:

显示文本

Type: string

getTooltip() → {string}

Description:

获取提示信息

Inherited From:

FineUI.Component#getTooltip

Returns:

提示信息

Type: string

getValue() → {Object}

Description:

获取值（不同字段返回类型不同：TextBox返回字符串、NumberBox返回数字、DatePicker返回 Date、CheckBox返回布尔值、CheckBoxList返回字符串数组）

Example

读取常见字段的值：

var name = FineUI.ui.tbxName.getValue();       // 字符串
var age = FineUI.ui.numberAge.getValue();      // 数字
var birthday = FineUI.ui.datepicker1.getValue(); // Date 对象
var checked = FineUI.ui.checkbox1.getValue();  // 布尔值
var picks = FineUI.ui.checkboxlist1.getValue(); // 字符串数组 ['v1', 'v2']

Returns:

值

Type: Object

getWidth() → {number}

Description:

获取控件宽度

Inherited From:

FineUI.Component#getWidth

Returns:

宽度

Type: number

hide()

Description:

隐藏控件（默认通过 CSS display:none 隐藏；可通过hiddenMode选择 visibility/offsets 模式以保留布局空间）

Inherited From:

FineUI.Component#hide

Example

根据权限隐藏按钮：

if (!currentUser.canEdit) {
    FineUI.ui.btnEdit.hide();
}

hideLoading()

Description:

隐藏加载动画

Inherited From:

FineUI.Container#hideLoading

hidePopEl()

Description:

隐藏容器内的所有弹出框

Inherited From:

FineUI.Container#hidePopEl

insert(insertIndex, value)

Description:

插入新的子控件到当前控件

Inherited From:

FineUI.Container#insert

Examples

向菜单的开头插入一个新菜单项和一个分隔符（'-' 是 MenuSeparator 的快捷字符串形式）：

// 假设 menu1 当前 items 为：[菜单1, 菜单2, 菜单3]
FineUI.ui.menu1.insert(0, [
    { type: 'MenuItem', text: '新增', iconFont: 'plus' },
    '-'
]);
// 插入后 items 顺序：[新增, ----, 菜单1, 菜单2, 菜单3]

在工具栏第 2 项位置插入一个分隔符和一个新按钮（Toolbar 中的'-' 是 ToolbarSeparator 的快捷字符串形式）：

FineUI.ui.toolbar1.insert(2, [
    '-',
    { type: 'Button', text: '新增', iconFont: 'plus' }
]);

Parameters:

Name	Type	Description
`insertIndex`	number	插入的位置（从 0 开始；如果 ≥ 当前子项数量，则追加到末尾）
`value`	Object \| Array.<Object>	控件实例（或控件实例数组，一次插入多个，按数组顺序）

isDirty() → {boolean}

Description:

字段值是否已经改变（与初始值/上次clearDirty时的值比较）

Overrides:

FineUI.Container#isDirty

Example

关闭页面前提示未保存：

window.addEventListener('beforeunload', function (event) {
    if (FineUI.ui.tbxName.isDirty()) {
        event.preventDefault();
        event.returnValue = '';
    }
});

Returns:

字段值是否已经改变

Type: boolean

isDisabled() → {boolean}

Description:

是否禁用

Inherited From:

FineUI.Component#isDisabled

Returns:

是否禁用

Type: boolean

isFocused() → {boolean}

Description:

是否焦点元素

Returns:

是否焦点元素

Type: boolean

isType(value) → {boolean}

Description:

检测当前实例是否指定的控件类型

Inherited From:

FineUI.Base#isType

Example

grid1.isType('panel') // 返回true
grid1.isType('grid')  // 返回true

Parameters:

Name	Type	Description
`value`	Object	控件类型

Returns:

如果当前实例是指定的控件类型，返回true；否则返回false

Type: boolean

isValid(onlyFirstInvalidFieldopt) → {Array.<Object>}

Description:

容器内的表单字段是否有效（会同时触发各字段的校验提示显示；常配合Button的validateForm属性自动调用）

Inherited From:

FineUI.Container#isValid

Examples

提交按钮显式校验（不依赖validateForm属性）：

FineUI.create({
    type: 'Button', text: '提交',
    handler: function () {
        var result = FineUI.ui.form1.isValid();
        if (result[0]) {
            // 校验通过 → 提交逻辑
        } else {
            // result[1] 是第一个无效字段，可聚焦提示
            result[1].focus();
        }
    }
});

仅检查"是否有效"（推荐的更常用方式：让 Button 的validateForm自动校验，handler 仅在通过时执行）：

FineUI.create({
    type: 'Button', text: '提交', validateForm: 'form1',
    handler: function () {
        // 走到这里说明 form1 已校验通过
    }
});

Parameters:

Name	Type	Attributes	Default	Description
`onlyFirstInvalidField`	boolean	<optional>	`false`	是否仅返回第一个无效的字段

Returns:

校验结果数组：第一项是布尔值（是否全部有效），其后是无效字段实例（[isValid, firstInvalidField, secondInvalidField, ...]）

Type: Array.<Object>

isVisible() → {boolean}

Description:

是否可见

Inherited From:

FineUI.Component#isVisible

Returns:

是否可见

Type: boolean

markInvalid(errorMsg)

Description:

将字段标记为无效（不会自动清除，需配合clearInvalid或setValue后由内置校验重新判定；常用于服务端校验回显，例如"用户名已被占用"这种客户端无法判定的错误）

Example

提交时根据服务端响应回显错误（用 jQuery 的 $.ajax）：

$.ajax({
    url: '/api/register', method: 'POST', dataType: 'json',
    data: { username: FineUI.ui.tbxUserName.getValue() },
    success: function (resp) {
        if (resp.code === 'USERNAME_TAKEN') {
            FineUI.ui.tbxUserName.markInvalid('用户名已被占用');
            FineUI.ui.tbxUserName.focus();
        }
    }
});

Parameters:

Name	Type	Description
`errorMsg`	string	错误提示消息（显示位置由字段的`msgTarget`决定：side/qtip/title/none）

off(eventNames, fnopt)

Description:

移除事件

Inherited From:

FineUI.Component#off

Examples

移除特定回调：

function onMyClick() { ... }
FineUI.ui.btn1.on('click', onMyClick);
// 后续解绑：
FineUI.ui.btn1.off('click', onMyClick);

移除某事件下的全部回调（不传 fn 参数）：

FineUI.ui.btn1.off('click');

Parameters:

Name	Type	Attributes	Description
`eventNames`	string		事件名称（可以空格分割多个事件名称）
`fn`	F_Component_on	<optional>	之前注册的事件处理函数（留空则移除该事件的所有回调）

on(eventNames, fn)

Description:

注册事件（运行时绑定；与配置参数listeners的初始绑定等价，但可在控件创建后动态追加）

Inherited From:

FineUI.Component#on

Examples

初始绑定形态：在FineUI.create时通过listeners配置项一次性声明：

FineUI.create({
    type: 'Button', renderTo: document.body, text: '按钮',
    listeners: {
        click: function (event) {
            FineUI.alert('button clicked');
        },
        // 同一个 listeners 内可以同时声明多个事件
        beforeclick: function (event) {
            // 返回 false 可阻止 click 事件
        }
    }
});

运行时绑定形态：控件创建后通过on()追加，效果与上面的listeners等价：

FineUI.ui.btn1.on('click', function (event) {
    FineUI.alert('button clicked');
});

on()一次绑定多个事件（事件名之间空格分隔）：

FineUI.ui.tbxName.on('focus blur', function () {
    console.log('focus 或 blur 触发');
});

Parameters:

Name	Type	Description
`eventNames`	string	事件名称（可以空格分割多个事件名称）
`fn`	F_Component_on	触发事件时执行的函数

remove()

Description:

从父控件中移除当前控件并销毁其 DOM（不可恢复；移除后 FineUI.ui[id] 也会清除）。触发 remove 事件可用于清理外部资源。

Inherited From:

FineUI.Component#remove

Example

动态添加 + 移除子控件：

var btn = FineUI.create({
    type: 'Button', text: '临时按钮', renderTo: document.body
});
// 5 秒后移除
setTimeout(function () {
    btn.remove();
}, 5000);

removeAttr(key)

Description:

删除节点属性

Inherited From:

FineUI.Component#removeAttr

Parameters:

Name	Type	Description
`key`	string	节点属性键

removeTooltip()

Description:

删除提示信息

Inherited From:

FineUI.Component#removeTooltip

reset()

Description:

重置字段

Overrides:

FineUI.Container#reset

setAttr(key, value)

Description:

设置节点属性

Inherited From:

FineUI.Component#setAttr

Parameters:

Name	Type	Description
`key`	string	节点属性键
`value`	string	节点属性值

setAttrs(attrs)

Description:

设置节点属性

Inherited From:

FineUI.Component#setAttrs

Parameters:

Name	Type	Description
`attrs`	Object	节点属性对象

setDisabled(disabled)

Description:

设置控件的禁用状态

Inherited From:

FineUI.Component#setDisabled

Parameters:

Name	Type	Description
`disabled`	boolean	是否禁用

setEnabled(enabled)

Description:

设置控件的启用状态

Inherited From:

FineUI.Component#setEnabled

Parameters:

Name	Type	Description
`enabled`	boolean	是否启用

setFieldLabel(label)

Description:

设置字段标签

Parameters:

Name	Type	Description
`label`	string	字段标签

setHeight(height)

Description:

设置控件高度

Inherited From:

FineUI.Component#setHeight

Parameters:

Name	Type	Description
`height`	number	高度

setHidden(hidden)

Description:

设置控件的隐藏状态

Inherited From:

FineUI.Component#setHidden

Parameters:

Name	Type	Description
`hidden`	boolean	是否隐藏

setReadonly(readonly)

Description:

设置只读（只读字段仍能聚焦/复制文本，但不能修改；与disable区别：只读字段仍参与表单提交）

Example

根据下拉框选择切换某字段是否只读：

FineUI.ui.ddlMode.on('change', function () {
    FineUI.ui.tbxAmount.setReadonly(this.getValue() === 'auto');
});

Parameters:

Name	Type	Description
`readonly`	boolean	只读状态

setRedStar(redStar)

Description:

设置是否显示红色星号

Parameters:

Name	Type	Description
`redStar`	boolean	是否显示红色星号

setSize(width, height)

Description:

设置控件尺寸（同时设置宽高；等价于setWidth + setHeight但只触发一次布局）

Inherited From:

FineUI.Component#setSize

Example

响应窗口 resize 调整面板尺寸：

$(window).on('resize', function () {
    FineUI.ui.panel1.setSize($(window).width() - 20, $(window).height() - 40);
});

Parameters:

Name	Type	Description
`width`	number	宽度
`height`	number	高度

setTooltip(tooltip)

Description:

设置提示信息

Inherited From:

FineUI.Component#setTooltip

Parameters:

Name	Type	Description
`tooltip`	string	提示信息

setValue(value, forceNoValidateopt)

Description:

设置值（不同字段接受的类型与getValue对应；DatePicker额外接受 yyyy-MM-dd 字符串；setValue默认会触发字段校验）

Example

批量回填编辑表单（用 jQuery 的 $.ajax 从服务端拉到行数据后逐字段赋值）：

$.ajax({
    url: '/api/student/101', dataType: 'json',
    success: function (row) {
        FineUI.ui.tbxName.setValue(row.name);
        FineUI.ui.datepicker1.setValue(row.birthday);  // '2000-01-01' 字符串也可
        FineUI.ui.checkboxlist1.setValue(row.tags);    // ['music', 'sport']
    }
});

Parameters:

Name	Type	Attributes	Default	Description
`value`	Object			值
`forceNoValidate`	boolean	<optional>	`false`	传`true`则跳过校验（适用于批量赋值后再统一校验的场景）

setVisible(visible)

Description:

设置控件的显示状态

Inherited From:

FineUI.Component#setVisible

Parameters:

Name	Type	Description
`visible`	boolean	是否可见

setWidth(width)

Description:

设置控件宽度

Inherited From:

FineUI.Component#setWidth

Parameters:

Name	Type	Description
`width`	number	宽度

show()

Description:

显示控件（与hide对应）

Inherited From:

FineUI.Component#show

Example

根据下拉列表的选中项，联动显示某区块：

FineUI.ui.ddlType.on('change', function () {
    if (this.getValue() === 'advanced') {
        FineUI.ui.pnlAdvanced.show();
    } else {
        FineUI.ui.pnlAdvanced.hide();
    }
});

showLoading(opacity, container)

Description:

显示加载动画

Inherited From:

FineUI.Container#showLoading

Parameters:

Name	Type	Description
`opacity`	number	透明度（默认值：0.65）
`container`	jQuery	显示动画的目标元素（留空则为内容元素）

toggleEnabled()

Description:

切换启用状态

Inherited From:

FineUI.Component#toggleEnabled

toggleVisible()

Description:

切换显示状态

Inherited From:

FineUI.Component#toggleVisible

trigger(eventName, args)

Description:

触发事件

Inherited From:

FineUI.Component#trigger

Parameters:

Name	Type	Description
`eventName`	string	事件名称
`args`	Object	事件参数

validate() → {boolean}

Description:

验证字段的有效性（会触发字段的校验提示显示；适用于针对单个字段做主动校验，例如失焦/外部触发；批量校验请用FineUI.ui.form1.isValid()）

Example

失焦时主动校验单字段：

FineUI.create({
    type: 'TextBox', fieldLabel: '邮箱', regex: /^[\w.]+@[\w.]+$/, regexMessage: '邮箱格式不正确',
    listeners: {
        blur: function () {
            this.validate();
        }
    }
});