Подсказки

Из практического примера мы уже знаем, что добавить подсказки в спецификацию довольно просто. Здесь рассмотрим их подробнее.

Если вы ещё не читали обзор интерактивности, начните с него: он объясняет особенности взаимодействия с Power BI. Это особенно полезно для понимания подсказок на основе страницы отчёта.

Как работают подсказки

Vega и Vega-Lite позволяют настраивать обработку событий подсказок. Deneb содержит собственный обработчик для Power BI. Подсказка появляется, если выполнены следующие условия:

1. В разделе Tooltips панели Project setup редактора визуала включена настройка Tooltip Handler. По умолчанию она включена.
2. Примитиву задано подходящее свойство tooltip. Рекомендуемый синтаксис для каждой библиотеки приведён ниже.
3. Указатель наведён на примитив с включённой подсказкой.

Определение точки данных

Если объект datum примитива не был преобразован относительно "dataset" и представляет исходный контекст переданной строки, Deneb может сопоставить его с Power BI. Контекст строки нужен только для подсказок на основе страницы отчёта. Обычные подсказки выводят данные как пары «ключ — значение» и работают с любым объектом datum.

Если существует страница подсказки с хотя бы одним столбцом из текущего datum, Power BI покажет её в контексте этой строки:

Если подходящей страницы нет либо в меню Tooltip панели свойств Power BI выбрана стандартная подсказка, появится обычная подсказка:

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

Если в отчёте включена поддержка современных подсказок и для точки данных существует подходящая страница drill-through, соответствующее действие будет доступно в подсказке:

Оформление обычных подсказок

Настраивайте его обычным способом — в меню Tooltip панели свойств Power BI.

Синтаксис Vega-Lite

Рекомендуется самый простой подход:

{
    ...
        "mark": {
            ...
            "tooltip": true,
            ...
        },
    ...
}

Синтаксис Vega

В Vega нужно задать сигнал tooltip в свойстве encode примитива:

{
    ...
    "encode": {
        "enter": {
            ...
            "tooltip": {
                "signal": "datum"
            },
            ...
        }
    },
    ...
}

Поддержка текстовых шаблонов подсказок

В июне 2026 года в Power BI появились текстовые шаблоны подсказок. Они позволяют добавлять в стандартную подсказку произвольный текст с подстановками значений полей, обозначенными фигурными скобками.

Deneb поддерживает эту возможность с важным условием: каждое поле, указанное в текстовом шаблоне, должно явно присутствовать в данных подсказки, которые Deneb получает для примитива под указателем. Если поля нет, его обозначение останется в тексте без подстановки. Самый простой способ обеспечить наличие полей — перечислить их в канале кодирования tooltip Vega-Lite или в записи tooltip свойства encode Vega.

Меню Tooltips — стандартное свойство контейнера, которым управляет Power BI. Сам текст нельзя прочитать, задать или изменить из спецификации. Он также не переносится вместе с шаблоном Deneb: его нужно настроить в самом визуале.

Полный практический пример, распространённые ошибки и способ использования полей, существующих только в спецификации — например, результатов преобразования, — описаны в статье «Текстовые подсказки Power BI в Deneb».

Отладка с помощью подсказок

Если вместо подготовленных Vega данных, получаемых при tooltip: true, выводить исходный объект точки данных — например, способом Vega-Lite, — можно увидеть больше внутренних сведений:

Это помогает определить дополнительные поля и вычисления, доступные для выражений. Также можно проверить, сохранил ли примитив контекст строки и можно ли сопоставить его с Power BI для интерактивных действий. Наличие поля __row__ в datum подсказки подтверждает эту связь.

Значение дополнительных полей объясняется в обзоре интерактивности.

Ограничения и особенности

• Подсказки на основе страницы отчёта полностью зависят от правильного контекста строки: datum должен сопоставляться со строкой набора данных визуала. Обычные подсказки, включая текстовые шаблоны, выводят пары «ключ — значение» и контекста строки не требуют. Подробнее см. выше и в обзоре.
• Добавление подсказки само по себе не создаёт визуальной реакции или эффектов. Если нужно явно обозначить положение точки данных, например на линейном графике, добавьте подходящие примитивы. Примеры есть в галереях Vega и Vega-Lite.
• Разработка этой функциональности прежде всего ориентирована на интеграцию с Power BI. При отклонении от описанных способов подсказки могут отображаться неправильно. Если обнаружите такой случай, создайте обращение на GitHub с инструкцией по воспроизведению, спецификацией и/или данными, чтобы разработчики могли его изучить.