Bokeh 3.4.0 版本全解析浮动 UI、零延迟交互与数学文本渲染的新里程碑【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh导读Bokeh 3.4.02024 年 3 月发布是 Bokeh 项目的一个 minor milestone围绕更自由的界面布局、更顺滑的交互体验、更丰富的文本与数据表现力三条主线带来了浮动 UI 元素与节点定位系统、零延迟 tap 手势、xor 选择模式、TeXGlyph/MathMLGlyph数学文本字形、CategoricalSlider等一大批新特性。本文以官方发布说明为骨架结合本仓库源码逐一展开这些能力的用法、底层实现与迁移注意事项帮助你快速掌握 3.4.0 的核心增量并平滑完成从旧 API 的升级。一、版本定位与更新总览根据发布说明docs/bokeh/source/docs/releases/3.4.0.rstBokeh3.4.0是一次 minor milestone 更新新增能力可归纳为以下几个方向方向代表性新特性UI 与布局浮动 UI 元素Dialog与节点定位系统交互与选择零延迟 tap、xor 选择模式、选择反转、Tool.visible文本与标注Label/Title的padding、border_radius、可旋转编辑TeXGlyph/MathMLGlyph控件与数据CategoricalSlider、PaletteSelect由ColorMap更名、数据列默认值工程与平台strict mode、ES2020 目标、CSS-safe 唯一 DOM id、WebGL/SVG 大量修复下面按主题逐一展开所有配置项与默认值均以仓库源码为准。二、浮动 UI 元素与节点定位系统PR #135381. 核心模型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是否允许折叠折叠后只显示标题在标题上滚动即可折叠便于让开下方 UIminimizable True是否允许最小化最小化会将对话框折叠并移动到视口左下角的最小化区域maximizable True是否允许最大化最大化后覆盖整个视口多个对话框可同时最大化但只有一个位于顶层closable True是否允许关闭close_action决定关闭后的行为取值为hide从 DOM 移除但保留视图与状态可再次打开或destroy销毁视图与状态重新打开需重建默认destroyresizable all缩放方向枚举类型Resizablemovable both移动方向枚举类型Movablesymmetric 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提示, contentDiv(textb这是一个浮动对话框/b), closableTrue) button Button(label打开对话框) button.js_on_click(dialog.js_open()) # 打开对话框 show(column(button, dialog))2. 节点定位系统Node/Coordinatenode positioning system 的落地是Node与Coordinate两个模型。Coordinate是Model的子类Node继承自Coordinate用于把 UI 元素/标注的锚点绑定到绘图帧的某个位置例如与某条轴范围或坐标关联从而让浮动元素跟随数据位置移动。它与Dialog的top_limit等属性配合可以实现对话框只能在绘图区域内移动/缩放之类的约束。三、交互升级零延迟 tap 与全新的选择模式PR #12831、#135451. 零延迟 tap 手势发布说明指出 3.4.0 Redesigned UI gesture handling and added support for zero latency tap。手势处理管线被重新设计tap 不再等待判断是否拖拽的防抖延迟点击即可立即触发显著降低了TapTool等工具的响应延迟适合对点击反馈敏感的仪表盘场景。2. xor 选择模式与选择反转选择工具的mode属性支持的选择模式枚举定义在 enums.pytype 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.pyfrom bokeh.models import TapTool tool TapTool(modexor) # 点击已选中的点会取消其选中实现点选/取消发布说明特别提到 3.4.0 将TapTool的默认选择模式改为xor从而允许通过再次点击来取消选中。需要说明的是从当前仓库源码tools.py看TapTool.mode的默认值写为toggle这提示后续版本可能对默认值又做了调整如果你依赖点击取消选中的行为建议在代码中显式指定modexor而非依赖默认值。3. 工具显隐控制Tool.visible3.4.0 为工具基类新增了visible Bool(defaultTrue)属性tools.py可以在不销毁工具对象的前提下将其从工具栏隐藏同时InspectTool.toggleable被标记为弃用。典型用法from bokeh.models import HoverTool hover HoverTool(visibleFalse) # 默认隐藏需要时再置 True四、Label与Title的视觉增强PR #128251.padding与border_radius3.4.0 为Label和Title增加了padding、border_radius等样式属性源码位于 annotations/labels.pyfrom bokeh.models import Label label Label( x10, y80, text带背景的标签, background_fill_colornavy, background_fill_alpha0.3, border_line_colorblack, padding10, # 背景内边距 border_radius5, # 背景圆角 )这些属性与已有的background_fill_*、border_line_*视觉属性配合可以快速做出胶囊/圆角卡片式的标签外观而不再需要手工拼接矩形与文本。2.editableTrue时支持旋转交互同一 PR 还让Label在editableTrue时支持旋转用户在浏览器中拖动旋转手柄即可改变标签角度适用于地图标注、示意图等需要现场微调角度的场景。五、数学文本字形TeXGlyph与MathMLGlyphPR #136123.4.0 新增了基于数学排版的内容字形定义于 glyphs.pyMathTextGlyph抽象基类继承自TextTeXGlyph使用 LaTeX 记法渲染数学内容底层依赖 MathJax官方 docstring 提示 MathJax 只支持数学模式宏不支持文本模式宏与标准 TeX/LaTeX 存在差异MathMLGlyph使用 MathML 记法渲染。两者都继承Text的全部文本属性字体、颜色、背景填充、边框、hatch 等可像普通文本字形一样放在figure上from bokeh.models import TeXGlyph p figure(width400, height200) p.add_glyph(TeXGlyph( x0.5, y0.5, textr$E mc^2$, text_font_size24px, ))这填补了此前只能通过Label/MathText注解渲染公式、而无法把公式作为数据字形参与缩放/点击的空白。六、新控件与更名1.CategoricalSliderPR #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更名为PaletteSelectPR #13537颜色映射控件ColorMap在 3.4.0 中更名为PaletteSelectwidgets/inputs.py旧名称不再可用。若你的代码中使用过ColorMap升级时需改为from bokeh.models import PaletteSelect七、数据层增强1.ColumnDataSource列默认值与编辑工具PR #135183.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默认mrange属性的单位字符串例如km、ft、midimensional计量维度模型默认MetricLength实例定义单位体系当unit不属于该维度时会触发NON_MATCHING_SCALE_BAR_UNIT校验错误见 legends.pyrange默认auto显示比例所依据的坐标轴范围auto时根据方向自动选择默认的 x/y 范围orientation水平或垂直location默认top_right、x_units/y_units默认data、anchor默认auto控制比例尺在绘图帧内的摆放与锚定length_sizingadaptive/exact与bar_length默认0.2控制比例条长度的自适应取整或精确取值。例如在地图场景中显示5 公里from bokeh.models import ScaleBar scale_bar ScaleBar( unitkm, dimensional__import__(bokeh.core.property.vectorization, fromlist[]), # 示意 orientationhorizontal, locationbottom_right, )dimensional通常由 bokeh 提供的单位模型直接传入这里仅示意字段结构实际使用时请参考 ug_styling_plots 用户手册中 ScaleBar 相关章节。5.DataTable单元格格式化样式增强PR #136853.4.0 改进了DataTable单元格格式化器的样式支持例如对数值格式、日期格式列可以配置字体、对齐等视觉属性使表格与整体主题更统一。八、工程与平台级改进1. 开发资源默认值PR #13042BOKEH_DEVtrue现在默认启用server development resources开发服务器资源开发者在修改 bokehjs 源码后无需手工切换资源模式即可获得带源码映射的开发构建调试体验更顺滑。2. bokehjs 代码质量与构建目标strict modebokehjs 的 bundle 全面启用 JavaScriptuse strict;PR #13523更早暴露隐式全局变量等隐患ES2020 目标bokehjs 构建从 ES2017 迁移到 ES2020PR #13565可安全使用可选链、空值合并等现代语法统一 API 处理bokehjs 各 API 统一了普通对象与Map对象的处理PR #13696唯一 CSS-safe 标识符所有 Bokeh 生成的 DOM 元素改用全局唯一且 CSS-safe 的 idPR #13636避免多个图表共存时的 id 冲突与 CSS 选择器转义问题bokeh/bokehjs元包依赖恢复bokehjs 的元包依赖被恢复PR #13715npm install bokeh/bokehjs可正常拉齐依赖。3. Unicode 名称占位符PR #13723HoverTool等使用的占位符语法支持 Unicode 名称例如数据列名为温度(°C)时可直接写温度(°C)或使用 Unicode 别名不再受 ASCII 限制。4. 后端修复WebGL 后端多项 bug 修复PR #13482、#13649、#13651、#13684覆盖大数量级点/线渲染与混合问题SVG 后端多项 bug 修复PR #13363、#13640改善矢量导出的一致性。九、弃用与迁移指南figure.circle(size...)弃用PR #13283figure.circle(size10)形式被弃用统一改用figure.scatter(size10)。在 glyph_api.py 中可以看到兼容逻辑调用circle()且传入size时会触发deprecated((3, 4, 0), ...)警告并自动转发到scatter()若同时传入size与radius则抛出ValueError。迁移方式# 旧写法3.4.0 起弃用 p.circle(x, y, size10, colorred) # 新写法 p.scatter(x, y, size10, colorred)其他迁移注意点汇总ColorMap→PaletteSelectInspectTool.toggleable→ 使用Tool.visible依赖TapTool默认点击取消选中行为的代码建议显式TapTool(modexor)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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考