jQuery UI API - 按钮部件（Button Widget）

所属类别

小部件（Widgets）

用法

描述：可主题化的按钮和按钮集合。

版本新增：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-button-icon-primary：用于显示按钮主要图标的元素。只有当主要图标在 icons 选项中提供时才呈现。
    • ui-button-text：在按钮的文本内容周围的容器。
    • ui-button-icon-secondary：用于显示按钮的次要图标。只有当次要图标在 icons 选项中提供时才呈现。
  • ui-buttonset：Buttonset 的外层容器。

依赖

附加说明

  • 该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。

快速导航

选项 方法 事件

选项 类型 描述 默认值
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 选项）。默认情况下 ，主图标显示在标签文本的左边，副图标显示在右边。显示位置可通过 CSS 进行控制。

primary 和 secondary 属性值必须是 图标 class 名称，例如，"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 选项，否则 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>