工具提示#

Bokeh 支持在各种 UI 元素上使用工具提示,例如绘图或组件。您可以使用工具提示将附加信息附加到可视化的几乎任何部分。

注意

工具提示的一个特殊情况是由 HoverTool 显示的工具提示。如果您想在悬停在绘图的特定区域上时显示工具提示,请使用悬停工具。此工具在幕后使用 Bokeh 的通用工具提示对象,但包含许多额外的、主题功能。有关使用 HoverTool 在绘图上配置工具提示的更多信息,请参阅基本工具提示 部分以获取更多信息。

Tooltip 对象#

Bokeh 使用 Tooltip 模型来管理工具提示。Tooltip 对象有多个属性来定制工具提示的行为和外观。有关更多信息,请参阅Tooltip参考指南中。

工具提示内容#

Tooltip 的内容由其 content 属性定义。

此内容可以是纯文本字符串或 HTML 对象

from bokeh.io import show
from bokeh.layouts import column
from bokeh.models import TextInput, Tooltip
from bokeh.models.dom import HTML

plaintext_tooltip = Tooltip(content="plain text tooltip", position="right")
html_tooltip = Tooltip(content=HTML("<b>HTML</b> tooltip"), position="right")

input_with_plaintext_tooltip = TextInput(value="default", title="Label:", description=plaintext_tooltip)
input_with_html_tooltip = TextInput(value="default", title="Label2:", description=html_tooltip)

show(column(input_with_plaintext_tooltip, input_with_html_tooltip))

悬停或点击输入标题旁边的“?”符号,以查看工具提示的实际效果。

注意

目前,Tooltip 对象至少需要设置 contentposition 属性。如果这两个属性都没有赋值,则不会渲染工具提示。

支持工具提示的 UI 元素#

Bokeh 的几个对象内置了对工具提示的支持。

输入组件#

InputWidget 基类的所有后代都内置了对工具提示的支持。这些输入有一个 description 属性,它接受 Tooltip 对象作为其值。当用户悬停或点击输入组件标题旁边的“?”符号时,将显示由 description 属性定义的工具提示

from bokeh.io import show
from bokeh.models import MultiChoice, Tooltip

OPTIONS = ["apple", "mango", "banana", "tomato"]

tooltip = Tooltip(content="Choose any number of the items", position="right")

multi_choice = MultiChoice(value=OPTIONS[:2], options=OPTIONS, title="Choose values:", description=tooltip)

show(multi_choice)

注意

由于 description 工具提示与输入组件的标题相关联,因此只有当组件的 title 参数有值时,此功能才有效。如果组件没有标题,则不会显示使用 description 参数定义的工具提示。

目前,以下输入组件直接支持工具提示

提示

一个 Tooltip 的单个实例应仅使用一次。如果两个组件引用同一个 Tooltip 实例,则只会显示第一个。

from bokeh.models import Tooltip, AutocompleteInput, ColorPicker
from bokeh.layouts import column
from bokeh.io import show

tooltip=Tooltip(content="Enter a value", position="right")
input_widgets = [
    AutocompleteInput(value="AutocompleteInput", title="Choose value:", description=tooltip),  # tooltip displayed here
    ColorPicker(color="red", title="Choose color:", description=tooltip),  # no tooltip displayed here
]
show(column(input_widgets))

相反,请确保为每个组件使用不同的 Tooltip 实例。

HelpButton#

如果您想向没有内置工具提示支持的 UI 元素添加带有附加信息的工具提示,您可以使用 HelpButton。此组件添加一个带有“?”符号的按钮。当按钮被点击或悬停时,将显示传递给 HelpButton 的 tooltip 属性的 Tooltip 对象。

from bokeh.io import show
from bokeh.layouts import row
from bokeh.models import HelpButton, RadioButtonGroup, Tooltip

LABELS = ["Option 1", "Option 2", "Option 3"]

radio_button_group = RadioButtonGroup(labels=LABELS, active=0)
tooltip = Tooltip(content=f"Select one of the following options: {', '.join(LABELS)}", position="right")
help_button = HelpButton(tooltip=tooltip)

show(row(radio_button_group, help_button))

有关更多信息,请参阅 HelpButton

向任意 UI 元素添加工具提示#

除了向显式支持工具提示的元素添加工具提示外,您还可以向任意 UI 元素添加工具提示。

使用 Tooltip 对象的 target 属性将此工具提示链接到 UI 元素。您有两种选择来向 target 属性标识 UI 元素

  • 任何 Bokeh 模型的实例

  • 一个 selectors 模型的实例,该模型表示您要将工具提示附加到的元素的 CSS 选择器

在定义 Tooltip 对象并指定目标后,您需要将工具提示添加到 document 中。

其他 UI 元素#

Bokeh 还支持其他 UI 元素,您可以使用它们向 Bokeh 文档添加更多信息。例如,Dialog 模型允许您定义对话框覆盖,而 Menu 模型允许您定义自定义上下文菜单。

有关这些 UI 元素的示例,请参阅 examples/models/widgets.py