DropDownList

FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '性别', data: ['全部', '男', '女']
});

FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '城市',
	data: [['bj', '北京'], ['sh', '上海'], ['gz', '广州'], ['sz', '深圳']],
	value: 'sh'
});

FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '城市',
	fields: ['value', 'text', 'enabled'],
	data: [
		['bj', '北京'],                          // 省略第 3 项 → enabled=true
		['sh', '上海（暂不可选）', false],        // 第 3 项 enabled=false → 此项被禁用
		['gz', '广州'],
		['sz', '深圳']
	]
});

FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '兴趣',
	data: [['music', '音乐'], ['sport', '运动'], ['read', '阅读'], ['travel', '旅行']],
	multiSelect: true, multiSelectMode: 'tags'
});

FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '城市',
	data: ['北京', '上海', '广州'], editable: true, forceSelection: false
});

FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '城市',
	data: [['bj', '北京'], ['sh', '上海']],
	listeners: {
		change: function (event) {
			FineUI.alert('选中值：' + this.getValue() + '，文本：' + this.getText());
		}
	}
});

FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '老师', group: true,
	fields: ['value', 'text', 'group'],
	data: [
		['101', '张萍萍', '材料科学与工程系'],
		['102', '陈飞', '化学系'],
		['103', '董婷婷', '化学系'],
		['104', '康颖颖', '数学系'],
		['105', '彭博', '数学系'],
		['106', '唐超', '物理系']
	]
});

Extends

• FineUI.TriggerBox

Members

bodyEl :jQuery

Description:

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

Inherited From:

• FineUI.Field#bodyEl

Type:

• jQuery

el :jQuery

Description:

• 控件对应的jQuery节点对象

Inherited From:

• FineUI.Component#el

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:

blur()

Description:

• 取消焦点

Inherited From:

• FineUI.Field#blur

clearDirty()

Description:

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

Inherited From:

• FineUI.Field#clearDirty

Example

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

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

clearInvalid()

Description:

• 清空无效标记

Inherited From:

• FineUI.TriggerBox#clearInvalid

clearValue()

Description:

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

Inherited From:

• FineUI.Field#clearValue

Example

清空所有筛选字段：

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

disable()

Description:

• 禁用控件

Inherited From:

• FineUI.TextBox#disable

doLayout(startFormTopmostComonentopt)

Description:

• 执行布局操作

Inherited From:

• FineUI.Component#doLayout

Parameters:

enable()

Description:

• 启用控件

Inherited From:

• FineUI.TextBox#enable

focus(selectTextopt, delayMillisecondsopt)

Description:

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

Inherited From:

• FineUI.Field#focus

Example

校验失败后聚焦：

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

Parameters:

getAttr(key) → {string}

Description:

• 获取节点属性

Inherited From:

• FineUI.Component#getAttr

Parameters:

Returns:

Type

string

getEncodedText(text) → {string}

Description:

• 获取编码后的字符串

Inherited From:

• FineUI.Component#getEncodedText

Parameters:

Returns:

Type

string

getFieldLabel() → {string}

Description:

• 获取字段标签

Inherited From:

• FineUI.Field#getFieldLabel

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:

Returns:

Type

FineUI.Component

getText() → {string}

Description:

• 获取显示文本

Inherited From:

• FineUI.TextBox#getText

Returns:

Type

string

getTextByValue(value) → {string}

Description:

• 获取值对应的显示文本

Parameters:

Returns:

Type

string

getTooltip() → {string}

Description:

• 获取提示信息

Inherited From:

• FineUI.Component#getTooltip

Returns:

Type

string

getValue() → {string|Array.<string>}

Description:

• 获取下拉列表的值

Overrides:

• FineUI.TriggerBox#getValue

Returns:

Type

string | Array.<string>

getValueByText(text) → {string}

Description:

• 获取显示文本对应的值

Parameters:

Returns:

Type

string

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:

• 隐藏弹出框

Overrides:

• FineUI.TriggerBox#hidePopEl

hideTrigger()

Description:

• 隐藏触发按钮

Inherited From:

• FineUI.TriggerBox#hideTrigger

hideTrigger1()

Description:

• 隐藏第一个触发按钮

Inherited From:

• FineUI.TriggerBox#hideTrigger1

hideTrigger2()

Description:

• 隐藏第二个触发按钮

Inherited From:

• FineUI.TriggerBox#hideTrigger2

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:

isDirty() → {boolean}

Description:

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

Inherited From:

• FineUI.Field#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:

• 是否焦点元素

Inherited From:

• FineUI.Field#isFocused

Returns:

Type

boolean

isTriggerVisible(triggerNumber) → {boolean}

Description:

• 触发按钮是否可见

Inherited From:

• FineUI.TriggerBox#isTriggerVisible

Parameters:

Returns:

Type

boolean

isType(value) → {boolean}

Description:

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

Inherited From:

• FineUI.Base#isType

Example

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

Parameters:

Returns:

Type

boolean

isUserInput() → {boolean}

Description:

• 是否为用户自行输入值

Returns:

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:

Returns:

Type

Array.<Object>

isVisible() → {boolean}

Description:

• 是否可见

Inherited From:

• FineUI.Component#isVisible

Returns:

Type

boolean

loadData(data, valueopt)

Description:

• 加载数据（会替换下拉项；常用于级联下拉：在父下拉change事件中调用子下拉的loadData）

Examples

省市县级联：选择省份后刷新城市下拉项：

FineUI.create({
    type: 'DropDownList', id: 'ddlSheng',
    data: [['bj', '北京'], ['shanghai', '上海'], ['guangdong', '广东']],
    listeners: {
        change: function () {
            var province = this.getValue();
            var cityData = getCitiesByProvince(province);
            FineUI.ui.ddlCity.loadData(cityData, '-1');  // 第二个参数指定默认选中
        }
    }
});

仅替换下拉项，不预设选中：

FineUI.ui.ddlCategory.loadData([
    ['fruit', '水果'],
    ['vegetable', '蔬菜']
]);

Parameters:

markInvalid(errorMsg)

Description:

• 将字段标记为无效

Inherited From:

• FineUI.TriggerBox#markInvalid

Parameters:

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:

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:

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:

removeTooltip()

Description:

• 删除提示信息

Inherited From:

• FineUI.Component#removeTooltip

reset()

Description:

• 重置字段

Inherited From:

• FineUI.Field#reset

setAttr(key, value)

Description:

• 设置节点属性

Inherited From:

• FineUI.Component#setAttr

Parameters:

setAttrs(attrs)

Description:

• 设置节点属性

Inherited From:

• FineUI.Component#setAttrs

Parameters:

setDisabled(disabled)

Description:

• 设置控件的禁用状态

Inherited From:

• FineUI.Component#setDisabled

Parameters:

setEditable(editable)

Description:

• 设置是否可编辑

Inherited From:

• FineUI.TextBox#setEditable

Parameters:

setEmptyText(emptyText)

Description:

• 设置空白文本

Inherited From:

• FineUI.TextBox#setEmptyText

Parameters:

setEnabled(enabled)

Description:

• 设置控件的启用状态

Inherited From:

• FineUI.Component#setEnabled

Parameters:

setFieldLabel(label)

Description:

• 设置字段标签

Inherited From:

• FineUI.Field#setFieldLabel

Parameters:

setHeight(height)

Description:

• 设置控件高度

Inherited From:

• FineUI.Component#setHeight

Parameters:

setHidden(hidden)

Description:

• 设置控件的隐藏状态

Inherited From:

• FineUI.Component#setHidden

Parameters:

setMaxLength(maxLength)

Description:

• 设置最大长度

Inherited From:

• FineUI.TextBox#setMaxLength

Parameters:

setMinLength(minLength)

Description:

• 设置最小长度

Inherited From:

• FineUI.TextBox#setMinLength

Parameters:

setReadonly(readonly)

Description:

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

Inherited From:

• FineUI.Field#setReadonly

Example

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

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

Parameters:

setRedStar(redStar)

Description:

• 设置是否显示红色星号

Inherited From:

• FineUI.Field#setRedStar

Parameters:

setRegex(regex)

Description:

• 设置正则表达式

Inherited From:

• FineUI.TextBox#setRegex

Parameters:

setRegexPattern(regexPattern)

Description:

• 设置正则表达式规则

Inherited From:

• FineUI.TextBox#setRegexPattern

Parameters:

setRequired(required)

Description:

• 设置是否必填

Inherited From:

• FineUI.TextBox#setRequired

Parameters:

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:

setText(text, forceNoValidate)

Description:

• 设置显示文本

Inherited From:

• FineUI.TextBox#setText

Parameters:

setTooltip(tooltip)

Description:

• 设置提示信息

Inherited From:

• FineUI.Component#setTooltip

Parameters:

setTriggerVisible(triggerNumber, visible)

Description:

• 设置触发按钮的显示状态

Inherited From:

• FineUI.TriggerBox#setTriggerVisible

Parameters:

setValue(value, forceNoValidate)

Description:

• 设置下拉列表的值

Overrides:

• FineUI.TriggerBox#setValue

Parameters:

setVisible(visible)

Description:

• 设置控件的显示状态

Inherited From:

• FineUI.Component#setVisible

Parameters:

setWidth(width)

Description:

• 设置控件宽度

Inherited From:

• FineUI.Component#setWidth

Parameters:

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:

showPopEl()

Description:

• 显示弹出框

showTrigger()

Description:

• 显示触发按钮

Inherited From:

• FineUI.TriggerBox#showTrigger

showTrigger1()

Description:

• 显示第一个触发按钮

Inherited From:

• FineUI.TriggerBox#showTrigger1

showTrigger2()

Description:

• 显示第二个触发按钮

Inherited From:

• FineUI.TriggerBox#showTrigger2

toggleEnabled()

Description:

• 切换启用状态

Inherited From:

• FineUI.Component#toggleEnabled

toggleVisible()

Description:

• 切换显示状态

Inherited From:

• FineUI.Component#toggleVisible

trigger(eventName, args)

Description:

• 触发事件

Inherited From:

• FineUI.Component#trigger

Parameters:

triggerDefaultAction()

Description:

• 触发缺省动作

Inherited From:

• FineUI.TriggerBox#triggerDefaultAction

validate() → {boolean}

Description:

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

Inherited From:

• FineUI.Field#validate

Example

失焦时主动校验单字段：

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

Returns:

Type

boolean

Events

beforehide

Description:

• 隐藏控件之前触发（返回false则取消隐藏操作）

Inherited From:

• FineUI.Component#event:beforehide

beforeselect

Description:

• 选中列表项之前触发（返回false则取消选中操作）

Parameters:

beforeshow

Description:

• 显示控件之前触发（返回false则取消显示操作）

Inherited From:

• FineUI.Component#event:beforeshow

blur

Description:

• 输入框失去焦点时触发（常用于失焦校验或失焦联动）

Inherited From:

• FineUI.TextBox#event:blur

Example

失焦触发字段校验（仅校验当前字段，不影响整表）：

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

Parameters:

change

Description:

• 输入框值改变时触发（失焦或回车后；继承到所有 TextBox 派生类如NumberBox/DatePicker/DropDownList）

Inherited From:

• FineUI.TextBox#event:change

Example

响应值变化做联动：

FineUI.create({
    type: 'TextBox', fieldLabel: '关键字',
    listeners: {
        change: function () {
            FineUI.ui.grid1.loadDataUrl('/api/search', { q: this.getValue() });
        }
    }
});

Parameters:

cleariconclick

Description:

• 点击清空图标时触发

Parameters:

enter

Description:

• 输入框获取焦点并按下 ENTER 键时触发（常用于"搜索框回车提交"或"密码框回车登录"）

Inherited From:

• FineUI.TextBox#event:enter

Example

搜索框回车触发搜索（也可改用配置属性enterClickControl声明式实现）：

FineUI.create({
    type: 'TextBox', fieldLabel: '关键字',
    listeners: {
        enter: function () {
            FineUI.ui.btnSearch.click();
        }
    }
});

Parameters:

focus

Description:

• 输入框获取焦点时触发

Inherited From:

• FineUI.TextBox#event:focus

Parameters:

hide

Description:

• 隐藏控件时触发

Inherited From:

• FineUI.Component#event:hide

layout

Description:

• 布局控件时触发

Inherited From:

• FineUI.Component#event:layout

remove

Description:

• 移除控件时触发（调用 remove() 时，控件 DOM 被销毁之前触发；可用于清理外部资源 / 解绑全局事件）

Inherited From:

• FineUI.Component#event:remove

render

Description:

• 渲染控件时触发

Inherited From:

• FineUI.Component#event:render

select

Description:

• 选中列表项时触发

Parameters:

show

Description:

• 显示控件时触发

Inherited From:

• FineUI.Component#event:show

tagclose

Description:

• 关闭某个标签时触发（仅在启用多选标签模式时有效）

Parameters:

trigger1click

Description:

• 点击第一个触发图标时触发

Inherited From:

• FineUI.TriggerBox#event:trigger1click

Parameters:

trigger2click

Description:

• 点击第二个触发图标时触发

Inherited From:

• FineUI.TriggerBox#event:trigger2click

Parameters:

triggerclick

Description:

• 点击触发图标时触发

Inherited From:

• FineUI.TriggerBox#event:triggerclick

Parameters: