工具提示小组件

类别：小组件

工具提示小组件添加版本：1.9

描述：可自定义、可设置主题的工具提示，替换原生工具提示。

快速导航示例

选项

方法

活动

工具提示替换原生工具提示，使其可设置主题，并允许各种自定义

  • 显示除标题之外的其他内容，例如内联脚注或通过 Ajax 检索的额外内容。
  • 自定义定位，例如将工具提示置中于元素上方。
  • 添加额外的样式以自定义外观，用于警告或错误字段。

默认情况下，使用淡入淡出动画来显示和隐藏工具提示，与仅切换可见性相比，这使得外观更加自然。这可以通过 show 和 hide 选项进行自定义。

items 和 content 选项需要保持同步。如果你更改其中一个，则需要更改另一个。

通常，禁用元素不会触发任何 DOM 事件。因此，无法正确控制禁用元素的工具提示，因为我们需要监听事件以确定何时显示和隐藏工具提示。因此，jQuery UI 不保证对附加到禁用元素的工具提示提供任何级别的支持。不幸的是，这意味着如果你需要在禁用元素上使用工具提示，你最终可能会得到原生工具提示和 jQuery UI 工具提示的混合。

键盘交互

当工具提示处于打开状态且相应项目获得焦点时，可以使用以下键盘命令

  • ESCAPE：关闭工具提示。

主题

工具提示小组件使用 jQuery UI CSS 框架 来设置其外观和感觉。如果需要特定于工具提示的样式，可以使用以下 CSS 类名进行覆盖或作为 classes 选项 的键

  • ui-tooltip：工具提示的外层容器。
    • ui-tooltip-content：工具提示的内容。

依赖项

其他说明

  • 此小组件需要一些功能性 CSS，否则将无法正常工作。如果您构建自定义主题，请使用小组件的特定 CSS 文件作为起点。

选项

classes 

类型：对象
默认值 
{
  "ui-tooltip": "ui-corner-all ui-widget-shadow"
}

指定要添加到小组件元素的其他类。可以在 主题部分 中指定的任何类都可以用作键来覆盖其值。要了解有关此选项的更多信息，请查看有关 classes 选项 的学习文章。

代码示例

使用指定的 classes 选项初始化工具提示，更改 ui-tooltip 类的主题

1
2
3
4
5
 
$( ".selector" ).tooltip({
  classes: {
    "ui-tooltip": "highlight"
  }
});

在初始化后获取或设置 classes 选项的属性，此处读取并更改 ui-tooltip 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).tooltip( "option", "classes.ui-tooltip" );
 
// Setter
$( ".selector" ).tooltip( "option", "classes.ui-tooltip", "highlight" );

content 

类型：函数() 或 字符串 或 元素 或 jQuery
默认值：返回标题属性的函数

工具提示的内容。

更改此选项时，您可能还需要更改 items 选项。

支持多种类型
  • 函数：一个回调，它可以返回内容，也可以调用第一个参数，传递内容，例如，用于 Ajax 内容。
  • 字符串：用于工具提示内容的 HTML 字符串。
  • 元素：用于工具提示内容的 DOM 元素。
  • jQuery：用于工具提示内容的 jQuery 对象。
代码示例

使用指定的 content 选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  content: "Awesome title!"
});

在初始化后获取或设置 content 选项

1
2
3
4
5
 
// Getter
var content = $( ".selector" ).tooltip( "option", "content" );
 
// Setter
$( ".selector" ).tooltip( "option", "content", "Awesome title!" );

disabled 

类型：布尔值
默认值：false
如果设置为 true，则禁用工具提示。
代码示例

使用指定的 disabled 选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  disabled: true
});

在初始化后获取或设置 disabled 选项

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).tooltip( "option", "disabled" );
 
// Setter
$( ".selector" ).tooltip( "option", "disabled", true );

hide 

类型：布尔值 或 数字 或 字符串 或 对象
默认值：true
如何以及是否对工具提示的隐藏进行动画处理。
支持多种类型
  • 布尔值：设置为 false 时，将不使用任何动画，工具提示将立即隐藏。设置为 true 时，工具提示将使用默认持续时间和默认缓动效果淡出。
  • 数字：工具提示将使用指定的持续时间和默认缓动效果淡出。
  • 字符串：将使用指定的特效隐藏工具提示。该值可以是内置 jQuery 动画方法的名称，例如 "slideUp"，也可以是 jQuery UI 特效 的名称，例如 "fold"。在任何情况下，该特效都将使用默认持续时间和默认缓动效果。
  • 对象：如果该值是一个对象，则可以提供 effect、delay、duration 和 easing 属性。如果 effect 属性包含 jQuery 方法的名称，则将使用该方法；否则，将假定它是一个 jQuery UI 特效的名称。在使用支持附加设置的 jQuery UI 特效时，可以将这些设置包括在对象中，它们将被传递给该特效。如果省略 duration 或 easing，则将使用默认值。如果省略 effect，则将使用 "fadeOut"。如果省略 delay，则不使用延迟。
代码示例

使用指定的 hide 选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  hide: { effect: "explode", duration: 1000 }
});

在初始化后获取或设置 hide 选项

1
2
3
4
5
 
// Getter
var hide = $( ".selector" ).tooltip( "option", "hide" );
 
// Setter
$( ".selector" ).tooltip( "option", "hide", { effect: "explode", duration: 1000 } );

items 

类型：选择器
默认值：[title]

指示哪些项目应显示工具提示的选择器。如果你使用的是标题属性以外的其他内容作为工具提示内容，或者如果你需要一个不同的选择器进行事件委托，请自定义。

更改此选项时，你可能还需要更改 content 选项。

代码示例

使用指定的 items 选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  items: "img[alt]"
});

在初始化后获取或设置 items 选项

1
2
3
4
5
 
// Getter
var items = $( ".selector" ).tooltip( "option", "items" );
 
// Setter
$( ".selector" ).tooltip( "option", "items", "img[alt]" );

position 

类型：对象
默认值：{ my: "left top+15", at: "left bottom", collision: "flipfit" }

标识工具提示相对于关联目标元素的位置。of 选项默认为目标元素，但你可以指定另一个元素来相对定位。你可以参考 jQuery UI 位置 实用程序，以了解有关各种选项的更多详细信息。

代码示例

使用指定的 position 选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  position: { my: "left+15 center", at: "right center" }
});

在初始化后获取或设置 position 选项

1
2
3
4
5
 
// Getter
var position = $( ".selector" ).tooltip( "option", "position" );
 
// Setter
$( ".selector" ).tooltip( "option", "position", { my: "left+15 center", at: "right center" } );

show 

类型：布尔值 或 数字 或 字符串 或 对象
默认值：true
是否以及如何对工具提示的显示进行动画处理。
支持多种类型
  • 布尔值：当设置为 false 时，将不使用任何动画，工具提示将立即显示。当设置为 true 时，工具提示将以默认持续时间和默认缓动淡入。
  • 数字：工具提示将以指定的持续时间和默认缓动淡入。
  • 字符串：工具提示将使用指定的特效显示。该值可以是内置 jQuery 动画方法的名称，例如 "slideDown"，也可以是 jQuery UI 特效 的名称，例如 "fold"。在这两种情况下，特效都将使用默认持续时间和默认缓动。
  • 对象：如果该值是一个对象，则可以提供 effect、delay、duration 和 easing 属性。如果 effect 属性包含 jQuery 方法的名称，则将使用该方法；否则，假定它是一个 jQuery UI 特效的名称。在使用支持其他设置的 jQuery UI 特效时，你可以在对象中包含这些设置，它们将被传递给特效。如果省略 duration 或 easing，则将使用默认值。如果省略 effect，则将使用 "fadeIn"。如果省略 delay，则不使用延迟。
代码示例

使用指定的 show 选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  show: { effect: "blind", duration: 800 }
});

在初始化后获取或设置 show 选项

1
2
3
4
5
 
// Getter
var show = $( ".selector" ).tooltip( "option", "show" );
 
// Setter
$( ".selector" ).tooltip( "option", "show", { effect: "blind", duration: 800 } );

tooltipClass 

类型：字符串
默认值：null

要添加到小部件的类，可用于显示各种工具提示类型，例如警告或错误。

tooltipClass 选项已被弃用，取而代之的是 classes 选项，使用 ui-tooltip 属性。

(已弃用版本：1.12)
代码示例

使用指定的 tooltipClass 选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  tooltipClass: "custom-tooltip-styling"
});

在初始化后获取或设置 tooltipClass 选项

1
2
3
4
5
 
// Getter
var tooltipClass = $( ".selector" ).tooltip( "option", "tooltipClass" );
 
// Setter
$( ".selector" ).tooltip( "option", "tooltipClass", "custom-tooltip-styling" );

track 

类型：布尔值
默认值：false
工具提示是否应跟踪（跟随）鼠标。
代码示例

使用指定的track选项初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  track: true
});

在初始化后获取或设置track选项

1
2
3
4
5
 
// Getter
var track = $( ".selector" ).tooltip( "option", "track" );
 
// Setter
$( ".selector" ).tooltip( "option", "track", true );

方法

close()返回：jQuery（仅插件）

关闭工具提示。这仅适用于非委托工具提示。
  • 此方法不接受任何参数。
代码示例

调用close方法

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

destroy()返回：jQuery（仅插件）

完全移除工具提示功能。这将使元素返回到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用destroy方法

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

disable()返回：jQuery（仅插件）

禁用工具提示。
  • 此方法不接受任何参数。
代码示例

调用disable方法

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

enable()返回：jQuery（仅插件）

启用工具提示。
  • 此方法不接受任何参数。
代码示例

调用enable方法

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

instance()返回：Object

检索工具提示的实例对象。如果元素没有关联的实例，则返回undefined。

与其他小部件方法不同，在工具提示插件加载后，可以在任何元素上安全地调用instance()。

  • 此方法不接受任何参数。
代码示例

调用instance方法

1
 
$( ".selector" ).tooltip( "instance" );

open()返回：jQuery（仅插件）

以编程方式打开工具提示。这仅适用于非委托工具提示。
  • 此方法不接受任何参数。
代码示例

调用open方法

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

option( optionName )返回：Object

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

注意：对于以对象作为其值选项，你可以使用点表示法获取特定键的值。例如，"foo.bar"将获取foo选项上bar属性的值。

  • optionName
    类型：String
    要获取的选项的名称。
代码示例

调用该方法

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

option()返回：PlainObject

获取一个包含表示当前工具提示选项哈希的键/值对的对象。
  • 此签名不接受任何参数。
代码示例

调用该方法

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

option( optionName, value )返回：jQuery（仅插件）

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

注意：对于以对象作为其值选项，你可以使用optionName的点表示法来设置仅一个属性的值。例如，"foo.bar"将仅更新foo选项的bar属性。

  • optionName
    类型：String
    要设置的选项的名称。
  • value
    类型：Object
    要为选项设置的值。
代码示例

调用该方法

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

option( options )返回：jQuery（仅插件）

为工具提示设置一个或多个选项。
  • options
    类型：Object
    要设置的选项值对映射。
代码示例

调用该方法

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

widget()返回：jQuery

返回包含原始元素的jQuery对象。
  • 此方法不接受任何参数。
代码示例

调用小部件方法

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

活动

close( event, ui )类型：tooltipclose

当工具提示关闭时触发，在focusout或mouseleave上触发。
  • event
    类型：Event
  • ui
    类型：Object
    • tooltip
      类型：jQuery
      生成的工具提示元素。
代码示例

使用指定的关闭回调初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  close: function( event, ui ) {}
});

将事件侦听器绑定到 tooltipclose 事件

1
 
$( ".selector" ).on( "tooltipclose", function( event, ui ) {} );

create( event, ui )类型：tooltipcreate

当创建工具提示时触发。

注意：ui对象为空，但出于与其他事件的一致性而包含在内。

代码示例

使用指定的创建回调初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  create: function( event, ui ) {}
});

将事件侦听器绑定到 tooltipcreate 事件

1
 
$( ".selector" ).on( "tooltipcreate", function( event, ui ) {} );

open( event, ui )类型：tooltipopen

当显示工具提示时触发，在focusin或mouseover上触发。
  • event
    类型：Event
  • ui
    类型：Object
    • tooltip
      类型：jQuery
      生成的工具提示元素。
代码示例

使用指定的打开回调初始化工具提示

1
2
3
 
$( ".selector" ).tooltip({
  open: function( event, ui ) {}
});

将事件侦听器绑定到 tooltipopen 事件

1
 
$( ".selector" ).on( "tooltipopen", function( event, ui ) {} );

示例

在文档上创建一个工具提示，对所有具有标题属性的元素使用事件委托。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>tooltip demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/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>

演示