Button Widget · jQuery UI API 中文文檔 1.10

# Button Widget Categories: [Widgets](http://www.css88.com/jquery-ui-api/category/widgets/ "View all posts in Widgets") ## version added: 1.8 **Description:** 可主題化的按鈕和按鈕集合。 ## QuickNav[Examples](#entry-examples) ### Options + [disabled](#option-disabled) + [icons](#option-icons) + [label](#option-label) + [text](#option-text) ### Methods + [destroy](#method-destroy) + [disable](#method-disable) + [enable](#method-enable) + [option](#method-option) + [refresh](#method-refresh) + [widget](#method-widget) ### Events + [create](#event-create) 按鈕部件（Button Widget）加強了標準表單元素的功能，比如按鈕（button）、輸入（input）、錨（anchor），用適當的懸停（hover）和激活（active）樣式來主題化按鈕。除了基本的按鈕，單選按鈕和復選框（input 類型為 radio 和 checkbox）也可以轉換為按鈕。相關的標簽（label）設計成按鈕的樣式，點擊時更新底層的輸入。為了能正常工作，需要給 input 一個 `id` 屬性，并指向標簽（label）的 `for` 屬性。不要把 input 放在標簽（label）內，否則會[引起可訪問性問題](//www.paciellogroup.com/blog/2011/07/html5-accessibility-chops-form-control-labeling/)。為了分組單選按鈕，Button 也提供了一個額外的小部件，名為 Buttonset。Buttonset 通過選擇一個容器元素（包含單選按鈕）并調用 `.buttonset()` 來使用。Buttonset 也提供了可視化分組，因此當有一組按鈕時都可考慮使用它。它會選擇所有的后代，并對它們應用 `.button()`。您可以啟用和禁用一個按鈕集，這將會啟用和禁用所有包含的按鈕。銷毀按鈕集會調用每個按鈕的 `destroy` 方法。對于分組的單選按鈕和復選框按鈕，推薦使用帶有 `legend` 的 `fieldset` 來提供一個可訪問的分組標簽。當使用一個類型為 button、submit 或 reset 的 input 時，僅限于支持純文本無圖標標簽。 ### 主題按鈕部件（Button Widget）使用 [jQuery UI CSS 框架](/theming/css-framework/) 來定義它的外觀和感觀的樣式。如果需要使用按鈕指定的樣式，則可以使用下面的 CSS class 名稱： * `ui-button`：表示按鈕的 DOM 元素。該元素會根據 [text](#option-text) 和 [icons](#option-icons) 選項添加下列 class 之一：`ui-button-text-only`、`ui-button-icon-only`、`ui-button-icons-only`、`ui-button-text-icons`。 * `ui-button-icon-primary`：用于顯示按鈕主要圖標的元素。只有當主要圖標在 [icons](#option-icons) 選項中提供時才呈現。 * `ui-button-text`：在按鈕的文本內容周圍的容器。 * `ui-button-icon-secondary`：用于顯示按鈕的次要圖標。只有當次要圖標在 [icons](#option-icons) 選項中提供時才呈現。 * `ui-buttonset`：Buttonset 的外層容器。 ### 依賴 * [UI 核心（UI Core）](/category/ui-core/) * [部件庫（Widget Factory）](/jQuery.widget/) ### 其他注意事項： * 該部件要求一些功能性的 CSS，否則將無法工作。如果您創建了一個自定義的主題，請使用小部件指定的 CSS 文件作為起點。 ## Options ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果設置為 `true`，則禁用該 button。**Code examples:** 初始化帶有指定 `disabled` 選項的 button： ``` $( ".selector" ).button({ disabled: true }); ``` 在初始化后，獲取或設置`disabled` 選項： ``` // getter var disabled = $( ".selector" ).button( "option", "disabled" ); // setter $( ".selector" ).button( "option", "disabled", true ); ``` ### icons**Type:** [Object](http://api.jquery.com/Types/#Object) **Default:** `{ primary: null, secondary: null }` 要顯示的圖標，包括帶有文本的圖標和不帶有文本的圖標（查看 [`text`](#option-text) 選項）。默認情況下，主圖標顯示在標簽文本的左邊，副圖標顯示在右邊。顯示位置可通過 CSS 進行控制。 `primary` 和 `secondary` 屬性值必須是 [圖標 class 名稱](/theming/icons/)，例如，`"ui-icon-gear"`。如果只使用一個圖標，則 `icons: { primary: "ui-icon-locked" }`。如果使用兩個圖標，則 `icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }`。 **Code examples:** 初始化帶有指定 `icons` 選項的 button： ``` $( ".selector" ).button({ icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } }); ``` 在初始化后，獲取或設置`icons` 選項： ``` // getter var icons = $( ".selector" ).button( "option", "icons" ); // setter $( ".selector" ).button( "option", "icons", { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } ); ``` ### label**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `null`要顯示在按鈕中的文本。當未指定時（`null`），則使用元素的 HTML 內容，或者如果元素是一個 submit 或 reset 類型的 input 元素，則使用它的 `value` 屬性，或者如果元素是一個 radio 或 checkbox 類型的 input 元素，則使用相關的 label 元素的 HTML 內容。**Code examples:** 初始化帶有指定 `label` 選項的 button： ``` $( ".selector" ).button({ label: "custom label" }); ``` 在初始化后，獲取或設置`label` 選項： ``` // getter var label = $( ".selector" ).button( "option", "label" ); // setter $( ".selector" ).button( "option", "label", "custom label" ); ``` ### text**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `true`是否顯示標簽。當設置為 `false` 時，不顯示文本，但是此時必須啟用 [`icons`](#option-icons) 選項，否則 `text` 選項將被忽略。**Code examples:** 初始化帶有指定 `text` 選項的 button： ``` $( ".selector" ).button({ text: false }); ``` 在初始化后，獲取或設置`text` 選項： ``` // getter var text = $( ".selector" ).button( "option", "text" ); // setter $( ".selector" ).button( "option", "text", false ); ``` ## Methods ### destroy()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 完全移除 button 功能。這會把元素返回到它的預初始化狀態。 * 該方法不接受任何參數。 **Code examples:** 調用 destroy 方法： ``` $( ".selector" ).button( "destroy" ); ``` ### disable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 禁用 button。 * 該方法不接受任何參數。 **Code examples:** 調用 disable 方法： ``` $( ".selector" ).button( "disable" ); ``` ### enable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 啟用 button。 * 該方法不接受任何參數。 **Code examples:** 調用 enable 方法： ``` $( ".selector" ).button( "enable" ); ``` ### option( optionName )Returns: [Object](http://api.jquery.com/Types/#Object) 獲取當前與指定的 `optionName` 關聯的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要獲取值的選項的名稱。 **Code examples:** 調用該方法： ``` var isDisabled = $( ".selector" ).button( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個包含鍵/值對的對象，鍵/值對表示當前 button 選項哈希。 * 該方法不接受任何參數。 **Code examples:** 調用該方法： ``` var options = $( ".selector" ).button( "option" ); ``` ### option( optionName, value )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 設置與指定的 `optionName` 關聯的 button 選項的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置的選項的名稱。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)要為選項設置的值。 **Code examples:** 調用該方法： ``` $( ".selector" ).button( "option", "disabled", true ); ``` ### option( options )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 為 button 設置一個或多個選項。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要設置的 option-value 對。 **Code examples:** 調用該方法： ``` $( ".selector" ).button( "option", { disabled: true } ); ``` ### refresh()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 刷新按鈕的視覺狀態。用于在以編程方式改變原生元素的選中狀態或禁用狀態后更新按鈕狀態。 * 該方法不接受任何參數。 **Code examples:** 調用 refresh 方法： ``` $( ".selector" ).button( "refresh" ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個包含 button 的 `jQuery` 對象。 * 該方法不接受任何參數。 **Code examples:** 調用 widget 方法： ``` var widget = $( ".selector" ).button( "widget" ); ``` ## Events ### create( event, ui )Type: `buttoncreate` 當創建按鈕 button 時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。_ **Code examples:** 初始化帶有指定 create 回調的button ``` $( ".selector" ).button({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 buttoncreate 事件： ``` $( ".selector" ).on( "buttoncreate", function( event, ui ) {} ); ``` ## Examples: #### Example: 一個簡單的 jQuery UI 按鈕（Button）。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>button demo</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 label</button> <script> $( "button" ).button(); </script> </body> </html> ``` #### Example: 一個簡單的 jQuery UI 按鈕集（Buttonset）。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>button demo</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>Favorite jQuery Project</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> ```