# 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