# jQuery UI API - 按钮部件(Button Widget)
## 所属类别
[小部件(Widgets)](ref-widgets.html)
## 用法
**描述:**可主题化的按钮和按钮集合。
**版本新增:**1.8
按钮部件(Button Widget)加强了标准表单元素的功能,比如按钮(button)、输入(input)、锚(anchor),用适当的悬停(hover)和激活(active)样式来主题化按钮。
除了基本的按钮,单选按钮和复选框(input 类型为 radio 和 checkbox)也可以转换为按钮。相关的标签(label)设计成按钮的样式,点击时更新底层的输入。为了能正常工作,需要给 input 一个 `id` 属性,并指向标签(label)的 `for` 属性。不要把 input 放在标签(label)内,否则会[引起可访问性问题](//www.paciellogroup.com/blog/2011/07/html5-accessibility-chops-form-control-labeling/)。
为了分组单选按钮,Button 也提供了一个额外的小部件,名为 Buttonset。Buttonset 通过选择一个容器元素(包含单选按钮)并调用 `.buttonset()` 来使用。Buttonset 也提供了可视化分组,因此当有一组按钮时都可考虑使用它。它会选择所有的后代,并对它们应用 `.button()`。您可以启用和禁用一个按钮集,这将会启用和禁用所有包含的按钮。销毁按钮集会调用每个按钮的 `destroy` 方法。对于分组的单选按钮和复选框按钮,推荐使用带有 `legend` 的 `fieldset` 来提供一个可访问的分组标签。
当使用一个类型为 button、submit 或 reset 的 input 时,仅限于支持纯文本无图标标签。
### 主题化
按钮部件(Button Widget)使用 [jQuery UI CSS 框架](api-css-framework.html) 来定义它的外观和感观的样式。如果需要使用按钮指定的样式,则可以使用下面的 CSS class 名称:
* `ui-button`:表示按钮的 DOM 元素。该元素会根据 [text](#option-text) 和 [icons](#option-icons) 选项添加下列 class 之一:`ui-button-text-only`、`ui-button-icon-only`、`ui-button-icons-only`、`ui-button-text-icons`。
* `ui-button-icon-primary`:用于显示按钮主要图标的元素。只有当主要图标在 [icons](#option-icons) 选项中提供时才呈现。
* `ui-button-text`:在按钮的文本内容周围的容器。
* `ui-button-icon-secondary`:用于显示按钮的次要图标。只有当次要图标在 [icons](#option-icons) 选项中提供时才呈现。
* `ui-buttonset`:Buttonset 的外层容器。
### 依赖
* [UI 核心(UI Core)](ref-ui-core.html)
* [部件库(Widget Factory)](api-jQuery-widget.html)
### 附加说明
* 该部件要求一些功能性的 CSS,否则将无法工作。如果您创建了一个自定义的主题,请使用小部件指定的 CSS 文件作为起点。
### 快速导航
| 选项 | 方法 | 事件 |
| --- | --- | --- |
| [disabled](#option-disabled)[icons](#option-icons)[label](#option-label)[text](#option-text) | [destroy](#method-destroy)[disable](#method-disable)[enable](#method-enable)[option](#method-option)[refresh](#method-refresh)[widget](#method-widget) | [create](#event-create) |
#### disabled
**类型**:Boolean
**描述**:如果设置为 `true`,则禁用该 button。
**代码实例:**
初始化带有指定 `disabled` 选项的 button:
```
$( ".selector" ).button({ disabled: true });
```
在初始化后,获取或设置 `disabled` 选项:
```
// getter
var disabled = $( ".selector" ).button( "option", "disabled" );
// setter
$( ".selector" ).button( "option", "disabled", true );
```
**默认值**:false
#### icons
**类型**:Object
**描述**:要显示的图标,包括带有文本的图标和不带有文本的图标(查看 [`text`](#option-text) 选项)。默认情况下 ,主图标显示在标签文本的左边,副图标显示在右边。显示位置可通过 CSS 进行控制。
`primary` 和 `secondary` 属性值必须是 [图标 class 名称](api-icons.html),例如,`"ui-icon-gear"`。如果只使用一个图标,则 `icons: { primary: "ui-icon-locked" }`。如果使用两个图标,则 `icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }`。
**代码实例:**
初始化带有指定 `icons` 选项的 button:
```
$( ".selector" ).button({ icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } });
```
在初始化后,获取或设置 `disabled` 选项:
```
// getter
var icons = $( ".selector" ).button( "option", "icons" );
// setter
$( ".selector" ).button( "option", "icons", { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } );
```
**默认值**:{ primary: null, secondary: null }
#### label
**类型**:String
**描述**:要显示在按钮中的文本。当未指定时(`null`),则使用元素的 HTML 内容,或者如果元素是一个 submit 或 reset 类型的 input 元素,则使用它的 `value` 属性,或者如果元素是一个 radio 或 checkbox 类型的 input 元素,则使用相关的 label 元素的 HTML 内容。
**代码实例:**
初始化带有指定 `label` 选项的 button:
```
$( ".selector" ).button({ label: "custom label" });
```
在初始化后,获取或设置 `label` 选项:
```
// getter
var label = $( ".selector" ).button( "option", "label" );
// setter
$( ".selector" ).button( "option", "label", "custom label" );
```
**默认值**:null
#### text
**类型**:Boolean
**描述**:是否显示标签。当设置为 `false` 时,不显示文本,但是此时必须启用 [`icons`](#options-icons) 选项,否则 `text` 选项将被忽略。
**代码实例:**
初始化带有指定 `text` 选项的 button:
```
$( ".selector" ).button({ text: false });
```
在初始化后,获取或设置 `text` 选项:
```
// getter
var text = $( ".selector" ).button( "option", "text" );
// setter
$( ".selector" ).button( "option", "text", false );
```
**默认值**:true
#### 方法
#### destroy()
**类型**:jQuery (plugin only)
**描述**:完全移除 button 功能。这会把元素返回到它的预初始化状态。
* 该方法不接受任何参数。
**代码实例:**
调用 destroy 方法:
```
$( ".selector" ).button( "destroy" );
```
#### disable()
**类型**:jQuery (plugin only)
**描述**:禁用 button。
* 该方法不接受任何参数。
**代码实例:**
调用 disable 方法:
```
$( ".selector" ).button( "disable" );
```
#### enable()
**类型**:jQuery (plugin only)
**描述**:启用 button。
* 该方法不接受任何参数。
**代码实例:**
调用 enable 方法:
```
$( ".selector" ).button( "enable" );
```
#### option( optionName )
**类型**:Object
**描述**:获取当前与指定的 `optionName` 关联的值。
* **optionName**
类型:String
描述:要获取的选项的名称。
**代码实例:**
调用该方法:
```
var isDisabled = $( ".selector" ).button( "option", "disabled" );
```
#### option()
**类型**:PlainObject
**描述**:获取一个包含键/值对的对象,键/值对表示当前 button 选项哈希。
* 该方法不接受任何参数。
**代码实例:**
调用该方法:
```
var options = $( ".selector" ).button( "option" );
```
#### option( optionName, value )
**类型**:jQuery (plugin only)
**描述**:设置与指定的 `optionName` 关联的 button 选项的值。
* **optionName**
类型:String
描述:要设置的选项的名称。
* **value**
类型:Object
描述:要为选项设置的值。
**代码实例:**
调用该方法:
```
$( ".selector" ).button( "option", "disabled", true );
```
#### option( options )
**类型**:jQuery (plugin only)
**描述**:为 button 设置一个或多个选项。
* **options**
类型:Object
描述:要设置的 option-value 对。
**代码实例:**
调用该方法:
```
$( ".selector" ).button( "option", { disabled: true } );
```
#### refresh()
**类型**:jQuery (plugin only)
**描述**:刷新按钮的视觉状态。用于在以编程方式改变原生元素的选中状态或禁用状态后更新按钮状态。
* 该方法不接受任何参数。
**代码实例:**
调用 refresh 方法:
```
$( ".selector" ).button( "refresh" );
```
#### widget()
**类型**:jQuery
**描述**:返回一个包含 button 的 `jQuery` 对象。
* 该方法不接受任何参数。
**代码实例:**
调用 widget 方法:
```
var widget = $( ".selector" ).button( "widget" );
```
#### 事件
#### create( event, ui )
**类型**:buttoncreate
**描述**:当创建按钮 button 时触发。
* **event**
类型:Event
* **ui**
类型:Object
注意:`ui` 对象是空的,这里包含它是为了与其他事件保持一致性。
**代码实例:**
初始化带有指定 create 回调的 button:
```
$( ".selector" ).button({
create: function( event, ui ) {}
});
```
绑定一个事件监听器到 buttoncreate 事件:
```
$( ".selector" ).on( "buttoncreate", function( event, ui ) {} );
```
## 实例
**实例 1:**
一个简单的 jQuery UI 按钮(Button)。
```
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>按钮部件(Button Widget)演示</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<button>按钮标签</button>
<script>
$( "button" ).button();
</script>
</body>
</html>
```
**实例 2:**
一个简单的 jQuery UI 按钮集(Buttonset)。
```
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>按钮部件(Button Widget)演示</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<form>
<fieldset>
<legend>最喜欢的 jQuery 项目</legend>
<div id="radio">
<input type="radio" id="sizzle" name="project">
<label for="sizzle">Sizzle</label>
<input type="radio" id="qunit" name="project" checked="checked">
<label for="qunit">QUnit</label>
<input type="radio" id="color" name="project">
<label for="color">Color</label>
</div>
</fieldset>
</form>
<script>
$( "#radio" ).buttonset();
</script>
</body>
</html>
```
- jQuery UI 基础
- jQuery UI 简介
- jQuery UI 下载
- jQuery UI 使用
- jQuery UI 定制
- jQuery UI 工作原理
- jQuery UI 主题
- jQuery UI 主题
- jQuery UI ThemeRoller
- jQuery UI CSS 框架 API
- jQuery UI 设计主题
- jQuery UI 部件库
- jQuery UI 部件库(Widget Factory)
- jQuery UI 通过部件库(Widget Factory)扩展小部件
- jQuery UI 小部件(Widget)方法调用
- jQuery UI 为什么使用部件库(Widget Factory)
- jQuery UI 如何使用部件库(Widget Factory)
- jQuery UI 实例
- jQuery UI 实例
- jQuery UI 实例 - 拖动(Draggable)
- jQuery UI 实例 - 放置(Droppable)
- jQuery UI 实例 - 缩放(Resizable)
- jQuery UI 实例 - 选择(Selectable)
- jQuery UI 实例 - 排序(Sortable)
- jQuery UI 实例 - 折叠面板(Accordion)
- jQuery UI 实例 - 自动完成(Autocomplete)
- jQuery UI 实例 - 按钮(Button)
- jQuery UI 实例 - 日期选择器(Datepicker)
- jQuery UI 实例 - 对话框(Dialog)
- jQuery UI 实例 - 菜单(Menu)
- jQuery UI 实例 - 进度条(Progressbar)
- jQuery UI 实例 - 滑块(Slider)
- jQuery UI 实例 - 旋转器(Spinner)
- jQuery UI 实例 - 标签页(Tabs)
- jQuery UI 实例 - 工具提示框(Tooltip)
- jQuery UI 实例 - 特效(Effect)
- jQuery UI 实例 - 显示(Show)
- jQuery UI 实例 - 隐藏(Hide)
- jQuery UI 实例 - 切换(Toggle)
- jQuery UI 实例 - 添加 Class(Add Class)
- jQuery UI 实例 - 移除 Class(Remove Class)
- jQuery UI 实例 - 切换 Class(Toggle Class)
- jQuery UI 实例 - 转换 Class(Switch Class)
- jQuery UI 实例 - 颜色动画(Color Animation)
- jQuery UI 实例 - 定位(Position)
- jQuery UI 实例 - 部件库(Widget Factory)
- jQuery UI API 参考
- jQuery UI API 类别 - 特效(Effects)
- jQuery UI API - .addClass()
- jQuery UI API - 百叶窗特效(Blind Effect)
- jQuery UI API - 反弹特效(Bounce Effect)
- jQuery UI API - 剪辑特效(Clip Effect)
- jQuery UI API - 颜色动画(Color Animation)
- jQuery UI API - 降落特效(Drop Effect)
- jQuery UI API - Easings
- jQuery UI API - .effect()
- jQuery UI API - 爆炸特效(Explode Effect)
- jQuery UI API - 淡入淡出特效(Fade Effect)
- jQuery UI API - 折叠特效(Fold Effect)
- jQuery UI API - .hide()
- jQuery UI API - 突出特效(Highlight Effect)
- jQuery UI API - 膨胀特效(Puff Effect)
- jQuery UI API - 跳动特效(Pulsate Effect)
- jQuery UI API - .removeClass()
- jQuery UI API - 缩放特效(Scale Effect)
- jQuery UI API - 震动特效(Shake Effect)
- jQuery UI API - .show()
- jQuery UI API - 尺寸特效(Size Effect)
- jQuery UI API - 滑动特效(Slide Effect)
- jQuery UI API - .switchClass()
- jQuery UI API - .toggle()
- jQuery UI API - .toggleClass()
- jQuery UI API - 转移特效(Transfer Effect)
- jQuery UI API 类别 - 特效核心(Effects Core)
- jQuery UI API - 颜色动画(Color Animation)
- jQuery UI API 类别 - 交互(Interactions)
- jQuery UI API - 可拖拽小部件(Draggable Widget)
- jQuery UI API - 可放置小部件(Droppable Widget)
- jQuery UI API - 鼠标交互(Mouse Interaction)
- jQuery UI API - 可调整尺寸小部件(Resizable Widget)
- jQuery UI API - 可选择小部件(Selectable Widget)
- jQuery UI API - 可排序小部件(Sortable Widget)
- jQuery UI API 类别 - 方法重载(Method Overrides)
- jQuery UI API - .focus()
- jQuery UI API - .position()
- jQuery UI API 类别 - 方法(Methods)
- jQuery UI API - .disableSelection()
- jQuery UI API - .enableSelection()
- jQuery UI API - .removeUniqueId()
- jQuery UI API - .scrollParent()
- jQuery UI API - .uniqueId()
- jQuery UI API - .zIndex()
- jQuery UI API 类别 - 选择器(Selectors)
- jQuery UI API - :data() Selector
- jQuery UI API - :focusable Selector
- jQuery UI API - :tabbable Selector
- jQuery UI API 类别 - 主题(Theming)
- jQuery UI API - CSS 框架(CSS Framework)
- jQuery UI API - 图标(Icons)
- jQuery UI API - 堆叠元素(Stacking Elements)
- jQuery UI API 类别 - UI 核心(UI Core)
- jQuery UI API 类别 - 实用工具(Utilities)
- jQuery UI API - 部件库(Widget Factory)
- jQuery UI API - 插件桥(Widget Plugin Bridge)
- jQuery UI API 类别 - 小部件(Widgets)
- jQuery UI API - 折叠面板部件(Accordion Widget)
- jQuery UI API - 自动完成部件(Autocomplete Widget)
- jQuery UI API - 按钮部件(Button Widget)
- jQuery UI API - 日期选择器部件(Datepicker Widget)
- jQuery UI API - 对话框部件(Dialog Widget)
- jQuery UI API - 菜单部件(Menu Widget)
- jQuery UI API - 进度条部件(Progressbar Widget)
- jQuery UI API - 滑块部件(Slider Widget)
- jQuery UI API - 旋转器部件(Spinner Widget)
- jQuery UI API - 标签页部件(Tabs Widget)
- jQuery UI API - 工具提示框部件(Tooltip Widget)
- jQuery EasyUI 简介
- jQuery EasyUI 应用
- jQuery EasyUI 应用 - 创建 CRUD 应用
- jQuery EasyUI 应用 - 创建 CRUD 数据网格(DataGrid)
- jQuery EasyUI 应用 - 创建展开行明细编辑表单的 CRUD 应用
- jQuery EasyUI 应用 - 创建 RSS Feed 阅读器
- jQuery EasyUI 拖放
- jQuery EasyUI 拖放 - 基本的拖动和放置
- jQuery EasyUI 拖放 - 创建拖放的购物车
- jQuery EasyUI 拖放 - 创建学校课程表
- jQuery EasyUI 菜单与按钮
- jQuery EasyUI 菜单与按钮 - 创建简单的菜单
- jQuery EasyUI 菜单与按钮 - 创建链接按钮(Link Button)
- jQuery EasyUI 菜单与按钮 - 创建菜单按钮(Menu Button)
- jQuery EasyUI 菜单与按钮 - 创建分割按钮(Split Button)
- jQuery EasyUI 布局
- jQuery EasyUI 布局 - 为网页创建边框布局
- jQuery EasyUI 布局 - 在面板中创建复杂布局
- jQuery EasyUI 布局 - 创建折叠面板
- jQuery EasyUI 布局 - 创建标签页(Tabs)
- jQuery EasyUI 布局 - 动态添加标签页(Tabs)
- jQuery EasyUI 布局 - 添加自动播放标签页(Tabs)
- jQuery EasyUI 布局 - 创建 XP 风格左侧面板
- jQuery EasyUI 数据网格
- jQuery EasyUI 数据网格 - 转换 HTML 表格为数据网格
- jQuery EasyUI 数据网格 - 取得选中行数据
- jQuery EasyUI 数据网格 - 添加查询功能
- jQuery EasyUI 数据网格 - 添加工具栏
- jQuery EasyUI 数据网格 - 创建复杂工具栏
- jQuery EasyUI 数据网格 - 设置冻结列
- jQuery EasyUI 数据网格 - 动态改变列
- jQuery EasyUI 数据网格 - 格式化列
- jQuery EasyUI 数据网格 - 设置排序
- jQuery EasyUI 数据网格 - 自定义排序
- jQuery EasyUI 数据网格 - 创建列组合
- jQuery EasyUI 数据网格 - 添加复选框
- jQuery EasyUI 数据网格 - 自定义分页
- jQuery EasyUI 数据网格 - 启用行内编辑
- jQuery EasyUI 数据网格 - 扩展编辑器
- jQuery EasyUI 数据网格 - 列运算
- jQuery EasyUI 数据网格 - 合并单元格
- jQuery EasyUI 数据网格 - 创建自定义视图
- jQuery EasyUI 数据网格 - 创建页脚摘要
- jQuery EasyUI 数据网格 - 条件设置行背景颜色
- jQuery EasyUI 数据网格 - 创建属性网格
- jQuery EasyUI 数据网格 - 扩展行显示细节
- jQuery EasyUI 数据网格 - 创建子网格
- jQuery EasyUI 数据网格 - 使用虚拟滚动视图显示海量数据
- jQuery EasyUI 数据网格 - 添加分页组件
- jQuery EasyUI 窗口
- jQuery EasyUI 窗口 - 创建简单窗口
- jQuery EasyUI 窗口 - 自定义窗口工具栏
- jQuery EasyUI 窗口 - 窗口与布局
- jQuery EasyUI 窗口 - 创建对话框
- jQuery EasyUI 窗口 - 自定义带有工具条和按钮的对话框
- jQuery EasyUI 树形菜单
- jQuery EasyUI 树形菜单 - 使用标记创建树形菜单
- jQuery EasyUI 树形菜单 - 创建异步树形菜单
- jQuery EasyUI 树形菜单 - 树形菜单添加节点
- jQuery EasyUI 树形菜单 - 创建带复选框的树形菜单
- jQuery EasyUI 树形菜单 - 树形菜单拖放控制
- jQuery EasyUI 树形菜单 - 树形菜单加载父/子节点
- jQuery EasyUI 树形菜单 - 创建基础树形网格
- jQuery EasyUI 树形菜单 - 创建复杂树形网格
- jQuery EasyUI 树形菜单 - 树形网格动态加载
- jQuery EasyUI 树形菜单 - 树形网格添加分页
- jQuery EasyUI 树形菜单 - 树形网格惰性加载节点
- jQuery EasyUI 表单
- jQuery EasyUI 表单 - 创建异步提交表单
- jQuery EasyUI 表单 - 表单验证
- jQuery EasyUI 表单 - 创建树形下拉框
- jQuery EasyUI 表单 - 格式化下拉框
- jQuery EasyUI 表单 - 过滤下拉数据网格
- jQuery EasyUI 插件
- jQuery EasyUI 扩展
- 免责声明