DataList

FineUI. DataList

new DataList(options)

Description:

列表控件。常用于移动端场景，支持选择、多选、分组、超链接、面板切换等。

相关在线示例（多为移动端场景）：

Examples

创建基础列表，data提供 [value, text] 二维数组：

FineUI.create({
	type: 'DataList', renderTo: document.body, width: 300, height: 300, title: '城市列表',
	data: [['bj', '北京'], ['sh', '上海'], ['gz', '广州'], ['sz', '深圳']]
});

使用selectable: true启用选中、multiSelect: true启用多选：

FineUI.create({
	type: 'DataList', renderTo: document.body, width: 300, height: 300, title: '可多选',
	data: [['a', '选项 A'], ['b', '选项 B'], ['c', '选项 C'], ['d', '选项 D']],
	selectable: true, multiSelect: true
});

使用group: true启用分组。默认 fields=['value','text','enabled','group','href','hrefTarget','arrow']（group 是第 4 个），实际使用中建议显式重写fields来精简数据：

FineUI.create({
	type: 'DataList', renderTo: document.body, width: 300, height: 350, title: '分组列表', group: true,
	fields: ['value', 'text', 'group'],
	data: [
		['bj', '北京', '直辖市'],
		['sh', '上海', '直辖市'],
		['gz', '广州', '广东省'],
		['sz', '深圳', '广东省']
	]
});

通过itemclick事件响应点击（事件第二个参数是被点击项的value字符串）：

FineUI.create({
	type: 'DataList', renderTo: document.body, width: 300, height: 250, selectable: true,
	data: [['a', '选项 A'], ['b', '选项 B'], ['c', '选项 C']],
	listeners: {
		itemclick: function (event, itemValue) {
			FineUI.alert('点击了 value：' + itemValue);
		}
	}
});

Parameters:

Name Type Description

options

Object

初始参数

Properties

Name	Type	Default	Description
`fields`	Array.<string>	`['value','text','enabled','group','href','hrefTarget','arrow'`	数据源对应的字段
`group`	boolean	`false`	是否启用分组
`selectable`	boolean	`false`	是否可选择
`multiSelect`	boolean	`false`	是否允许多选（通过 Ctrl, Shift 键进行多选）
`enableTextSelection`	boolean	`false`	是否启用文本选择
`keepCurrentSelection`	boolean	`false`	多选时保持当前已选中项
`clickOnContextMenu`	boolean	`true`	右键点击时选中当前项（默认为true）
`type`	string	`'DataList'`	控件类型

Extends

FineUI.Container

Members

el :jQuery

Description:

控件对应的jQuery节点对象

Inherited From:

FineUI.Component#el

控件对应的jQuery节点对象

Type:

jQuery

items :Object

Description:

子控件列表

Inherited From:

FineUI.Container#items

子控件列表

Type:

Object

Methods

appendData(data)

Description:

追加数据（在现有数据末尾追加，不会清空；移动端"加载更多"场景常用）

Example

"加载更多"按钮场景：

FineUI.ui.datalist1.appendData([
    ['nj', '南京'],
    ['hz', '杭州']
]);

Parameters:

Name	Type	Description
`data`	Array.<Object>	数据

clearSelection()

Description:

清空全部选中项

deselectAllItems()

Description:

取消选中全部列表项

deselectItem(row)

Description:

取消选中列表项

Parameters:

Name	Type	Description
`row`	number \| string \| jQuery	列表项索引、列表项值或者列表项元素

deselectItems(itemValues)

Description:

取消选中多列表项

Parameters:

Name	Type	Description
`itemValues`	Array.<number> \| Array.<string> \| Array.<jQuery>	列表项索引数组、列表项值数组或者列表项元素数组

getEncodedText(text) → {string}

Description:

获取编码后的字符串

Inherited From:

FineUI.Component#getEncodedText

Parameters:

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

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>

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

getItemData(item) → {Object}

Description:

获取项数据

Parameters:

Name	Type	Description
`item`	number \| string \| jQuery	列表项索引、列表项值或者列表项元素

Returns:

项数据

Type: Object

getItemEl(row) → {jQuery}

Description:

获取列表列表项元素

Parameters:

Name	Type	Description
`row`	number \| string \| jQuery	列表项索引、列表项值或者列表项元素

Returns:

列表列表项元素

Type: jQuery

getItemEls() → {jQuery}

Description:

获取列表列表项元素集合

Returns:

列表列表项元素集合

Type: jQuery

getSelectedItem(returnItemDataopt) → {string|Object}

Description:

获取选中的列表项值（单选场景）

Example

单选场景取选中 value：

var value = FineUI.ui.datalist1.getSelectedItem();
// 例如：'bj'

Parameters:

Name	Type	Attributes	Description
`returnItemData`	boolean	<optional>	传`true`则返回列表项对象，否则返回列表项值

Returns:

列表项值，或列表项对象

Type: string | Object

getSelectedItems(returnItemDataopt) → {Array.<string>|Array.<Object>}

Description:

获取选中的列表项值数组（多选场景）

Examples

获取所有选中项的 value 字符串数组：

var values = FineUI.ui.datalist1.getSelectedItems();
// 例如：['bj', 'sh']

获取选中项的完整数据：

var items = FineUI.ui.datalist1.getSelectedItems(true);
// 例如：[{ value: 'bj', text: '北京' }, { value: 'sh', text: '上海' }]

Parameters:

Name	Type	Attributes	Description
`returnItemData`	boolean	<optional>	传`true`则返回列表项对象数组，否则返回列表项值数组

Returns:

列表项值数组，或列表项对象数组

Type: Array.<string> | Array.<Object>

getTextByValue(value) → {string}

Description:

获取值对应的显示文本

Parameters:

Name	Type	Description
`value`	string	值

Returns:

值对应的显示文本

Type: string

getValueByText(text) → {string}

Description:

获取显示文本对应的值

Parameters:

Name	Type	Description
`text`	string	显示文本

Returns:

显示文本对应的值

Type: string

hidePopEl()

Description:

隐藏容器内的所有弹出框

Inherited From:

FineUI.Container#hidePopEl

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

loadData(data, selectedItemsopt)

Description:

加载数据（会替换列表全部项；可同时指定默认选中值）

Examples

加载列表数据：

FineUI.ui.datalist1.loadData([
    ['bj', '北京'],
    ['sh', '上海']
]);

加载并默认选中：

FineUI.ui.datalist1.loadData(
    [['bj', '北京'], ['sh', '上海'], ['gz', '广州']],
    ['bj', 'sh']  // 多选场景默认选中
);

Parameters:

Name	Type	Attributes	Description
`data`	Array.<Object>		数据
`selectedItems`	string \| Array.<string>	<optional>	选中的值（多选场景为数组）

selectAllItems()

Description:

选中全部列表项

selectItem(itemValue, options)

Description:

选中列表项

Parameters:

Name Type Description

itemValue

number | string | jQuery

列表项索引、列表项值或者列表项元素

options

Object

参数

Properties

Name	Type	Default	Description
`keep`	boolean	`false`	是否保持已选中项
`keepUnselectable`	boolean	`true`	是否保持不可选择项的选中状态（options.keep=true时，此参数无效）
`scrollTo`	boolean	`true`	是否滚动到选中项（仅有一项处于选中状态时有效）

selectItems(itemValues, optionsopt)

Description:

选中多个列表项

Examples

批量选中多项（替换当前选中）：

FineUI.ui.datalist1.selectItems(['bj', 'sh']);

在已有选中基础上追加：

FineUI.ui.datalist1.selectItems(['gz'], { keep: true });

Parameters:

Name Type Attributes Description

itemValues

Array.<number> | Array.<string> | Array.<jQuery>

列表项索引数组、列表项值数组或者列表项元素数组

options

Object

参数

Properties

Name	Type	Default	Description
`keep`	boolean	`false`	是否保持已选中项
`keepUnselectable`	boolean	`true`	是否保持不可选择项的选中状态（options.keep=true时，此参数无效）
`scrollTo`	boolean	`true`	是否滚动到选中项（仅有一项处于选中状态时有效）

Events

beforehide

Description:

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

Inherited From:

FineUI.Component#event:beforehide

beforeitemcontextmenu

Description:

右键点击行时触发（返回false则阻止浏览器默认的右键菜单）

Parameters:

Name	Type	Description
`event`	jQuery.Event	事件对象
`itemValue`	string	列表项的值

beforeshow

Description:

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

Inherited From:

FineUI.Component#event:beforeshow

hide

Description:

隐藏控件时触发

Inherited From:

FineUI.Component#event:hide

itemclick

Description:

点击列表项时触发

Parameters:

Name	Type	Description
`event`	jQuery.Event	事件对象
`itemValue`	string	列表项的值

itemdblclick

Description:

双击行时触发

Parameters:

Name	Type	Description
`event`	jQuery.Event	事件对象
`itemValue`	string	列表项的值

itemdeselect

Description:

取消选中列表项时触发

Parameters:

Name	Type	Description
`event`	jQuery.Event	事件对象
`itemValue`	string	列表项值

itemselect

Description:

选中列表项时触发

Parameters:

Name	Type	Description
`event`	jQuery.Event	事件对象
`itemValue`	string	列表项值

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

selectionchange

Description:

选中项改变时触发

Parameters:

Name	Type	Description
`event`	jQuery.Event	事件对象

show

Description:

显示控件时触发

Inherited From:

FineUI.Component#event:show