jQuery UI API - 按鈕部件(Button Widget)

所屬類別

小部件(Widgets)

用法

描述:可主題化的按鈕和按鈕集合。

版本新增:1.8

按鈕部件(Button Widget)加強(qiáng)了標(biāo)準(zhǔn)表單元素的功能,比如按鈕(button)、輸入(input)、錨(anchor),用適當(dāng)?shù)膽彝#╤over)和激活(active)樣式來主題化按鈕。

除了基本的按鈕,單選按鈕和復(fù)選框(input 類型為 radio 和 checkbox)也可以轉(zhuǎn)換為按鈕。相關(guān)的標(biāo)簽(label)設(shè)計成按鈕的樣式,點(diǎn)擊時更新底層的輸入。為了能正常工作,需要給 input 一個 id 屬性,并指向標(biāo)簽(label)的 for 屬性。不要把 input 放在標(biāo)簽(label)內(nèi),否則會引起可訪問性問題。

為了分組單選按鈕,Button 也提供了一個額外的小部件,名為 Buttonset。Buttonset 通過選擇一個容器元素(包含單選按鈕)并調(diào)用 .buttonset() 來使用。Buttonset 也提供了可視化分組,因此當(dāng)有一組按鈕時都可考慮使用它。它會選擇所有的后代,并對它們應(yīng)用 .button()。您可以啟用和禁用一個按鈕集,這將會啟用和禁用所有包含的按鈕。銷毀按鈕集會調(diào)用每個按鈕的 destroy 方法。對于分組的單選按鈕和復(fù)選框按鈕,推薦使用帶有 legendfieldset 來提供一個可訪問的分組標(biāo)簽。

當(dāng)使用一個類型為 button、submit 或 reset 的 input 時,僅限于支持純文本無圖標(biāo)標(biāo)簽。

主題化

按鈕部件(Button Widget)使用 jQuery UI CSS 框架 來定義它的外觀和感觀的樣式。如果需要使用按鈕指定的樣式,則可以使用下面的 CSS class 名稱:

  • ui-button:表示按鈕的 DOM 元素。該元素會根據(jù) texticons 選項(xiàng)添加下列 class 之一:ui-button-text-only、ui-button-icon-only、ui-button-icons-onlyui-button-text-icons。
    • ui-button-icon-primary:用于顯示按鈕主要圖標(biāo)的元素。只有當(dāng)主要圖標(biāo)在 icons 選項(xiàng)中提供時才呈現(xiàn)。
    • ui-button-text:在按鈕的文本內(nèi)容周圍的容器。
    • ui-button-icon-secondary:用于顯示按鈕的次要圖標(biāo)。只有當(dāng)次要圖標(biāo)在 icons 選項(xiàng)中提供時才呈現(xiàn)。
  • ui-buttonset:Buttonset 的外層容器。

依賴

附加說明

  • 該部件要求一些功能性的 CSS,否則將無法工作。如果您創(chuàng)建了一個自定義的主題,請使用小部件指定的 CSS 文件作為起點(diǎn)。

快速導(dǎo)航

選項(xiàng) 方法 事件

選項(xiàng) 類型 描述 默認(rèn)值
disabled Boolean 如果設(shè)置為 true,則禁用該 button。

代碼實(shí)例:

初始化帶有指定 disabled 選項(xiàng)的 button:

$( ".selector" ).button({ disabled: true });
	

在初始化后,獲取或設(shè)置 disabled 選項(xiàng):

// getter
var disabled = $( ".selector" ).button( "option", "disabled" );
 
// setter
$( ".selector" ).button( "option", "disabled", true );
	
false
icons Object 要顯示的圖標(biāo),包括帶有文本的圖標(biāo)和不帶有文本的圖標(biāo)(查看 text 選項(xiàng))。默認(rèn)情況下 ,主圖標(biāo)顯示在標(biāo)簽文本的左邊,副圖標(biāo)顯示在右邊。顯示位置可通過 CSS 進(jìn)行控制。

primarysecondary 屬性值必須是 圖標(biāo) class 名稱,例如,"ui-icon-gear"。如果只使用一個圖標(biāo),則 icons: { primary: "ui-icon-locked" }。如果使用兩個圖標(biāo),則 icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }。

代碼實(shí)例:

初始化帶有指定 icons 選項(xiàng)的 button:

$( ".selector" ).button({ icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } });
	

在初始化后,獲取或設(shè)置 disabled 選項(xiàng):

// 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 要顯示在按鈕中的文本。當(dāng)未指定時(null),則使用元素的 HTML 內(nèi)容,或者如果元素是一個 submit 或 reset 類型的 input 元素,則使用它的 value 屬性,或者如果元素是一個 radio 或 checkbox 類型的 input 元素,則使用相關(guān)的 label 元素的 HTML 內(nèi)容。

代碼實(shí)例:

初始化帶有指定 label 選項(xiàng)的 button:

$( ".selector" ).button({ label: "custom label" });
	

在初始化后,獲取或設(shè)置 label 選項(xiàng):

// getter
var label = $( ".selector" ).button( "option", "label" );
 
// setter
$( ".selector" ).button( "option", "label", "custom label" );
	
null
text Boolean 是否顯示標(biāo)簽。當(dāng)設(shè)置為 false 時,不顯示文本,但是此時必須啟用 icons 選項(xiàng),否則 text 選項(xiàng)將被忽略。

代碼實(shí)例:

初始化帶有指定 text 選項(xiàng)的 button:

$( ".selector" ).button({ text: false });
	

在初始化后,獲取或設(shè)置 text 選項(xiàng):

// getter
var text = $( ".selector" ).button( "option", "text" );
 
// setter
$( ".selector" ).button( "option", "text", false );
	
true

方法 返回 描述
destroy() jQuery (plugin only) 完全移除 button 功能。這會把元素返回到它的預(yù)初始化狀態(tài)。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例:

調(diào)用 destroy 方法:

$( ".selector" ).button( "destroy" );
	
disable() jQuery (plugin only) 禁用 button。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例:

調(diào)用 disable 方法:

$( ".selector" ).button( "disable" );
	
enable() jQuery (plugin only) 啟用 button。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例:

調(diào)用 enable 方法:

$( ".selector" ).button( "enable" );
	
option( optionName ) Object 獲取當(dāng)前與指定的 optionName 關(guān)聯(lián)的值。
  • optionName
    類型:String
    描述:要獲取的選項(xiàng)的名稱。

代碼實(shí)例:

調(diào)用該方法:

var isDisabled = $( ".selector" ).button( "option", "disabled" );
	
option() PlainObject 獲取一個包含鍵/值對的對象,鍵/值對表示當(dāng)前 button 選項(xiàng)哈希。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例:

調(diào)用該方法:

var options = $( ".selector" ).button( "option" );
	
option( optionName, value ) jQuery (plugin only) 設(shè)置與指定的 optionName 關(guān)聯(lián)的 button 選項(xiàng)的值。
  • optionName
    類型:String
    描述:要設(shè)置的選項(xiàng)的名稱。
  • value
    類型:Object
    描述:要為選項(xiàng)設(shè)置的值。

代碼實(shí)例:

調(diào)用該方法:

$( ".selector" ).button( "option", "disabled", true );
	
option( options ) jQuery (plugin only) 為 button 設(shè)置一個或多個選項(xiàng)。
  • options
    類型:Object
    描述:要設(shè)置的 option-value 對。

代碼實(shí)例:

調(diào)用該方法:

$( ".selector" ).button( "option", { disabled: true } );
	
refresh() jQuery (plugin only) 刷新按鈕的視覺狀態(tài)。用于在以編程方式改變原生元素的選中狀態(tài)或禁用狀態(tài)后更新按鈕狀態(tài)。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例:

調(diào)用 refresh 方法:

$( ".selector" ).button( "refresh" );
	
widget() jQuery 返回一個包含 button 的 jQuery 對象。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例:

調(diào)用 widget 方法:

var widget = $( ".selector" ).button( "widget" );
	

事件 類型 描述
create( event, ui ) buttoncreate 當(dāng)創(chuàng)建按鈕 button 時觸發(fā)。
  • event
    類型:Event
  • ui
    類型:Object

注意:ui 對象是空的,這里包含它是為了與其他事件保持一致性。

代碼實(shí)例:

初始化帶有指定 create 回調(diào)的 button:

$( ".selector" ).button({
  create: function( event, ui ) {}
});
	

綁定一個事件監(jiān)聽器到 buttoncreate 事件:

$( ".selector" ).on( "buttoncreate", function( event, ui ) {} );
	

實(shí)例

實(shí)例 1:

一個簡單的 jQuery UI 按鈕(Button)。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>按鈕部件(Button Widget)演示</title>
  <link rel="stylesheet"  rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank" >
  <script src="http://code.jquery.com/jquery-1.10.2.js" rel="external nofollow"  rel="external nofollow" ></script>
  <script src="http://code.jquery.com/ui/1.10.4/jquery-ui.js" rel="external nofollow"  rel="external nofollow" ></script>
</head>
<body>
 
<button>按鈕標(biāo)簽</button>
 
<script>
$( "button" ).button();
</script>
 
</body>
</html>

查看演示

實(shí)例 2:

一個簡單的 jQuery UI 按鈕集(Buttonset)。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>按鈕部件(Button Widget)演示</title>
  <link rel="stylesheet"  rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank" >
  <script src="http://code.jquery.com/jquery-1.10.2.js" rel="external nofollow"  rel="external nofollow" ></script>
  <script src="http://code.jquery.com/ui/1.10.4/jquery-ui.js" rel="external nofollow"  rel="external nofollow" ></script>
</head>
<body>
 
<form>
  <fieldset>
    <legend>最喜歡的 jQuery 項(xiàng)目</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>

查看演示