# 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>
```
- 索引
- Effects
- .addClass()
- Blind Effect
- Bounce Effect
- Clip Effect
- Color Animation
- Drop Effect
- Easings
- .effect()
- Explode Effect
- Fade Effect
- Fold Effect
- .hide()
- Highlight Effect
- Puff Effect
- Pulsate Effect
- .removeClass()
- Scale Effect
- Shake Effect
- .show()
- Size Effect
- Slide Effect
- .switchClass()
- .toggle()
- .toggleClass()
- Transfer Effect
- Effect Core
- .addClass()
- Color Animation
- .effect()
- .hide()
- .removeClass()
- .show()
- .switchClass()
- .toggle()
- .toggleClass()
- Interactions
- Draggable Widget
- Droppable Widget
- Mouse Interaction
- Resizable Widget
- Resizable Widget
- Selectable Widget
- Sortable Widget
- Method Overrides
- .addClass()
- .focus()
- .hide()
- .position()
- .removeClass()
- .show()
- .toggle()
- .toggleClass()
- Methods
- .disableSelection()
- .effect()
- .enableSelection()
- .focus()
- .hide()
- .position()
- .removeUniqueId()
- .scrollParent()
- .show()
- .toggle()
- .uniqueId()
- .zIndex()
- Selectors
- :data() Selector
- :focusable Selector
- :tabbable Selector
- Theming
- CSS 框架(CSS Framework)
- Icons
- Stacking Elements
- UI Core
- :data() Selector
- .disableSelection()
- .enableSelection()
- .focus()
- :focusable Selector
- .removeUniqueId()
- .scrollParent()
- :tabbable Selector
- .uniqueId()
- .zIndex()
- Utilities
- Easings
- Widget Factory
- Widget Plugin Bridge
- Mouse Interaction
- .position()
- Widgets
- Accordion Widget
- Autocomplete Widget
- Button Widget
- Datepicker Widget
- Dialog Widget
- Menu Widget
- Progressbar Widget
- Slider Widget
- Spinner Widget
- Tabs Widget
- Tooltip Widget