Tooltip Widget

Categories: Widgets

version added: 1.9

Description: 可自定义的、可主题化的工具提示框，替代原生的工具提示框。

QuickNavExamples

工具提示框（Tooltip）取代了原生的工具提示框，让它们可主题化，也允许进行各种自定义：

显示不仅仅是标题的其他内容，就如内联的脚注或通过 Ajax 检索的额外内容。
自定义定位，例如，在元素上居中工具提示框。
添加额外的样式来定制警告或错误区域的外观。

默认使用一个渐变的动画来显示和隐藏工具提示框，这种外观与简单的切换可见度相比更具灵性。这可以通过 show 和 hide 选项进行定制。

items 和 content 选项需要保持同步。如果您改变了其中一个，您需要同时改变另一个。

在一般情况下，禁用的元素不会触发任何 DOM 事件。因此，适当地控制禁用元素的工具提示框是不可能的，因为我们需要监听事件来决定何时显示和隐藏工具提示框。这就导致 jQuery UI 不能保证对附加到禁用元素上的工具提示框任何层次上的支持。这意味着如果您需要在禁用元素上进行提示，您可能需要使用一个原生的提示框和 jQuery UI 工具提示框的混合物。

主题（Theming）

工具提示框部件（Tooltip Widget）使用 jQuery UI CSS 框架来定义它的外观和感观的样式。如果需要使用工具提示框指定的样式，则可以使用下面的 CSS class 名称：

ui-tooltip: 工具提示框的外层容器。
- ui-tooltip-content: 工具提示框的内容。

依赖（Dependencies）

UI 核心（UI Core）
部件库（Widget Factory）
定位（Position）
特效核心（Effects Core）（可选的；当与 show 和 hide 选项一起使用时）

其他注意事项（Additional Notes）:

该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。

Options

contentType: Function() or String

Default: function returning the title attribute

tooltip(工具提示框)的内容。

当改变这个选项时，你可能还需要更改 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!" );

disabledType: 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 );

hideType: Boolean or Number or String or Object

Default: truetooltip(工具提示框)关闭（隐藏）时的动画效果。支持多个类型：

Boolean: 当设置为false，将不使用动画效果，该 tooltip(工具提示框) 会立即被隐藏。如果设置为true，该 tooltip(工具提示框) 将会以默认的持续时间和默认的效果淡出。
Number: 该 tooltip(工具提示框) 将以指定的时间和默认的效果淡出。
String: 该 tooltip(工具提示框) 将使用指定的效果被隐藏。该值可以是一个jQuery内置的动画方法的名称，如"slideUp"，或一个 jQuery UI 效果的名称，如"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 } );

itemsType: Selector

Default: [title]

一个选择器表示哪些项目应该显示tooltip(工具提示框)。如果您使用其他的东西自定义，那么title属性将作为tooltip(工具提示框)的内容，或者你需要一个不同的选择来事件委托。

当改变这个选项时，你可能还需要改变的 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]" );

positionType: Object

Default: { my: "left top+15", at: "left bottom", collision: "flipfit" }

确定 tooltip(工具提示框) 相对于相关目标元素的位置。 of选项默认为目标元素，但您可以指定其他元素来定位。有关各个选项的更多细节，你可以参考jQuery UI 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" } );

showType: Boolean or Number or String or Object

Default: truetooltip(工具提示框) 打开（显示）时的动画效果。支持多个类型：

Boolean: 当设置为false，将不使用动画效果，该 tooltip(工具提示框) 会立即被隐藏。如果设置为true，该 tooltip(工具提示框) 将会以默认的持续时间和默认的效果淡出。
Number: 该 tooltip(工具提示框) 将以指定的时间和默认的效果淡出。
String: 该 tooltip(工具提示框) 将使用指定的效果被隐藏。该值可以是一个jQuery内置的动画方法的名称，如"slideUp"，或一个 jQuery UI 效果的名称，如"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 } );

tooltipClassType: String

Default: null一个CSS样式类名添加到tooltip(工具提示框)小部件，可用于显示各种提示类型，像警告或错误。

这可能会被classes option取代。

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" );

trackType: Boolean

Default: falsetooltip(工具提示框)是否应该跟踪（跟随）鼠标。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 (plugin only)

关闭 tooltip(工具提示框) 。这仅供非委派的 tooltip(工具提示框) 调用。

该方法不接受任何参数。

Code examples:

调用 close 方法：

$( ".selector" ).tooltip( "close" );

destroy()Returns: jQuery (plugin only)

完全移除 tooltip(工具提示框) 功能. 这将使元素返回到之前的初始化状态.

该方法不接受任何参数。

Code examples:

调用 destroy 方法：

$( ".selector" ).tooltip( "destroy" );

disable()Returns: jQuery (plugin only)

禁用 tooltip(工具提示框)。

该方法不接受任何参数。

Code examples:

调用 disable 方法：

$( ".selector" ).tooltip( "disable" );

enable()Returns: jQuery (plugin only)

启用 tooltip(工具提示框)。

该方法不接受任何参数。

Code examples:

调用 enable 方法：

$( ".selector" ).tooltip( "enable" );

open()Returns: jQuery (plugin only)

以编程方式打开一个 tooltip(工具提示框) 。这仅供非委派的 tooltip(工具提示框) 调用。

该方法不接受任何参数。

Code examples:

调用 open 方法：

$( ".selector" ).tooltip( "open" );

option( optionName )Returns: Object

获取当前与指定的 optionName 关联的值。

optionNameType: String要获取值的选项的名称。

Code examples:

调用该方法：

var isDisabled = $( ".selector" ).tooltip( "option", "disabled" );

option()Returns: PlainObject

获取一个包含键/值对的对象，键/值对表示当前 tooltip(工具提示框) 选项哈希。

该方法不接受任何参数。

Code examples:

调用该方法：

var options = $( ".selector" ).tooltip( "option" );

option( optionName, value )Returns: jQuery (plugin only)

设置与指定的 optionName 关联的 tooltip(工具提示框) 选项的值。

optionNameType: String要设置的选项的名称。
valueType: Object要为选项设置的值。

Code examples:

调用该方法：

$( ".selector" ).tooltip( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

为 tooltip(工具提示框) 设置一个或多个选项。

optionsType: Object要设置的 option-value 对。

Code examples:

调用该方法：

$( ".selector" ).tooltip( "option", { disabled: true } );

widget()Returns: jQuery

返回一个包含生成包裹元素的 jQuery 对象。

该方法不接受任何参数。

Code examples:

调用 widget 方法：

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

Events

close( event, ui )Type: `tooltipclose`

当 tooltip(工具提示框) 关闭时触发，触发事件为focusout 或 mouseleave。

eventType: Event
uiType: Object
- tooltipType: 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(工具提示框)时触发该事件。

eventType: Event
uiType: 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。

eventType: Event
uiType: Object
- tooltipType: 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>

version added: 1.9

QuickNavExamples

Options

Methods

Events

主题（Theming）

依赖（Dependencies）

其他注意事项（Additional Notes）:

Options

contentType: Function() or String

disabledType: Boolean

hideType: Boolean or Number or String or Object

itemsType: Selector

positionType: Object

showType: Boolean or Number or String or Object

tooltipClassType: String

trackType: Boolean

Methods

close()Returns: jQuery (plugin only)

destroy()Returns: jQuery (plugin only)

disable()Returns: jQuery (plugin only)

enable()Returns: jQuery (plugin only)

open()Returns: jQuery (plugin only)

option( optionName )Returns: Object

option()Returns: PlainObject

option( optionName, value )Returns: jQuery (plugin only)

option( options )Returns: jQuery (plugin only)

widget()Returns: jQuery

Events

close( event, ui )Type: tooltipclose

create( event, ui )Type: tooltipcreate

open( event, ui )Type: tooltipopen

Example:

使用带有 title 属性的所有元素的事件代理，在文档上创建一个工具提示框（Tooltip）。

close( event, ui )Type: `tooltipclose`

create( event, ui )Type: `tooltipcreate`

open( event, ui )Type: `tooltipopen`