Button - FineUI.js

Button

FineUI. Button

按钮控件。支持图标（图片或图标字体）、按下状态、菜单挂载、徽标、表单校验等。

相关在线示例：

Constructor

new Button(options)

Examples

创建按钮，使用参数handler来指定点击按钮时执行的代码：

FineUI.create({
	type: 'Button', renderTo: document.body, text: '按钮',
	handler: function () {
		FineUI.alert('你点击了按钮');
	}
});

也可以通过FineUI.Button#event:click来设置按钮的点击事件处理函数，通过这种方式设置的代码会先于handler执行：

FineUI.create({
	type: 'Button', renderTo: document.body, text: '按钮',
	listeners: {
		click: function (event) {
			FineUI.alert('你点击了按钮');
		}
	}
});

使用参数icon指定按钮图标，或者参数iconFont指定图标字体：

FineUI.create({
	type: 'Button', renderTo: document.body, text: '按钮', icon: '../res/icon/tag_green.png'
});

按钮可以被按下，使用参数enablePress来启用，并通过pressed设置当前的状态：

FineUI.create({
	type: 'Button', renderTo: document.body, text: '按钮', enablePress: true, pressed: true
});

按钮菜单可以使用参数menu来设置，拥有菜单的按钮会在右侧显示一个箭头图标，点击按钮时弹出菜单：

FineUI.create({
	type: 'Button', renderTo: document.body, text: '按钮', iconFont: 'bank',
	menu: {
		type: 'Menu',
		items: [{
			type: 'MenuItem', text: '菜单一'
		}, {
			type: 'MenuItem', text: '菜单二', icon: '../res/icon/tag_pink.png', href: 'http://www.ustc.edu.cn/', hrefTarget: '_blank'
		}]
	}
});

Parameters:

Name Type Description

options

Object

初始参数

Properties

Name	Type	Default	Description
`text`	string	`''`	显示文本
`scale`	string	`'normal'`	按钮的大小（可选项为：small, normal, medium, large）
`enablePress`	boolean	`false`	是否启用按下状态
`enableToggle`	boolean		[已废弃] 旧版本属性名，请改用 `enablePress`。兼容性保留：若用户传入此参数会被识别并启用按下状态（与 `enablePress` 等价）。
`pressed`	boolean	`false`	是否处于按下状态
`icon`	string	`''`	图标
`iconFont`	string	`''`	图标字体
`iconFontCls`	string	`''`	自定义图标字体的样式类
`iconAlign`	string	`'left'`	按钮图标的位置（可选项为：left, right, top, bottom）
`validateForm`	string	`''`	需要验证的表单
`validateForms`	Array.<string>		需要验证的表单标识符数组
`validateTarget`	string	`'_self'`	验证失败时提示对话框的弹出位置（可选项为：_self, _parent, _top）
`validateMessageBox`	boolean	`true`	验证失败时是否出现提示对话框
`badge`	boolean	`false`	是否启用徽标
`badgeText`	string	`''`	徽标文本
`badgeType`	string	`'information'`	徽标类型（可选项为：information, error, success, warning）
`badgeAnimationType`	string	`'none'`	徽标动画类型（可选项为：none, processing, fade, shake, move）
`tabIndex`	number	`0`	TAB键导航的顺序
`type`	string	`'Button'`	控件类型

Extends

FineUI.Component

Members

el :jQuery

Description:

控件对应的jQuery节点对象

Inherited From:

FineUI.Component#el

控件对应的jQuery节点对象

Type:

jQuery

Methods

click()

Description:

程序触发按钮点击（依次走beforeclick/click事件 + handler）

Example

用键盘 Enter 触发某按钮（使用 FineUI 暴露的 FineUI.KEY 常量）：

$(document).on('keydown', function (event) {
    if (event.keyCode === FineUI.KEY.ENTER) {
        FineUI.ui.btnSubmit.click();
    }
});

disable()

Description:

禁用控件（按钮变灰、表单字段不可输入；可用isDisabled查询当前状态）

Inherited From:

FineUI.Component#disable

Example

提交期间禁用按钮，避免重复提交（用 jQuery 的 $.ajax）：

FineUI.create({
    type: 'Button', text: '提交',
    handler: function () {
        var me = this;
        me.disable();
        $.ajax({
            url: '/api/save', method: 'POST', dataType: 'json',
            complete: function () {
                me.enable();
            }
        });
    }
});

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

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

getHeight() → {number}

Description:

获取控件高度

Inherited From:

FineUI.Component#getHeight

Returns:

高度

Type: number

getText() → {string}

Description:

获取按钮文本

Returns:

按钮文本

Type: string

getTooltip() → {string}

Description:

获取提示信息

Inherited From:

FineUI.Component#getTooltip

Returns:

提示信息

Type: string

getWidth() → {number}

Description:

获取控件宽度

Inherited From:

FineUI.Component#getWidth

Returns:

宽度

Type: number

hasIcon() → {boolean}

Description:

是否有图标

Returns:

是否有图标

Type: boolean

hide()

Description:

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

Inherited From:

FineUI.Component#hide

Example

根据权限隐藏按钮：

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

hidePopEl()

Description:

隐藏弹出菜单

isDisabled() → {boolean}

Description:

是否禁用

Inherited From:

FineUI.Component#isDisabled

Returns:

是否禁用

Type: boolean

isPressed() → {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

isVisible() → {boolean}

Description:

是否可见

Inherited From:

FineUI.Component#isVisible

Returns:

是否可见

Type: boolean

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

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	节点属性对象

setBadge(badge, badgeText, badgeType, badgeAnimationType)

Description:

设置徽标

Parameters:

Name	Type	Description
`badge`	boolean	是否启用徽标
`badgeText`	string	徽标文本
`badgeType`	string	徽标类型（可选项为：information, error, success, warning）
`badgeAnimationType`	string	徽标动画类型（可选项为：none, processing, fade, shake, move）

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	是否启用

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	是否隐藏

setIcon(icon)

Description:

设置图标地址

Example

FineUI.ui.button1.setIcon('../res/images/16/1.png');

Parameters:

Name	Type	Description
`icon`	string	图标地址

setIconFont(iconFont)

Description:

设置图标字体

Example

FineUI.ui.button1.setIconFont('bank');

Parameters:

Name	Type	Description
`iconFont`	string	图标字体

setMenu(menu)

Description:

设置菜单

Parameters:

Name	Type	Description
`menu`	Object \| string	菜单对象或者菜单标识符

setPressed(pressed)

Description:

设置按下状态（仅enablePress: true的按钮有效；常用作开关按钮）

Example

按下按钮：

FineUI.ui.btnDark.setPressed(true);

Parameters:

Name	Type	Description
`pressed`	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	高度

setText(text)

Description:

设置按钮文本（动态更改按钮的显示文本）

Example

显示中间态：

FineUI.ui.btnMore.setText('加载中...');
FineUI.ui.btnMore.disable();
$.ajax({
    url: '/api/more', dataType: 'json',
    complete: function () {
        FineUI.ui.btnMore.setText('加载更多');
        FineUI.ui.btnMore.enable();
    }
});

Parameters:

Name	Type	Description
`text`	string	按钮文本

setTooltip(tooltip)

Description:

设置提示信息

Inherited From:

FineUI.Component#setTooltip

Parameters:

Name	Type	Description
`tooltip`	string	提示信息

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();
    }
});

showPopEl()

Description:

显示弹出菜单

toggleEnabled()

Description:

切换启用状态

Inherited From:

FineUI.Component#toggleEnabled

togglePressed()

Description:

切换按下状态（按下变弹起，弹起变按下）

Example

按下时显示侧栏，弹起时隐藏（在 click 中切换）：

FineUI.create({
    type: 'Button', text: '侧栏', enablePress: true,
    handler: function () {
        if (this.isPressed()) {
            FineUI.ui.panelSide.show();
        } else {
            FineUI.ui.panelSide.hide();
        }
    }
});