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>