DropDownBox

FineUI. DropDownBox

Description:

  • 下拉框控件

Examples

使用popPanel挂载自定义弹出面板（例如挂一棵树）。树节点的 id 字段作为下拉框的值，text 字段作为显示文本：

FineUI.create({
	type: 'Tree', id: 'tree1', hidden: true, width: 300, height: 250, header: false,
	rootNode: {
		expanded: true,
		children: [{
			text: '中国', id: 'china', expanded: true, 
			children: [
				{ text: '河南省', id: 'henan', leaf: true },
				{ text: '安徽省', id: 'anhui', leaf: true },
				{ text: '广东省', id: 'guangdong', leaf: true }
			]
		}]
	}
});

FineUI.create({
	type: 'DropDownBox', renderTo: document.body, fieldLabel: '所属节点',
	popPanel: 'tree1', value: 'henan'   // value 对应树节点的 id
});

获取用户在树中选中的节点：getValue()返回选中节点的 id，getText()返回显示文本（要拿完整节点数据，用 FineUI.ui.tree1.getNodeData(id)）：

FineUI.create({
	type: 'Tree', id: 'tree1', hidden: true, width: 300, height: 250, header: false,
	rootNode: {
		expanded: true,
		children: [
			{ text: '河南省', id: 'henan', leaf: true },
			{ text: '安徽省', id: 'anhui', leaf: true }
		]
	}
});

FineUI.create({
	type: 'DropDownBox', id: 'ddb1', renderTo: document.body, fieldLabel: '所属省份', popPanel: 'tree1'
});

FineUI.create({
	type: 'Button', renderTo: document.body, text: '获取选中节点',
	handler: function () {
		var ddb = FineUI.ui.ddb1;
		var nodeId = ddb.getValue();             // 选中节点的 id
		if (nodeId) {
			var node = FineUI.ui.tree1.getNodeData(nodeId);   // 完整节点数据
			FineUI.alert('选中：' + ddb.getText() + '（id=' + nodeId + '，原始 text=' + node.text + '）');
		} else {
			FineUI.alert('未选中任何节点');
		}
	}
});

挂载 CheckBoxList 实现"多选下拉"。关键参数：multiSelect: true 启用多选、dataControl 指向数据控件 id、value 设初始选中值（数组，元素是 CheckBoxList 的 value）：

FineUI.create({
	type: 'DropDownBox', id: 'ddb2', renderTo: document.body, fieldLabel: '编程语言',
	multiSelect: true, value: ['js', 'php'],     // 初始选中 JavaScript 和 PHP
	dataControl: 'checkboxlist1',                // 指向下面的 CheckBoxList
	popPanel: {
		type: 'Form', hidden: true, layout: 'anchor', bodyPadding: 10, header: false,
		items: [{
			type: 'CheckBoxList', id: 'checkboxlist1', columnNumber: 3,
			data: [
				['csharp', 'C#'], ['js', 'JavaScript'], ['java', 'JAVA'],
				['php', 'PHP'], ['python', 'Python'], ['go', 'Go']
			]
		}]
	}
});

FineUI.create({
	type: 'Button', renderTo: document.body, text: '获取选中项',
	handler: function () {
		var values = FineUI.ui.ddb2.getValue();   // 返回数组，例如 ['js', 'php']
		FineUI.alert('选中：' + (values && values.length ? values.join(', ') : '无'));
	}
});

与FineUI.DropDownList的区别：DropDownBox用于挂载任意弹出面板（树、表格、自定义 Panel），DropDownList仅用于"数据数组的下拉列表"。

// 复杂选择器场景下用 DropDownBox，简单列表场景下优先用 DropDownList
FineUI.create({
	type: 'DropDownList', renderTo: document.body, fieldLabel: '简单列表', data: ['A', 'B', 'C']
});
Parameters:
Name Type Description
options Object

初始参数

Properties
Name Type Default Description
value string | Array.<string>

选中的值
text string

显示文本（仅在editable==true时有效）
editable boolean false

是否可以编辑（手工输入）
matchFieldWidth boolean true

弹出面板和表单字段的宽度相匹配
multiSelect boolean false

是否允许多选
multiSelectSeparator string ',

' - 多选的文本分隔符（默认值为 ', '）
multiSelectMode string 'text'

启用多选时的显示模式（可选项为：text, tags）
userInputPrefix string '__USERINPUT'

用户输入值的前缀（仅在启用多选标签模式时有效）
popPanel Object

弹出面板对象
dataControl Object

数据控件对象
customData boolean false

是否自定义数据来源
clearIcon boolean false

是否自动显示清空图标
alwaysDisplay boolean false

是否总是显示弹出面板
maxPopHeight number 300

弹出面板的最大高度
hiddenName string ''

用来存放下拉框 input 节点的 name 属性
topSpaceFirst boolean false

优先使用上部空间显示弹出框
enableClickAction boolean true

点击输入框是否触发默认行为
type string 'DropDownBox'

控件类型

Extends

Members

bodyEl :jQuery

Description:

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

Inherited From:

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

Type:
  • jQuery

el :jQuery

Description:

  • 控件对应的jQuery节点对象

Inherited From:

控件对应的jQuery节点对象

Type:
  • jQuery

items :Object

Description:

  • 子控件列表

Inherited From:

子控件列表

Type:
  • Object

Methods

getEncodedText(text) → {string}

Description:

  • 获取编码后的字符串

Inherited From:
Parameters:
Name Type Description
text string

原始字符串
Returns:

编码后的字符串

Type
string

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

Description:

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

Inherited From:
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>

getItem(value) → {FineUI.Component}

Description:

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

Inherited From:
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

hidePopEl()

Description:

  • 隐藏弹出框

Overrides:

isType(value) → {boolean}

Description:

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

Inherited From:
Example
grid1.isType('panel') // 返回true
grid1.isType('grid')  // 返回true
Parameters:
Name Type Description
value Object

控件类型
Returns:

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

Type
boolean

isUserInput() → {boolean}

Description:

  • 是否为用户自行输入值

Returns:

是否为用户自行输入值

Type
boolean

showPopEl()

Description:

  • 显示弹出框

Events

afterpoppanelshow

Description:

  • [已废弃] 旧版本事件名，新代码请使用 FineUI.DropDownBox#event:poppanelshow。源码会同时触发两个事件名仅为兼容旧业务代码，未来版本可能移除。

Deprecated:
Parameters:
Name Type Description
event jQuery.Event

事件对象

beforehide

Description:

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

Inherited From:

beforeshow

Description:

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

Inherited From:

blur

Description:

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

Inherited From:
Example

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

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

事件对象

change

Description:

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

Inherited From:
Example

响应值变化做联动：

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

事件对象

cleariconclick

Description:

  • 点击清空图标时触发

Parameters:
Name Type Description
event jQuery.Event

事件对象

enter

Description:

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

Inherited From:
Example

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

FineUI.create({
    type: 'TextBox', fieldLabel: '关键字',
    listeners: {
        enter: function () {
            FineUI.ui.btnSearch.click();
        }
    }
});
Parameters:
Name Type Description
event jQuery.Event

事件对象

focus

Description:

  • 输入框获取焦点时触发

Inherited From:
Parameters:
Name Type Description
event jQuery.Event

事件对象

hide

Description:

  • 隐藏控件时触发

Inherited From:

layout

Description:

  • 布局控件时触发

Inherited From:

poppanelshow

Description:

  • 显示弹出面板时触发

Parameters:
Name Type Description
event jQuery.Event

事件对象

remove

Description:

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

Inherited From:

render

Description:

  • 渲染控件时触发

Inherited From:

show

Description:

  • 显示控件时触发

Inherited From:

tagclose

Description:

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

Parameters:
Name Type Description
event jQuery.Event

事件对象
tagValue string

关闭标签的值
tagText string

关闭标签的显示文本

trigger1click

Description:

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

Inherited From:
Parameters:
Name Type Description
event jQuery.Event

事件对象

trigger2click

Description:

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

Inherited From:
Parameters:
Name Type Description
event jQuery.Event

事件对象

triggerclick

Description:

  • 点击触发图标时触发

Inherited From:
Parameters:
Name Type Description
event jQuery.Event

事件对象