Spec-Zone.ru › jQuery UI

Виджет всплывающей подсказки

Виджет всплывающей подсказкиверсия добавлена: 1.9

Описание: Настраиваемые и стилизуемые всплывающие подсказки, заменяющие стандартные.

Быстрый переходПримеры

Параметры

классы
содержимое
отключено
скрыть
элементы
позиция
показать
класс подсказки
отслеживание

Методы

закрыть
удалить
отключить
включить
экземпляр
открыть
параметр
видет

События

закрытие
создание
открытие

Виджет всплывающей подсказки заменяет стандартные всплывающие подсказки, делая их стилизуемыми и позволяя различные настройки:

  • Отображение другого контента, кроме заголовка, например, сносок или дополнительного контента, полученного через Ajax.
  • Настройка позиционирования, например, для центрирования подсказки над элементами.
  • Добавление дополнительного стилирования для настройки внешнего вида, например, для полей с предупреждениями или ошибками.

По умолчанию используется анимация плавного появления и скрытия всплывающей подсказки, что делает внешний вид более плавным по сравнению с простым переключением видимости. Это можно настроить с помощью параметров show и hide.

Параметры items и content должны быть синхронизированы. Если вы измените один из них, вам нужно изменить и другой.

В общем случае, отключенные элементы не генерируют никаких событий DOM. Поэтому невозможно правильно управлять всплывающими подсказками для отключенных элементов, так как нам нужно прослушивать события, чтобы определить, когда показывать и скрывать подсказку. В результате jQuery UI не гарантирует поддержку всплывающих подсказок, прикрепленных к отключенным элементам. К сожалению, это означает, что если вам нужны всплывающие подсказки на отключенных элементах, у вас может получиться смесь стандартных всплывающих подсказок и всплывающих подсказок jQuery UI.

Взаимодействие с клавиатурой

Когда всплывающая подсказка открыта, а соответствующий элемент имеет фокус, доступны следующие команды клавиатуры:

  • ESCAPE: Закрыть всплывающую подсказку.

Тематизация

Виджет всплывающей подсказки использует фреймворк CSS-фреймворк jQuery UI для стилизации своего внешнего вида. Если требуется специфическое стилирование всплывающей подсказки, для переопределения или в качестве ключей для classes параметра можно использовать следующие имена классов CSS:

  • ui-tooltip: Внешний контейнер для всплывающей подсказки.
    • ui-tooltip-content: Содержимое всплывающей подсказки.

Зависимости

  • UI Core
  • Заводской класс виджетов
  • Позиционирование
  • Ядро эффектов (необязательно; для использования с параметрами show и hide)

Дополнительные заметки:

  • Для работы этого виджета необходим функциональный CSS. Если вы создаёте собственную тему, используйте файл CSS виджета в качестве отправной точки.

Параметры

classes

Тип: Объект
По умолчанию:
{
  "ui-tooltip": "ui-corner-all ui-widget-shadow"
}

Укажите дополнительные классы, которые нужно добавить к элементам виджета. Любой из классов, указанных в разделе Тема, может использоваться в качестве ключа для переопределения его значения. Чтобы узнать больше об этом параметре, ознакомьтесь со статьей учебник о параметре classes.

Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром classes, изменяя тему для класса ui-tooltip:

$( ".selector" ).tooltip({
  classes: {
    "ui-tooltip": "highlight"
  }
});

Получите или задайте свойство параметра classes, после инициализации, здесь читаем и изменяем тему для класса ui-tooltip:

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

content

Тип: Функция() или Строка или Элемент или jQuery
По умолчанию: function returning the title attribute

Содержимое всплывающей подсказки.

При изменении этого параметра, вероятно, также необходимо изменить параметр items.

Поддерживаются несколько типов:
  • Функция: Обратный вызов, который может либо вернуть содержимое непосредственно, либо вызвать первый аргумент, передав содержимое, например, для содержимого Ajax.
  • Строка: Строка HTML для использования в качестве содержимого всплывающей подсказки.
  • Элемент: Элемент DOM для использования в качестве содержимого всплывающей подсказки.
  • jQuery: Объект jQuery для использования в качестве содержимого всплывающей подсказки.
Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром content:

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

Получите или задайте параметр content, после инициализации:

// Getter
var content = $( ".selector" ).tooltip( "option", "content" );
 
// Setter
$( ".selector" ).tooltip( "option", "content", "Awesome title!" );

disabled

Тип: Булево
По умолчанию: false
Отключает всплывающую подсказку, если установлено значение true.
Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром disabled:

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

Получите или задайте параметр disabled, после инициализации:

// 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:

$( ".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

Тип: Селектор
По умолчанию: [title]

Селектор, указывающий, какие элементы должны отображать всплывающие подсказки. Настройте, если вы используете что-то другое, чем атрибут title для содержимого всплывающей подсказки, или если вам нужен другой селектор для делегирования событий.

При изменении этого параметра, вероятно, также необходимо изменить параметр content.

Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром items:

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

Получите или задайте параметр items, после инициализации:

// 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.

Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром position:

$( ".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

Тип: Булево или Число или Строка или Объект
По умолчанию: true
Как и когда анимировать отображение всплывающей подсказки.
Поддерживаются несколько типов:
  • Булево: При установке значения false, анимация не будет использоваться, и всплывающая подсказка будет отображена немедленно. При установке значения true, всплывающая подсказка будет отображаться с плавным эффектом с заданной по умолчанию продолжительностью и плавностью.
  • Число: Всплывающая подсказка будет отображаться с плавным эффектом с заданной продолжительностью и плавностью по умолчанию.
  • Строка: Всплывающая подсказка будет отображаться с заданным эффектом. Значение может быть именем встроенного метода анимации jQuery, например, "slideDown", или именем эффекта jQuery UI, например, "fold". В обоих случаях эффект будет использован с продолжительностью и плавностью по умолчанию.
  • Объект: Если значение является объектом, то свойства effect, delay, duration, и easing могут быть предоставлены. Если свойство effect содержит имя метода jQuery, то будет использован этот метод; в противном случае предполагается, что это имя эффекта jQuery UI. При использовании эффекта jQuery UI, поддерживающего дополнительные настройки, вы можете включить эти настройки в объект, и они будут переданы эффекту. Если duration или easing отсутствуют, будут использованы значения по умолчанию. Если effect отсутствует, будет использовано значение "fadeIn". Если delay отсутствует, задержка не используется.
Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром show:

$( ".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

Тип: Строка
По умолчанию: null

Класс, который нужно добавить к виджету, может быть использован для отображения различных типов всплывающих подсказок, таких как предупреждения или ошибки.

Параметр tooltipClass устарел в пользу параметра classes, используя свойство ui-tooltip.

(версия устаревшая: 1.12)
Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром tooltipClass:

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

Получите или задайте параметр tooltipClass, после инициализации:

// Getter
var tooltipClass = $( ".selector" ).tooltip( "option", "tooltipClass" );
 
// Setter
$( ".selector" ).tooltip( "option", "tooltipClass", "custom-tooltip-styling" );

track

Тип: Булево
По умолчанию: false
Следует ли всплывающей подсказке отслеживать (следовать) курсор мыши.
Примеры кода:

Инициализируйте всплывающую подсказку с указанным параметром track:

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

Получите или задайте параметр track, после инициализации:

// Getter
var track = $( ".selector" ).tooltip( "option", "track" );
 
// Setter
$( ".selector" ).tooltip( "option", "track", true );

Методы

close()Возвращает: jQuery (только для плагинов)

Закрывает подсказку. Это предназначено только для вызова для не-делегированных подсказок.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

Вызов метода close:

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

destroy()Возвращает: jQuery (только для плагинов)

Полностью удаляет функциональность подсказки. Это вернет элемент в состояние до инициализации.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

Вызов метода destroy:

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

disable()Возвращает: jQuery (только для плагинов)

Отключает подсказку.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

Вызов метода disable:

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

enable()Возвращает: jQuery (только для плагинов)

Включает подсказку.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

Вызов метода enable:

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

instance()Возвращает: Объект

Возвращает объект экземпляра подсказки. Если у элемента нет связанного экземпляра, возвращается undefined.

В отличие от других методов виджета, instance() можно безопасно вызывать для любого элемента после загрузки плагина подсказки.

  • Этот метод не принимает никаких аргументов.
Примеры кода:

Вызов метода instance:

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

open()Возвращает: jQuery (только для плагинов)

Программно открывает подсказку. Это предназначено только для вызова для не-делегированных подсказок.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

Вызов метода open:

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

option( optionName )Возвращает: Объект

Получает значение, текуще связанное с указанным optionName.

Примечание: Для опций, значениями которых являются объекты, можно получить значение определенного ключа, используя точечную нотацию. Например, "foo.bar" получит значение свойства bar опции foo.

  • optionName
    Тип: Строка
    Имя опции для получения.
Примеры кода:

Вызов метода:

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

option()Возвращает: Объект

Получает объект, содержащий пары ключ/значение, представляющие текущий хэш опций подсказки.
  • Этот метод не принимает аргументов.
Примеры кода:

Вызов метода:

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

option( optionName, value )Возвращает: jQuery (только для плагинов)

Устанавливает значение опции подсказки, связанной с указанным optionName.

Примечание: Для опций, значениями которых являются объекты, можно установить значение только одного свойства, используя точечную нотацию для optionName. Например, "foo.bar" обновит только свойство bar опции foo.

  • optionName
    Тип: Строка
    Имя опции для установки.
  • value
    Тип: Объект
    Значение для установки опции.
Примеры кода:

Вызов метода:

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

option( options )Возвращает: jQuery (только для плагинов)

Устанавливает одну или несколько опций для подсказки.
  • options
    Тип: Объект
    Карта пар опция-значение для установки.
Примеры кода:

Вызов метода:

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

widget()Возвращает: jQuery

Возвращает объект jQuery содержащий исходный элемент.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

Вызов метода widget:

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

События

close( event, ui )Тип: tooltipclose

Срабатывает при закрытии подсказки, срабатывает на focusout или mouseleave.
  • event
    Тип: Событие
  • ui
    Тип: Объект
    • tooltip
      Тип: jQuery
      Сгенерированный элемент подсказки.
Примеры кода:

Инициализация подсказки с указанным обратным вызовом close:

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

Привязка обработчика событий к событию tooltipclose:

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

create( event, ui )Тип: tooltipcreate

Срабатывает при создании подсказки.
  • event
    Тип: Событие
  • ui
    Тип: Объект

Примечание: Объект ui пуст, но включен для согласованности с другими событиями.

Примеры кода:

Инициализация подсказки с указанным обратным вызовом create:

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

Привязка обработчика событий к событию tooltipcreate:

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

open( event, ui )Тип: tooltipopen

Срабатывает при отображении подсказки, срабатывает на focusin или mouseover.
  • event
    Тип: Событие
  • ui
    Тип: Объект
    • tooltip
      Тип: jQuery
      Сгенерированный элемент подсказки.
Примеры кода:

Инициализация подсказки с указанным обратным вызовом open:

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

Привязка обработчика событий к событию tooltipopen:

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

Пример:

Создайте подсказку на документе, используя делегирование событий для всех элементов с атрибутом title.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>tooltip demo</title>
  <link rel="stylesheet" href="https://code.jquery.com/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
  <script src="https://code.jquery.com/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>

Демо:

© The jQuery Foundation and other contributors
Licensed under the MIT License.
https://api.jqueryui.com/tooltip

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API