CheckBoxList

FineUI. CheckBoxList

复选框列表控件。从数据数组生成多个互不互斥的复选框，支持多列布局、自动列宽、开关样式。

相关在线示例：

Constructor

new CheckBoxList(options)

Examples

创建复选框列表，data提供 [value, text] 二维数组，value设置预选值：

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

使用columnNumber控制每行列数，columnVertical: true纵向排列：

FineUI.create({
	type: 'CheckBoxList', renderTo: document.body, fieldLabel: '选项', width: 400,
	data: ['选项一', '选项二', '选项三', '选项四', '选项五', '选项六'],
	columnNumber: 3
});

使用displayType: 'switch'显示为开关样式：

FineUI.create({
	type: 'CheckBoxList', renderTo: document.body, fieldLabel: '通知',
	data: [['email', '邮件'], ['sms', '短信'], ['push', '推送']],
	displayType: 'switch'
});

禁用单个选项：data数组项的第 3 个元素对应默认 fields=['value','text','enabled','attrs','textRaw'] 中的 enabled 字段，设为 false 即禁用该项（短数据项可省略后续字段，使用默认值 enabled=true）：

FineUI.create({
	type: 'CheckBoxList', renderTo: document.body, fieldLabel: '兴趣',
	data: [
		['music', '音乐'],                       // 省略第 3 项 → enabled=true
		['sport', '运动（暂不可选）', false],     // 第 3 项 enabled=false → 此项被禁用
		['read', '阅读'],
		['travel', '旅行（暂不可选）', false]
	]
});

图标选项（可信 HTML）：text 用 FineUI.rawHtml(...) 声明为可信 HTML，原样输出图标；未用 FineUI.rawHtml 的普通字符串仍会被转义（防 XSS）。拼接图标 HTML 时，若名称等来自不可信来源须自行转义：

FineUI.create({
	type: 'CheckBoxList', renderTo: document.body, fieldLabel: '兴趣', columnNumber: 4,
	data: [
		{ value: 'music', text: FineUI.rawHtml('<img src="res/icon/music.png" />&nbsp;音乐') },
		{ value: 'sport', text: FineUI.rawHtml('<img src="res/icon/sport.png" />&nbsp;运动') }
	]
});
Parameters:
Name Type Description
options Object

初始参数

Properties
Name Type Default Description
value Array.<string>

选中的值
fields Array.<string> ['value','text','enabled','attrs','textRaw'

数据源对应的字段（textRaw 为真表示该项 text 是可信 HTML，原样输出不转义）
data Array.<string>

数据源（一维数组：['可选项1','可选项2','可选项3']，或者二维数组：[['value1','可选项1'], ['value2','可选项2'], ['value3','可选项3']]）。text 位可传 FineUI.rawHtml('<img...>名称') 声明可信 HTML（如图标选项）
columnNumber string | number 'auto'

几列显示
autoColumnWidth string | number false

自适应列宽度（默认所有列宽度相同）
columnVertical boolean false

是否纵向排列
required boolean false

是否必填项
displayType string 'default'

复选框的显示类型（可选项为：default, switch, radio）
switchTextVisible boolean false

是否显示开关类型的文本
switchOnText string ''

开关类型的选中文本
switchOffText string ''

开关类型的未选中文本
type string 'CheckBoxList'

控件类型

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

add(value)

Description:

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

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

  • 取消焦点

Inherited From:

clearDirty()

Description:

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

Inherited From:
Example

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

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

clearInvalid()

Description:

  • 清空无效标记

Inherited From:

clearValue()

Description:

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

Inherited From:
Example

清空所有筛选字段：

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

disable()

Description:

  • 禁用控件

Overrides:

doLayout(startFormTopmostComonentopt)

Description:

  • 执行布局操作

Inherited From:
Parameters:
Name Type Attributes Default Description
startFormTopmostComonent boolean <optional>
 false

从最顶层的控件开始布局

enable()

Description:

  • 启用控件

Overrides:

focus(selectTextopt, delayMillisecondsopt)

Description:

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

Inherited From:
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:
Parameters:
Name Type Description
key string

节点属性键
Returns:

节点属性值

Type
string

getEncodedText(text) → {string}

Description:

  • 获取编码后的字符串

Inherited From:
Parameters:
Name Type Description
text string

原始字符串
Returns:

编码后的字符串

Type
string

getFieldLabel() → {string}

Description:

  • 获取字段标签

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

getHeight() → {number}

Description:

  • 获取控件高度

Inherited From:
Returns:

高度

Type
number

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

getText() → {string}

Description:

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

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

getTextByValue(value) → {string}

Description:

  • 获取值对应的显示文本

Parameters:
Name Type Description
value string

值
Returns:

值对应的显示文本

Type
string

getTooltip() → {string}

Description:

  • 获取提示信息

Inherited From:
Returns:

提示信息

Type
string

getValue() → {Array.<string>}

Description:

  • 获取值

Overrides:
Returns:

选中值数组

Type
Array.<string>

getWidth() → {number}

Description:

  • 获取控件宽度

Inherited From:
Returns:

宽度

Type
number

hide()

Description:

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

Inherited From:
Example

根据权限隐藏按钮：

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

hideLoading()

Description:

  • 隐藏加载动画

Inherited From:

hidePopEl()

Description:

  • 隐藏容器内的所有弹出框

Inherited From:

insert(insertIndex, value)

Description:

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

Inherited From:
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时的值比较）

Inherited From:
Example

关闭页面前提示未保存：

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

字段值是否已经改变

Type
boolean

isDisabled() → {boolean}

Description:

  • 是否禁用

Inherited From:
Returns:

是否禁用

Type
boolean

isFocused() → {boolean}

Description:

  • 是否焦点元素

Inherited From:
Returns:

是否焦点元素

Type
boolean

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

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

Description:

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

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

是否可见

Type
boolean

loadData(data)

Description:

  • 加载数据

Parameters:
Name Type Description
data Array.<Object>

二维数组（[['value1','选项一'],['value2','选项二'],['value3','选项三']]）

markInvalid(errorMsg)

Description:

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

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

动态添加 + 移除子控件：

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

removeAttr(key)

Description:

  • 删除节点属性

Inherited From:
Parameters:
Name Type Description
key string

节点属性键

removeTooltip()

Description:

  • 删除提示信息

Inherited From:

reset()

Description:

  • 重置字段

Inherited From:

setAttr(key, value)

Description:

  • 设置节点属性

Inherited From:
Parameters:
Name Type Description
key string

节点属性键
value string

节点属性值

setAttrs(attrs)

Description:

  • 设置节点属性

Inherited From:
Parameters:
Name Type Description
attrs Object

节点属性对象

setDisabled(disabled)

Description:

  • 设置控件的禁用状态

Inherited From:
Parameters:
Name Type Description
disabled boolean

是否禁用

setEnabled(enabled)

Description:

  • 设置控件的启用状态

Inherited From:
Parameters:
Name Type Description
enabled boolean

是否启用

setFieldLabel(label)

Description:

  • 设置字段标签

Inherited From:
Parameters:
Name Type Description
label string

字段标签

setHeight(height)

Description:

  • 设置控件高度

Inherited From:
Parameters:
Name Type Description
height number

高度

setHidden(hidden)

Description:

  • 设置控件的隐藏状态

Inherited From:
Parameters:
Name Type Description
hidden boolean

是否隐藏

setReadonly(readonly)

Description:

  • 设置只读

Overrides:
Parameters:
Name Type Description
readonly boolean

只读状态

setRedStar(redStar)

Description:

  • 设置是否显示红色星号

Inherited From:
Parameters:
Name Type Description
redStar boolean

是否显示红色星号

setRequired(required)

Description:

  • 设置是否必填

Parameters:
Name Type Description
required boolean

是否必填

setSize(width, height)

Description:

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

Inherited From:
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:
Parameters:
Name Type Description
tooltip string

提示信息

setValue(values, forceNoValidate)

Description:

  • 设置值

Overrides:
Parameters:
Name Type Description
values Array.<string>

选中值数组
forceNoValidate boolean

是否验证

setVisible(visible)

Description:

  • 设置控件的显示状态

Inherited From:
Parameters:
Name Type Description
visible boolean

是否可见

setWidth(width)

Description:

  • 设置控件宽度

Inherited From:
Parameters:
Name Type Description
width number

宽度

show()

Description:

  • 显示控件（与hide对应）

Inherited From:
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:
Parameters:
Name Type Description
opacity number

透明度（默认值：0.65）
container jQuery

显示动画的目标元素（留空则为内容元素）

toggleEnabled()

Description:

  • 切换启用状态

Inherited From:

toggleVisible()

Description:

  • 切换显示状态

Inherited From:

trigger(eventName, args)

Description:

  • 触发事件

Inherited From:
Parameters:
Name Type Description
eventName string

事件名称
args Object

事件参数

validate() → {boolean}

Description:

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

Inherited From:
Example

失焦时主动校验单字段：

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

是否有效

Type
boolean

Events

beforehide

Description:

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

Inherited From:

beforeshow

Description:

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

Inherited From:

change

Description:

  • 复选框列表选中状态改变时触发

Parameters:
Name Type Description
event jQuery.Event

事件对象
item FineUI.CheckBox

触发事件的复选框对象
checked boolean

是否处于按下状态

hide

Description:

  • 隐藏控件时触发

Inherited From:

layout

Description:

  • 布局控件时触发

Inherited From:

remove

Description:

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

Inherited From:

render

Description:

  • 渲染控件时触发

Inherited From:

show

Description:

  • 显示控件时触发

Inherited From: