Bokeh 3.4.0 版本全解析：浮动 UI、零延迟交互与数学文本渲染的新里程碑

Bokeh 3.4.0 版本全解析：浮动 UI、零延迟交互与数学文本渲染的新里程碑

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

导读

Bokeh 3.4.0（2024 年 3 月发布）是 Bokeh 项目的一个 minor milestone，围绕"更自由的界面布局、更顺滑的交互体验、更丰富的文本与数据表现力"三条主线，带来了浮动 UI 元素与节点定位系统、零延迟 tap 手势、xor 选择模式、TeXGlyph/MathMLGlyph数学文本字形、CategoricalSlider等一大批新特性。本文以官方发布说明为骨架，结合本仓库源码逐一展开这些能力的用法、底层实现与迁移注意事项，帮助你快速掌握 3.4.0 的核心增量，并平滑完成从旧 API 的升级。

一、版本定位与更新总览

根据发布说明（docs/bokeh/source/docs/releases/3.4.0.rst），Bokeh3.4.0是一次 minor milestone 更新，新增能力可归纳为以下几个方向：

下面按主题逐一展开，所有配置项与默认值均以仓库源码为准。

二、浮动 UI 元素与节点定位系统（PR #13538）

1. 核心模型Dialog

发布说明中"floating UI elements (e.g.Dialog) and node positioning system"对应源码中的Dialog模型，它是一个"floating, movable and resizable container for UI elements"（可浮动、可移动、可缩放的 UI 容器），从UIElement派生。注意官方在模型 docstring 中明确提示：该模型及其所有属性目前是 experimental，未来可能调整。

Dialog的核心属性如下（均可在 dialogs.py 中查到默认值）：

• title：对话框标题，可以是纯文本字符串、DOMNode、UIElement或布局对象；
• content（必填）：对话框内容，同样支持字符串 /DOMNode/UIElement/ 布局；
• pinnable = True：是否允许"钉住"对话框，被钉住的对话框始终位于其他对话框之上，钉住一个会取消其他对话框的钉住状态；
• collapsible = True：是否允许折叠，折叠后只显示标题（在标题上滚动即可折叠），便于让开下方 UI；
• minimizable = True：是否允许最小化，最小化会将对话框折叠并移动到视口左下角的"最小化区域"；
• maximizable = True：是否允许最大化，最大化后覆盖整个视口，多个对话框可同时最大化但只有一个位于顶层；
• closable = True：是否允许关闭；close_action决定关闭后的行为，取值为"hide"（从 DOM 移除但保留视图与状态，可再次打开）或"destroy"（销毁视图与状态，重新打开需重建），默认"destroy"；
• resizable = "all"：缩放方向，枚举类型Resizable；
• movable = "both"：移动方向，枚举类型Movable；
• symmetric = False：缩放一个边/角时是否同步影响对边/对角；
• top_limit/bottom_limit/left_limit/right_limit：可选移动/缩放边界（Node实例），共同构成对话框移动与缩放的包围盒。

一个典型用法是把Dialog与Button的点击回调结合，动态打开/关闭：

from bokeh.io import show from bokeh.models import Button, Dialog, Div from bokeh.layouts import column dialog = Dialog(title="提示", content=Div(text="<b>这是一个浮动对话框</b>"), closable=True) button = Button(label="打开对话框") button.js_on_click(dialog.js_open()) # 打开对话框 show(column(button, dialog))

2. 节点定位系统Node/Coordinate

"node positioning system" 的落地是Node与Coordinate两个模型。Coordinate是Model的子类，Node继承自Coordinate，用于把 UI 元素/标注的锚点绑定到绘图帧的某个位置（例如与某条轴范围或坐标关联），从而让浮动元素跟随数据位置移动。它与Dialog的top_limit等属性配合，可以实现"对话框只能在绘图区域内移动/缩放"之类的约束。

三、交互升级：零延迟 tap 与全新的选择模式（PR #12831、#13545）

1. 零延迟 tap 手势

发布说明指出 3.4.0 "Redesigned UI gesture handling and added support for zero latency tap"。手势处理管线被重新设计，tap 不再等待"判断是否拖拽"的防抖延迟，点击即可立即触发，显著降低了TapTool等工具的响应延迟，适合对点击反馈敏感的仪表盘场景。

2. xor 选择模式与选择反转

选择工具的mode属性支持的选择模式枚举定义在 enums.py：

type RegionSelectionModeType = Literal["replace", "append", "intersect", "subtract", "xor"] type SelectionModeType = Literal[RegionSelectionModeType, "toggle"]

即：replace（替换）、append（追加）、intersect（取交集）、subtract（减去）、xor（异或）以及toggle（切换）。3.4.0 新增了xor模式，并支持选择反转（invert selection，仅对点选择生效）。以TapTool为例（tools.py）：

from bokeh.models import TapTool tool = TapTool(mode="xor") # 点击已选中的点会取消其选中，实现"点选/取消"

发布说明特别提到 3.4.0 将TapTool的默认选择模式改为"xor"，从而允许通过再次点击来取消选中。需要说明的是：从当前仓库源码（tools.py）看，TapTool.mode的默认值写为"toggle"，这提示后续版本可能对默认值又做了调整；如果你依赖"点击取消选中"的行为，建议在代码中显式指定mode="xor"，而非依赖默认值。

3. 工具显隐控制：Tool.visible

3.4.0 为工具基类新增了visible = Bool(default=True)属性（tools.py），可以在不销毁工具对象的前提下将其从工具栏隐藏；同时InspectTool.toggleable被标记为弃用。典型用法：

from bokeh.models import HoverTool hover = HoverTool(visible=False) # 默认隐藏，需要时再置 True

四、Label与Title的视觉增强（PR #12825）

1.padding与border_radius

3.4.0 为Label和Title增加了padding、border_radius等样式属性，源码位于 annotations/labels.py：

from bokeh.models import Label label = Label( x=10, y=80, text="带背景的标签", background_fill_color="navy", background_fill_alpha=0.3, border_line_color="black", padding=10, # 背景内边距 border_radius=5, # 背景圆角 )

这些属性与已有的background_fill_*、border_line_*视觉属性配合，可以快速做出"胶囊/圆角卡片"式的标签外观，而不再需要手工拼接矩形与文本。

2.editable=True时支持旋转交互

同一 PR 还让Label在editable=True时支持旋转：用户在浏览器中拖动旋转手柄即可改变标签角度，适用于地图标注、示意图等需要现场微调角度的场景。

五、数学文本字形：TeXGlyph与MathMLGlyph（PR #13612）

3.4.0 新增了基于数学排版的内容字形，定义于 glyphs.py：

• MathTextGlyph：抽象基类，继承自Text；
• TeXGlyph：使用 LaTeX 记法渲染数学内容，底层依赖 MathJax（官方 docstring 提示 MathJax 只支持数学模式宏，不支持文本模式宏，与标准 TeX/LaTeX 存在差异）；
• MathMLGlyph：使用 MathML 记法渲染。

两者都继承Text的全部文本属性（字体、颜色、背景填充、边框、hatch 等），可像普通文本字形一样放在figure上：

from bokeh.models import TeXGlyph p = figure(width=400, height=200) p.add_glyph(TeXGlyph( x=0.5, y=0.5, text=r"$E = mc^2$", text_font_size="24px", ))

这填补了此前只能通过Label/MathText注解渲染公式、而无法把公式作为数据字形参与缩放/点击的空白。

六、新控件与更名

1.CategoricalSlider（PR #13489）

新增的分类滑条，源码在 widgets/sliders.py，用于从一组离散取值中选择：

from bokeh.models import CategoricalSlider slider = CategoricalSlider( categories=["低", "中", "高"], value="中", )

属性说明：

• categories（必填，Seq(String)）：可选的分类集合；
• value（必填，String）：初始或当前选中值；
• value_throttled（只读，必填）：节流后的选中值，用于只在滑块停止时触发回调的场景（与数值Slider的value_throttled语义一致，参见同文件 sliders.py）。

2.ColorMap更名为PaletteSelect（PR #13537）

颜色映射控件ColorMap在 3.4.0 中更名为PaletteSelect（widgets/inputs.py），旧名称不再可用。若你的代码中使用过ColorMap，升级时需改为：

from bokeh.models import PaletteSelect

七、数据层增强

1.ColumnDataSource列默认值与编辑工具（PR #13518）

3.4.0 为ColumnDataSource增加了列默认值支持，并与编辑工具（如PointDrawTool、BoxEditTool、PolyDrawTool等）打通：当用户通过编辑工具新增数据点时，未显式提供的列会回落到默认值，避免因缺列导致新增点渲染失败或报错。这对于"带分类/时间戳列的增量编辑"场景非常实用。

2. 非视觉字形数据属性覆盖（PR #13554）

支持对字形的非视觉数据属性进行覆盖（non-visual glyph data property overrides），例如在CDSView或多数据源场景下，为部分字形单独指定数据列而不影响其视觉样式，进一步解耦"数据"与"样式"。

3.StaticLayoutProvider支持字符串节点（PR #13618）

图布局提供器StaticLayoutProvider在 3.4.0 起支持以字符串作为节点标识来提供坐标，此前只能使用整数索引。现在可以这样布局图：

from bokeh.models import StaticLayoutProvider provider = StaticLayoutProvider( graph_layout={ "A": (0, 0), "B": (1, 1), "C": (2, 0), }, )

字符串键与GraphRenderer的节点/边数据列（如"index"列存字符串）直接对应，大大提高了图数据与外部系统（如社交网络、知识图谱）对接的便利性。

4.ScaleBar自定义计量单位（PR #13625）

比例尺标注ScaleBar新增自定义单位支持：

• unit（默认"m"）：range属性的单位字符串，例如"km"、"ft"、"mi"；
• dimensional：计量维度模型（默认MetricLength实例），定义单位体系；当unit不属于该维度时，会触发NON_MATCHING_SCALE_BAR_UNIT校验错误（见 legends.py）；
• range（默认"auto"）：显示比例所依据的坐标轴范围，"auto"时根据方向自动选择默认的 x/y 范围；
• orientation：水平或垂直；
• location（默认"top_right"）、x_units/y_units（默认"data"）、anchor（默认"auto"）：控制比例尺在绘图帧内的摆放与锚定；
• length_sizing（"adaptive"/"exact"）与bar_length（默认0.2）：控制比例条长度的自适应取整或精确取值。

例如在地图场景中显示"5 公里"：

from bokeh.models import ScaleBar scale_bar = ScaleBar( unit="km", dimensional=__import__("bokeh.core.property.vectorization", fromlist=[""]), # 示意 orientation="horizontal", location="bottom_right", )

（dimensional通常由 bokeh 提供的单位模型直接传入，这里仅示意字段结构；实际使用时请参考 ug_styling_plots 用户手册中 ScaleBar 相关章节。）

5.DataTable单元格格式化样式增强（PR #13685）

3.4.0 改进了DataTable单元格格式化器的样式支持，例如对数值格式、日期格式列可以配置字体、对齐等视觉属性，使表格与整体主题更统一。

八、工程与平台级改进

1. 开发资源默认值（PR #13042）

BOKEH_DEV=true现在默认启用server development resources（开发服务器资源），开发者在修改 bokehjs 源码后无需手工切换资源模式即可获得带源码映射的开发构建，调试体验更顺滑。

2. bokehjs 代码质量与构建目标

• strict mode：bokehjs 的 bundle 全面启用 JavaScript"use strict";（PR #13523），更早暴露隐式全局变量等隐患；
• ES2020 目标：bokehjs 构建从 ES2017 迁移到 ES2020（PR #13565），可安全使用可选链、空值合并等现代语法；
• 统一 API 处理：bokehjs 各 API 统一了普通对象与Map对象的处理（PR #13696）；
• 唯一 CSS-safe 标识符：所有 Bokeh 生成的 DOM 元素改用全局唯一且 CSS-safe 的 id（PR #13636），避免多个图表共存时的 id 冲突与 CSS 选择器转义问题；
• @bokeh/bokehjs元包依赖恢复：bokehjs 的元包依赖被恢复（PR #13715），npm install @bokeh/bokehjs可正常拉齐依赖。

3. Unicode 名称占位符（PR #13723）

HoverTool等使用的占位符语法支持 Unicode 名称，例如数据列名为"温度(°C)"时可直接写@温度(°C)或使用 Unicode 别名，不再受 ASCII 限制。

4. 后端修复

• WebGL 后端：多项 bug 修复（PR #13482、#13649、#13651、#13684），覆盖大数量级点/线渲染与混合问题；
• SVG 后端：多项 bug 修复（PR #13363、#13640），改善矢量导出的一致性。

九、弃用与迁移指南

figure.circle(size=...)弃用（PR #13283）

figure.circle(size=10)形式被弃用，统一改用figure.scatter(size=10)。在 glyph_api.py 中可以看到兼容逻辑：调用circle()且传入size时，会触发deprecated((3, 4, 0), ...)警告并自动转发到scatter()；若同时传入size与radius则抛出ValueError。迁移方式：

# 旧写法（3.4.0 起弃用） p.circle(x, y, size=10, color="red") # 新写法 p.scatter(x, y, size=10, color="red")

其他迁移注意点汇总：

• ColorMap→PaletteSelect；
• InspectTool.toggleable→ 使用Tool.visible；
• 依赖TapTool默认"点击取消选中"行为的代码，建议显式TapTool(mode="xor")；
• Dialog及其定位系统为 experimental，生产使用前请关注后续版本兼容性。

十、总结

Bokeh 3.4.0 是一次"交互体验 + 表现力 + 工程化"并重的版本：Dialog与节点定位让仪表盘可以像桌面应用一样管理浮动面板；xor 选择模式与零延迟 tap 让选择交互更跟手；TeXGlyph/MathMLGlyph让数学内容直接成为可缩放、可拾取的数据字形；CategoricalSlider、PaletteSelect、ScaleBar自定义单位与DataTable样式增强则补齐了高频业务场景的细节。同时，strict mode、ES2020、唯一 DOM id 等工程改进为 bokehjs 后续迭代打下更稳的基础。升级到 3.4.0 时，重点核对circle(size=...)、ColorMap与InspectTool.toggleable三处弃用点，即可平稳过渡。

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