jQuery UI API - 按钮部件(Button Widget)
所属类别
用法
描述:可主题化的按钮和按钮集合。
版本新增:1.8
按钮部件(Button Widget)加强了标准表单元素的功能,比如按钮(button)、输入(input)、锚(anchor),用适当的悬停(hover)和激活(active)样式来主题化按钮。
除了基本的按钮,单选按钮和复选框(input 类型为 radio 和 checkbox)也可以转换为按钮。相关的标签(label)设计成按钮的样式,点击时更新底层的输入。为了能正常工作,需要给 input 一个 id
属性,并指向标签(label)的 for
属性。不要把 input 放在标签(label)内,否则会引起可访问性问题。
为了分组单选按钮,Button 也提供了一个额外的小部件,名为 Buttonset。Buttonset 通过选择一个容器元素(包含单选按钮)并调用 .buttonset()
来使用。Buttonset 也提供了可视化分组,因此当有一组按钮时都可考虑使用它。它会选择所有的后代,并对它们应用 .button()
。您可以启用和禁用一个按钮集,这将会启用和禁用所有包含的按钮。销毁按钮集会调用每个按钮的 destroy
方法。对于分组的单选按钮和复选框按钮,推荐使用带有 legend
的 fieldset
来提供一个可访问的分组标签。
当使用一个类型为 button、submit 或 reset 的 input 时,仅限于支持纯文本无图标标签。
主题化
按钮部件(Button Widget)使用 jQuery UI CSS 框架 来定义它的外观和感观的样式。如果需要使用按钮指定的样式,则可以使用下面的 CSS class 名称:
ui-button
:表示按钮的 DOM 元素。该元素会根据 text 和 icons 选项添加下列 class 之一:ui-button-text-only
、ui-button-icon-only
、ui-button-icons-only
、ui-button-text-icons
。ui-buttonset
:Buttonset 的外层容器。
依赖
附加说明
- 该部件要求一些功能性的 CSS,否则将无法工作。如果您创建了一个自定义的主题,请使用小部件指定的 CSS 文件作为起点。
快速导航
选项 | 方法 | 事件 |
---|---|---|
选项 | 类型 | 描述 | 默认值 |
---|---|---|---|
disabled | Boolean | 如果设置为 true ,则禁用该 button。代码实例: 初始化带有指定 $( ".selector" ).button({ disabled: true }); 在初始化后,获取或设置 // getter var disabled = $( ".selector" ).button( "option", "disabled" ); // setter $( ".selector" ).button( "option", "disabled", true ); |
false |
icons | Object | 要显示的图标,包括带有文本的图标和不带有文本的图标(查看 text 选项)。默认情况下 ,主图标显示在标签文本的左边,副图标显示在右边。显示位置可通过 CSS 进行控制。
代码实例: 初始化带有指定 $( ".selector" ).button({ icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } }); 在初始化后,获取或设置 // 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 内容。代码实例: 初始化带有指定 $( ".selector" ).button({ label: "custom label" }); 在初始化后,获取或设置 // getter var label = $( ".selector" ).button( "option", "label" ); // setter $( ".selector" ).button( "option", "label", "custom label" ); |
null |
text | Boolean | 是否显示标签。当设置为 false 时,不显示文本,但是此时必须启用 icons 选项,否则 text 选项将被忽略。 代码实例: 初始化带有指定 $( ".selector" ).button({ text: false }); 在初始化后,获取或设置 // 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 关联的值。
代码实例: 调用该方法: var isDisabled = $( ".selector" ).button( "option", "disabled" ); |
option() | PlainObject | 获取一个包含键/值对的对象,键/值对表示当前 button 选项哈希。
代码实例: 调用该方法: var options = $( ".selector" ).button( "option" ); |
option( optionName, value ) | jQuery (plugin only) | 设置与指定的 optionName 关联的 button 选项的值。
代码实例: 调用该方法: $( ".selector" ).button( "option", "disabled", true ); |
option( options ) | jQuery (plugin only) | 为 button 设置一个或多个选项。
代码实例: 调用该方法: $( ".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 时触发。
注意: 代码实例: 初始化带有指定 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>其他扩展