企业官网建设流程全解析

Bokeh Tooltips 完全指南：为 UI 组件与可视化添加交互提示信息

【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh

Bokeh 在广泛的 UI 元素（如绘图、控件）上内置了 Tooltips（提示气泡）支持，你可以把额外的说明信息附加到可视化中几乎任何一部分。本文以 Bokeh 官方用户指南的 Tooltips 章节（docs/bokeh/source/docs/user_guide/interaction/tooltips.rst）为主线，结合仓库源码深入讲解Tooltip模型的完整属性、content内容定义、内置支持 tooltips 的全部输入控件、HelpButton的用法，以及通过target属性把 tooltip 挂载到任意 UI 元素上的进阶方案。读完本文，你将能够为输入控件、任意组件乃至整个 Bokeh 文档中的指定 DOM 节点配置专业、可交互的提示信息。

Tooltip 对象（The Tooltip object）

Bokeh 使用bokeh.models.Tooltip模型来统一管理 tooltip 的行为与外观。Tooltip是UIElement的子类，其实现在 src/bokeh/models/ui/tooltips.py 中。与普通可见组件不同，它的visible属性被显式覆写为默认False，即 tooltip 默认处于隐藏状态，只有在用户悬停、点击或程序触发时才显示。

下表汇总了Tooltip模型的核心属性（对应源码 tooltips.py 与类型声明 tooltips.pyi）：

其中attachment可取的枚举值定义在 src/bokeh/core/enums.py，为"horizontal" | "vertical" | "left" | "right" | "above" | "below"六种：

• "horizontal"/"vertical"：分别在水平或垂直维度自动选择放置方向；
• "left"/"right"/"above"/"below"：固定在光标的左、右、上、下侧显示。

position的锚点值来自Anchor枚举（如"top"、"right"、"top_right"等），也可直接传入(x, y)像素元组。注意：目前Tooltip对象至少需要同时设置content和position两个属性，否则 tooltip 不会被渲染。

提示：HoverTool 是 tooltip 的一个特例。如果你希望在鼠标悬停到绘图特定区域时显示提示，请使用 HoverTool——它在底层同样使用 Bokeh 的通用 Tooltip 对象，但额外包含了许多主题化功能。关于为绘图配置 HoverTool tooltip 的详细说明，可参考交互章节中 HoverTool 基础 tooltip 的部分。

Tooltip 内容（Tooltip contents）

Tooltip的内容通过其content属性定义，它既可以是纯文本字符串，也可以是 HTML 对象。官方示例 examples/interaction/tooltips/tooltip_content.py 演示了这两种形式：

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 的实际效果：一个是普通文本，另一个是渲染为粗体 HTML 的内容。从源码看，content属性的类型是Required(Either(String, Instance(DOMNode), Instance(UIElement)))（tooltips.py），这意味着除了字符串和HTML节点，你甚至可以把另一个UIElement直接作为 tooltip 的内容嵌入，构建出包含按钮、图标等控件的富提示气泡。

支持 tooltips 的 UI 元素

Bokeh 中多个对象内置了 tooltip 支持，其中最重要的两类是输入控件（InputWidget）和HelpButton。

输入控件（Input widgets）

所有bokeh.models.InputWidget基类的后代都内置了 tooltip 支持。InputWidget抽象基类定义在 src/bokeh/models/widgets/inputs.py，它声明了两个关键属性：

• title：控件的标签（str \| HTML，默认""）；
• description：Nullable(Either(String, Instance(Tooltip)))，默认None，既可以是纯文本，也可以是一个携带富 HTML 内容的Tooltip实例。

当用户悬停或点击输入控件标题旁的 "?" 符号时，会显示description属性中定义的 tooltip：

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)

上面的示例来自 examples/interaction/tooltips/tooltip_description.py，展示了如何为一个MultiChoice控件挂接 tooltip。

注意：由于descriptiontooltip 与输入控件的标题绑定，因此只有当控件的title参数有值时它才会生效。如果控件没有标题，通过description参数定义的 tooltip 将不会被显示。

当前支持 tooltips 的输入控件完整列表如下（对应示例均可在 examples/interaction/widgets 目录中找到）：

重要约束：单个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

如果你希望给一个本身不支持 tooltips的 UI 元素添加提示信息，可以使用HelpButton控件。该控件显示一个带 "?" 符号的按钮，当按钮被点击或悬停时，会展示传入其tooltip属性的Tooltip对象。

HelpButton定义在 src/bokeh/models/widgets/buttons.py，其关键实现点包括：

• tooltip：Required(Instance(Tooltip))，必填属性，携带纯文本或富 HTML 的帮助内容；
• label被覆写为默认""，icon默认使用BuiltinIcon("help", size=18)，button_type默认"default"。

官方示例 examples/interaction/tooltips/tooltip_helpbutton.py 演示了如何把 HelpButton 与一组单选按钮并排组合：

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

在这里，RadioButtonGroup本身没有 tooltip 能力，但通过并排的HelpButton实现了等效的提示效果。

向任意 UI 元素添加 tooltips

除了将 tooltip 添加到上述内置支持的 UI 元素外，你还可以把 tooltip 挂到任意UI 元素上。方法是使用Tooltip对象的target属性，它支持两种目标标识方式（tooltips.py）：

1. 任意 Bokeh 模型实例：直接传入一个UIElement（或其子类）实例作为挂载目标；
2. Selector 模型实例：传入bokeh.models.selectors中的 CSS 选择器模型，用它来描述你想附加 tooltip 的 DOM 元素。

Selector抽象基类及其实现都位于 src/bokeh/models/selectors.py，可用的选择器包括：

定义好Tooltip对象并指定target之后，还需要把 tooltip 添加到bokeh.document（文档）中，它才会随文档一起渲染。

其他 UI 元素（Other UI elements）

除 tooltip 外，Bokeh 还支持其他用于向文档添加补充信息的 UI 元素：

• bokeh.models.Dialog：定义对话框覆盖层；
• bokeh.models.Menu：定义自定义上下文菜单。

两者的使用示例可参考 examples/models/widgets.py 以及基础 UI 示例 examples/basic/ui/dialog.py。此外，UIElement基类还提供了context_menu属性（见 src/bokeh/models/ui/ui_element.py），可用于在用户右键点击组件时显示菜单——这为构建完整的交互式文档提供了更多可能。

小结与实战建议

• 最小可用配置：创建Tooltip时必须同时设置content和position，否则不渲染；
• 内容形态：content支持纯文本、HTML对象乃至任意UIElement，富提示用bokeh.models.dom.HTML即可；
• 内置支持：17 种InputWidget输入控件通过description属性获得提示能力，前提是设置了title；
• 实例唯一性：一个Tooltip实例只能绑定一个控件，多个控件请各自创建实例；
• 无内置支持的元素：优先用HelpButton，或用target属性配合ByCSS/ByXPath等选择器将 tooltip 挂到任意 UI 元素或 DOM 节点上，最后别忘了加入 document；
• 绘图场景：若要在绘图区域悬停时显示提示，应使用 HoverTool，而非通用Tooltip。

以上内容与 Bokeh 官方用户指南 Tooltips 章节一致，并以当前仓库源码（src/bokeh/models/ui/tooltips.py、src/bokeh/models/widgets/inputs.py、src/bokeh/models/widgets/buttons.py、src/bokeh/models/selectors.py）及三个官方示例（tooltip_content、tooltip_description、tooltip_helpbutton）为验证依据，可直接复制运行。

【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh