Latest web development tutorials

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>