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

Bokeh Tooltips 完全指南为 UI 组件与可视化添加交互提示信息【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh 在广泛的 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 objectBokeh 使用bokeh.models.Tooltip模型来统一管理 tooltip 的行为与外观。Tooltip是UIElement的子类其实现在 src/bokeh/models/ui/tooltips.py 中。与普通可见组件不同它的visible属性被显式覆写为默认False即 tooltip 默认处于隐藏状态只有在用户悬停、点击或程序触发时才显示。下表汇总了Tooltip模型的核心属性对应源码 tooltips.py 与类型声明 tooltips.pyi属性类型默认值说明contentstr \| DOMNode \| UIElement必填—tooltip 的内容可以是纯文本字符串、bokeh.models.dom.HTML等 DOM 节点甚至另一个 UI 元素positionAnchor \| (float, float) \| Coordinate \| NoneNonetooltip 相对其父元素的位置既可以是right、top等锚点值也可以是像素坐标或坐标节点targetUIElement \| Selector \| autoautotooltip 的挂载目标某个 Bokeh 模型实例、CSS 选择器等 Selector或在auto模式下从其父元素推断attachmentTooltipAttachment \| autoautotooltip 相对光标位置的放置方向show_arrowboolTrue是否显示指向目标的小箭头closableboolFalse是否允许通过点击关闭x按钮来关闭 tooltip适合用于持久显示的提示interactiveboolTrue是否允许 tooltip 内容接收指针事件若设为False用户将无法与内容交互例如点击其中的链接其中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 contentsTooltip的内容通过其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(contentplain text tooltip, positionright) html_tooltip Tooltip(contentHTML(bHTML/b tooltip), positionright) input_with_plaintext_tooltip TextInput(valuedefault, titleLabel:, descriptionplaintext_tooltip) input_with_html_tooltip TextInput(valuedefault, titleLabel2:, descriptionhtml_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默认descriptionNullable(Either(String, Instance(Tooltip)))默认None既可以是纯文本也可以是一个携带富 HTML 内容的Tooltip实例。当用户悬停或点击输入控件标题旁的 ? 符号时会显示description属性中定义的 tooltipfrom bokeh.io import show from bokeh.models import MultiChoice, Tooltip OPTIONS [apple, mango, banana, tomato] tooltip Tooltip(contentChoose any number of the items, positionright) multi_choice MultiChoice(valueOPTIONS[:2], optionsOPTIONS, titleChoose values:, descriptiontooltip) show(multi_choice)上面的示例来自 examples/interaction/tooltips/tooltip_description.py展示了如何为一个MultiChoice控件挂接 tooltip。注意由于descriptiontooltip 与输入控件的标题绑定因此只有当控件的title参数有值时它才会生效。如果控件没有标题通过description参数定义的 tooltip 将不会被显示。当前支持 tooltips 的输入控件完整列表如下对应示例均可在 examples/interaction/widgets 目录中找到控件示例文件AutocompleteInputexamples/interaction/widgets/autocompleteinput.pyColorPickerexamples/interaction/widgets/colorpicker.pyDatePickerexamples/interaction/widgets/date_picker.pyDateRangePickerexamples/interaction/widgets/date_range_picker.pyMultipleDatePickerexamples/interaction/widgets/multiple_date_picker.pyDatetimeRangePickerexamples/interaction/widgets/datetime_range_picker.pyMultipleDatetimePickerexamples/interaction/widgets/multiple_datetime_picker.pyFileInputexamples/interaction/widgets/fileinput.pyMultiChoiceexamples/interaction/widgets/multichoice.pyMultiSelectexamples/interaction/widgets/multiselect.pyNumericInputexamples/interaction/widgets/numericinput.pyPasswordInputexamples/interaction/widgets/passwordinput.pySelectexamples/interaction/widgets/select_widget.pySpinnerexamples/interaction/widgets/spinner.pyTextAreaInputexamples/interaction/widgets/textareainput.pyTextInputexamples/interaction/widgets/textinput.pyTimePickerexamples/interaction/widgets/time_picker.py重要约束单个Tooltip实例只能被使用一次。如果两个控件引用了同一个Tooltip实例只有第一个会显示from bokeh.models import Tooltip, AutocompleteInput, ColorPicker from bokeh.layouts import column from bokeh.io import show tooltip Tooltip(contentEnter a value, positionright) input_widgets [ AutocompleteInput(valueAutocompleteInput, titleChoose value:, descriptiontooltip), # tooltip displayed here ColorPicker(colorred, titleChoose color:, descriptiontooltip), # no tooltip displayed here ] show(column(input_widgets))正确做法是为每个控件创建不同的Tooltip实例不要复用。HelpButton如果你希望给一个本身不支持 tooltips的 UI 元素添加提示信息可以使用HelpButton控件。该控件显示一个带 ? 符号的按钮当按钮被点击或悬停时会展示传入其tooltip属性的Tooltip对象。HelpButton定义在 src/bokeh/models/widgets/buttons.py其关键实现点包括tooltipRequired(Instance(Tooltip))必填属性携带纯文本或富 HTML 的帮助内容label被覆写为默认icon默认使用BuiltinIcon(help, size18)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(labelsLABELS, active0) tooltip Tooltip(contentfSelect one of the following options: {, .join(LABELS)}, positionright) help_button HelpButton(tooltiptooltip) show(row(radio_button_group, help_button))在这里RadioButtonGroup本身没有 tooltip 能力但通过并排的HelpButton实现了等效的提示效果。向任意 UI 元素添加 tooltips除了将 tooltip 添加到上述内置支持的 UI 元素外你还可以把 tooltip 挂到任意UI 元素上。方法是使用Tooltip对象的target属性它支持两种目标标识方式tooltips.py任意 Bokeh 模型实例直接传入一个UIElement或其子类实例作为挂载目标Selector 模型实例传入bokeh.models.selectors中的 CSS 选择器模型用它来描述你想附加 tooltip 的 DOM 元素。Selector抽象基类及其实现都位于 src/bokeh/models/selectors.py可用的选择器包括选择器说明ByID(my_id)按元素 ID 匹配不带#前缀也可用ByCSS(#my_id)ByClass(my_class)按 CSS 类名匹配不带.前缀也可用ByCSS(.my_class)ByCSS(#id .class)传入任意完整的 CSS 选择器表达式ByXPath(/html/body/...)按 XPath 路径匹配 DOM 节点定义好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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考