Tooltip Widget · jQuery UI API 中文文檔 1.10

# Tooltip Widget Categories: [Widgets](http://www.css88.com/jquery-ui-api/category/widgets/ "View all posts in Widgets") ## version added: 1.9 **Description:** 可自定義的、可主題化的工具提示框，替代原生的工具提示框。 ## QuickNav[Examples](#entry-examples) ### Options + [content](#option-content) + [disabled](#option-disabled) + [hide](#option-hide) + [items](#option-items) + [position](#option-position) + [show](#option-show) + [tooltipClass](#option-tooltipClass) + [track](#option-track) ### Methods + [close](#method-close) + [destroy](#method-destroy) + [disable](#method-disable) + [enable](#method-enable) + [open](#method-open) + [option](#method-option) + [widget](#method-widget) ### Events + [close](#event-close) + [create](#event-create) + [open](#event-open) 工具提示框（Tooltip）取代了原生的工具提示框，讓它們可主題化，也允許進行各種自定義： * 顯示不僅僅是標題的其他內容，就如內聯的腳注或通過 Ajax 檢索的額外內容。 * 自定義定位，例如，在元素上居中工具提示框。 * 添加額外的樣式來定制警告或錯誤區域的外觀。默認使用一個漸變的動畫來顯示和隱藏工具提示框，這種外觀與簡單的切換可見度相比更具靈性。這可以通過 [`show`](#option-show) 和 [`hide`](#option-hide) 選項進行定制。 + [`items`](#option-items) 和 [`content`](#option-content) 選項需要保持同步。如果您改變了其中一個，您需要同時改變另一個。在一般情況下，禁用的元素不會觸發任何 DOM 事件。因此，適當地控制禁用元素的工具提示框是不可能的，因為我們需要監聽事件來決定何時顯示和隱藏工具提示框。這就導致 jQuery UI 不能保證對附加到禁用元素上的工具提示框任何層次上的支持。這意味著如果您需要在禁用元素上進行提示，您可能需要使用一個原生的提示框和 jQuery UI 工具提示框的混合物。 ### 主題（Theming）工具提示框部件（Tooltip Widget）使用 [jQuery UI CSS 框架](/theming/css-framework/) 來定義它的外觀和感觀的樣式。如果需要使用工具提示框指定的樣式，則可以使用下面的 CSS class 名稱： * `ui-tooltip`: 工具提示框的外層容器。 * `ui-tooltip-content`: 工具提示框的內容。 ### 依賴（Dependencies） * [UI 核心（UI Core）](/category/ui-core/) * [部件庫（Widget Factory）](/jQuery.widget/) * [定位（Position）](/position/) * [特效核心（Effects Core）](/category/effects-core/)（可選的；當與 [`show`](#option-show) 和 [`hide`](#option-hide) 選項一起使用時） ### 其他注意事項（Additional Notes）: * 該部件要求一些功能性的 CSS，否則將無法工作。如果您創建了一個自定義的主題，請使用小部件指定的 CSS 文件作為起點。 ## Options ### content**Type:** [Function](http://api.jquery.com/Types/#Function)() or [String](http://api.jquery.com/Types/#String) **Default:** `function returning the title attribute` tooltip(工具提示框)的內容。 _當改變這個選項時，你可能還需要更改 [`items`](#option-items)選項。_ **支持多個類型：** * **Function**: 一個回調可以是直接返回的內容，或通過在內容，調用第一個參數，例如，對于Ajax內容。 * **String**: 一個HTML字符串作為tooltip(工具提示框)的內容。 **Code examples:** 初始化帶有指定 `content` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ content: "Awesome title!" }); ``` 在初始化后，獲取或設置`content` 選項： ``` // getter var content = $( ".selector" ).tooltip( "option", "content" ); // setter $( ".selector" ).tooltip( "option", "content", "Awesome title!" ); ``` ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果設置為 `true`，則禁用該 tooltip（工具提示框）。**Code examples:** 初始化帶有指定 `disabled` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ disabled: true }); ``` 在初始化后，獲取或設置`disabled` 選項： ``` // getter var disabled = $( ".selector" ).tooltip( "option", "disabled" ); // setter $( ".selector" ).tooltip( "option", "disabled", true ); ``` ### hide**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) or [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String) or [Object](http://api.jquery.com/Types/#Object) **Default:** `true`tooltip(工具提示框)關閉（隱藏）時的動畫效果。**支持多個類型：** * **Boolean**: 當設置為`false`，將不使用動畫效果，該 tooltip(工具提示框) 會立即被隱藏。如果設置為`true`，該 tooltip(工具提示框) 將會以默認的持續時間和默認的效果淡出。 * **Number**: 該 tooltip(工具提示框) 將以指定的時間和默認的效果淡出。 * **String**: 該 tooltip(工具提示框) 將使用指定的效果被隱藏。該值可以是一個jQuery內置的動畫方法的名稱，如`"slideUp"`，或一個 [jQuery UI 效果](/category/effects/)的名稱，如`"fold"`。在這兩種情況下，將使用默認持續時間和默認的動畫效果。 * **Object**: 如果該值是一個對象，那么 `effect`, `delay`, `duration`, 和`easing`可能要提供。 ?如果 `effect` 屬性包含一個jQuery方法的名稱，那么該方法將被使用; 否則它被假定為是一個jQuery UI的效果的名稱。當使用jQuery UI 支持額外設置的效果，你可以在對象中包含那些設置并且它們將被傳遞到的效果。如果`duration`持續時間或`easing`屬性被省略，那么默認值將被使用。如果`effect`被省略，那么`"fadeOut"` 將被使用。如果`delay`被省略，那么將不使用延遲。 **Code examples:** 初始化帶有指定 `hide` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ hide: { effect: "explode", duration: 1000 } }); ``` 在初始化后，獲取或設置`hide` 選項： ``` // getter var hide = $( ".selector" ).tooltip( "option", "hide" ); // setter $( ".selector" ).tooltip( "option", "hide", { effect: "explode", duration: 1000 } ); ``` ### items**Type:** [Selector](http://api.jquery.com/Types/#Selector) **Default:** `[title]` 一個選擇器表示哪些項目應該顯示tooltip(工具提示框)。如果您使用其他的東西自定義，那么title屬性將作為tooltip(工具提示框)的內容，或者你需要一個不同的選擇來事件委托。 _當改變這個選項時，你可能還需要改變的 [`content`](#option-content) 選項。_ **Code examples:** 初始化帶有指定 `items` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ items: "img[alt]" }); ``` 在初始化后，獲取或設置`items` 選項： ``` // getter var items = $( ".selector" ).tooltip( "option", "items" ); // setter $( ".selector" ).tooltip( "option", "items", "img[alt]" ); ``` ### position**Type:** [Object](http://api.jquery.com/Types/#Object) **Default:** `{ my: "left top+15", at: "left bottom", collision: "flipfit" }` 確定 tooltip(工具提示框) 相對于相關目標元素的位置。 `of`選項默認為目標元素，但您可以指定其他元素來定位。有關各個選項的更多細節，你可以參考[jQuery UI Position](/position/)實用工具。 **Code examples:** 初始化帶有指定 `position` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ position: { my: "left+15 center", at: "right center" } }); ``` 在初始化后，獲取或設置`position` 選項： ``` // getter var position = $( ".selector" ).tooltip( "option", "position" ); // setter $( ".selector" ).tooltip( "option", "position", { my: "left+15 center", at: "right center" } ); ``` ### show**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) or [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String) or [Object](http://api.jquery.com/Types/#Object) **Default:** `true`tooltip(工具提示框) 打開（顯示）時的動畫效果。**支持多個類型：** * **Boolean**: 當設置為`false`，將不使用動畫效果，該 tooltip(工具提示框) 會立即被隱藏。如果設置為`true`，該 tooltip(工具提示框) 將會以默認的持續時間和默認的效果淡出。 * **Number**: 該 tooltip(工具提示框) 將以指定的時間和默認的效果淡出。 * **String**: 該 tooltip(工具提示框) 將使用指定的效果被隱藏。該值可以是一個jQuery內置的動畫方法的名稱，如`"slideUp"`，或一個 [jQuery UI 效果](/category/effects/)的名稱，如`"fold"`。在這兩種情況下，將使用默認持續時間和默認的動畫效果。 * **Object**: 如果該值是一個對象，那么 `effect`, `delay`, `duration`, 和`easing`可能要提供。 ?如果 `effect` 屬性包含一個jQuery方法的名稱，那么該方法將被使用; 否則它被假定為是一個jQuery UI的效果的名稱。當使用jQuery UI 支持額外設置的效果，你可以在對象中包含那些設置并且它們將被傳遞到的效果。如果`duration`持續時間或`easing`屬性被省略，那么默認值將被使用。如果`effect`被省略，那么`"fadeOut"` 將被使用。如果`delay`被省略，那么將不使用延遲。 **Code examples:** 初始化帶有指定 `show` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ show: { effect: "blind", duration: 800 } }); ``` 在初始化后，獲取或設置`show` 選項： ``` // getter var show = $( ".selector" ).tooltip( "option", "show" ); // setter $( ".selector" ).tooltip( "option", "show", { effect: "blind", duration: 800 } ); ``` ### tooltipClass**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `null`一個CSS樣式類名添加到tooltip(工具提示框)小部件，可用于顯示各種提示類型，像警告或錯誤。這可能會被[classes option](http://bugs.jqueryui.com/ticket/7053)取代。 **Code examples:** 初始化帶有指定 `tooltipClass` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ tooltipClass: "custom-tooltip-styling" }); ``` 在初始化后，獲取或設置`tooltipClass` 選項： ``` // getter var tooltipClass = $( ".selector" ).tooltip( "option", "tooltipClass" ); // setter $( ".selector" ).tooltip( "option", "tooltipClass", "custom-tooltip-styling" ); ``` ### track**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`tooltip(工具提示框)是否應該跟蹤（跟隨）鼠標。**Code examples:** 初始化帶有指定 `track` 選項的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ track: true }); ``` 在初始化后，獲取或設置`track` 選項： ``` // getter var track = $( ".selector" ).tooltip( "option", "track" ); // setter $( ".selector" ).tooltip( "option", "track", true ); ``` ## Methods ### close()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 關閉 tooltip(工具提示框) 。這僅供非委派的 tooltip(工具提示框) 調用。 * 該方法不接受任何參數。 **Code examples:** 調用 close 方法： ``` $( ".selector" ).tooltip( "close" ); ``` ### destroy()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 完全移除 tooltip(工具提示框) 功能. 這將使元素返回到之前的初始化狀態. * 該方法不接受任何參數。 **Code examples:** 調用 destroy 方法： ``` $( ".selector" ).tooltip( "destroy" ); ``` ### disable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 禁用 tooltip(工具提示框)。 * 該方法不接受任何參數。 **Code examples:** 調用 disable 方法： ``` $( ".selector" ).tooltip( "disable" ); ``` ### enable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 啟用 tooltip(工具提示框)。 * 該方法不接受任何參數。 **Code examples:** 調用 enable 方法： ``` $( ".selector" ).tooltip( "enable" ); ``` ### open()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 以編程方式打開一個 tooltip(工具提示框) 。這僅供非委派的 tooltip(工具提示框) 調用。 * 該方法不接受任何參數。 **Code examples:** 調用 open 方法： ``` $( ".selector" ).tooltip( "open" ); ``` ### 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" ).tooltip( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個包含鍵/值對的對象，鍵/值對表示當前 tooltip(工具提示框) 選項哈希。 * 該方法不接受任何參數。 **Code examples:** 調用該方法： ``` var options = $( ".selector" ).tooltip( "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` 關聯的 tooltip(工具提示框) 選項的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置的選項的名稱。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)要為選項設置的值。 **Code examples:** 調用該方法： ``` $( ".selector" ).tooltip( "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/)) 為 tooltip(工具提示框) 設置一個或多個選項。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要設置的 option-value 對。 **Code examples:** 調用該方法： ``` $( ".selector" ).tooltip( "option", { disabled: true } ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個包含生成包裹元素的 `jQuery` 對象。 * 該方法不接受任何參數。 **Code examples:** 調用 widget 方法： ``` var widget = $( ".selector" ).tooltip( "widget" ); ``` ## Events ### close( event, ui )Type: `tooltipclose` 當 tooltip(工具提示框) 關閉時觸發，觸發事件為`focusout` 或 `mouseleave`。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **tooltip**Type: [jQuery](http://api.jquery.com/Types/#jQuery)生成tooltip(工具提示框) 的元素。 **Code examples:** 初始化帶有指定 close 回調的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ close: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 tooltipclose 事件： ``` $( ".selector" ).on( "tooltipclose", function( event, ui ) {} ); ``` ### create( event, ui )Type: `tooltipcreate` 在創建tooltip(工具提示框)時觸發該事件。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。_ **Code examples:** 初始化帶有指定 create 回調的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 tooltipcreate 事件： ``` $( ".selector" ).on( "tooltipcreate", function( event, ui ) {} ); ``` ### open( event, ui )Type: `tooltipopen` 當tooltip(工具提示框)打開，顯示時，觸發此事件，觸發的事件為`focusin` 或 `mouseover`。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **tooltip**Type: [jQuery](http://api.jquery.com/Types/#jQuery)生成tooltip(工具提示框) 的元素。 **Code examples:** 初始化帶有指定 open 回調的 tooltip(工具提示框)： ``` $( ".selector" ).tooltip({ open: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 tooltipopen 事件： ``` $( ".selector" ).on( "tooltipopen", function( event, ui ) {} ); ``` ## Example: #### 使用帶有 title 屬性的所有元素的事件代理，在文檔上創建一個工具提示框（Tooltip）。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>tooltip 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> <p> <a href="#" title="Anchor description">Anchor text</a> <input title="Input help"> </p> <script> $( document ).tooltip(); </script> </body> </html> ```