Bokeh 3.5.0 新特性深度解析交互注解、工具手势与事件 API 实战指南【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh导读Bokeh 3.5.02024 年 7 月发布是 Bokeh 项目的一个小型里程碑版本集中强化了浏览器端交互能力BoxAnnotation新增反选与拖拽手柄、滚轮工具支持修饰键与子坐标命中、图例与输入控件新增事件 API。本文以官方发布说明 docs/bokeh/source/docs/releases/3.5.0.rst 为主线结合当前仓库源码逐条解析这些新特性并给出可直接运行的配置示例帮助你在实际项目中准确使用这些能力。版本概览Bokeh3.5.0是 2024 年 7 月发布的小型里程碑版本核心方向是增强交互工具的可配置性与扩展注解/控件的事件能力同时完成了对旧版 Python 的清理。完整变更清单可在 docs/bokeh/source/docs/releases/3.5.0.rst 查看。本版本所有新增属性均在 Python 模型层src/bokeh/models定义经由现有序列化通道自动同步到 BokehJS 前端因此你只需在 Python 侧配置即可获得浏览器端交互效果。BoxAnnotation反选几何与交互手柄inverted属性让填充作用到矩形外部3.5.0 为BoxAnnotation新增了inverted布尔属性对应 PR #13810。在源码 src/bokeh/models/annotations/geometry.py#L318-L322 中定义如下inverted Bool(defaultFalse, help Inverts the geometry of the box, i.e. applies fill and hatch visuals to the outside of the box instead of the inside. Visuals are applied between the box and its parent, e.g. the frame. )默认False时BoxAnnotation在矩形内部绘制填充与填充纹理设置为True后视觉效果被应用到矩形外部矩形与其父容器——通常是绘图 frame——之间的区域。典型场景是排除法高亮例如在时间序列中高亮非工作时段只需在相应区间上放置一个invertedTrue的盒子其余区域自动被罩上底色。参考示例 examples/basic/annotations/box_annotation.py 中BoxAnnotation的基本用法在此基础上增加一个参数即可from bokeh.models import BoxAnnotation box BoxAnnotation( left5, right15, fill_color#ef6548, fill_alpha0.4, invertedTrue, # 3.5.0 新增填充 box 外部区域 )editable交互手柄体系同版本还引入了BoxAnnotation的交互手柄能力PR #13906。结合 src/bokeh/models/annotations/geometry.py#L262-L316 中的定义相关属性包括属性默认值作用editableFalse是否允许用户交互式修改盒子的几何形状resizableall允许调整尺寸的边组合限制缩放方向movableboth允许移动的方向水平/垂直symmetricFalse围绕中心还是围绕角落缩放use_handlesFalse是否显示独立的手柄为False时整个盒子含边框与四角都充当手柄handles默认BoxInteractionHandles手柄外观配置可分级覆盖all→move/resize→sides/corners→ 具体边/角min_width/min_height/max_width/max_height0/0/inf/inf盒子尺寸上下限left_limit/right_limit/top_limit/bottom_limitNone各方向移动边界实验性border_radius0圆角配合RangeTool使用editable盒子可打造可拖拽的选区面板交互式示例见 examples/interaction/annotations/editable_box_annotation.py。需要说明的是上述交互属性在源码注释中均标注为experimental and may change at any point生产使用前请留意后续版本变更。滚轮工具修饰键、自动激活与子坐标命中为 WheelZoomTool / WheelPanTool 配置修饰键3.5.0 允许为WheelZoomTool和WheelPanTool设置修饰键组合PR #13815只有在按住指定按键的同时滚动滚轮工具才会触发。modifiers属性定义于 src/bokeh/models/tools.py#L763-L790WheelZoomTool与 src/bokeh/models/tools.py#L624-L651WheelPanTool支持两种等价的写法from bokeh.models import WheelZoomTool, WheelPanTool # 方式一字典 tool WheelZoomTool(modifiersdict(ctrlTrue, shiftTrue)) # 方式二字符串由 _parse_modifiers 解析 tool WheelPanTool(modifiersctrlshift) plot.add_tools(tool)从 src/bokeh/models/tools.py#L169-L179 的_parse_modifiers解析器可见字符串形式支持alt、ctrl、shift三个键位遇到未知键名会抛出ValueError。modifiers属性的帮助文档同时给出了两点重要提示自动激活设置修饰键后若Toolbar.active_scroll设为auto该滚轮工具会被自动激活平台相关性警告修饰键是平台相关特性例如在移动设备上可能完全不可用。这一特性可有效缓解同一图表既要滚轮缩放又要页面滚动的冲突场景例如按住Ctrl滚轮缩放、直接滚动翻页。子坐标下的光标处缩放配合复合比例尺sub-coordinates场景3.5.0 支持滚轮缩放光标正下方的渲染器PR #13826。WheelZoomTool为此提供了两组属性见 src/bokeh/models/tools.py#L687-L728level配置缩放作用于哪一组范围默认缩放顶层 frame 范围hit_test是否只缩放被指针命中的渲染器默认False仅对配置了子坐标的渲染器生效hit_test_mode命中测试几何取point、hline、vlinehit_test_behavior命中后缩放哪些渲染器可传GroupBy模型实现命中一个、联动一组。这三个属性在源码中标注为实验性。此外WheelZoomTool还支持speed默认1/600建议区间0.0010.09、zoom_on_axis、zoom_togethernone/cross/all等细粒度控制。RangeTool可配置的范围设定手势RangeTool在 3.5.0 中新增start_gesture属性PR #13855允许选择在何处用何种手势开始一个新范围的交互方式。RangeTool本身是Drag工具的子类src/bokeh/models/tools.py#L523-L587其核心属性包括x_range/y_range与 overlay 同步的范围对象为None时 overlay 铺满对应维度overlay默认的BoxAnnotation用于可视化当前范围x_interaction/y_interaction是否响应对应维度的平移调整拖拽 box 内部或上下边start_gesturepan、tap或none默认none。start_gesture的语义src/bokeh/models/tools.py#L579-L587pan指针开始拖拽的位置即新范围的起点拖拽过程中范围连续更新松手确定终值tap在某个位置点击即开始新范围none不使用手势在当前视图内新建范围范围只能通过拖拽既有 overlay 边界调整。典型应用是联动缩放大图在大图上放置RangeTool将x_range绑定到小图的x_range用户拖拽/点击即可控制小图的显示窗口from bokeh.models import RangeTool range_tool RangeTool(x_rangeplot_small.x_range, start_gesturetap) plot_large.add_tools(range_tool)文本类字形可定制的轮廓形状Text、TeX、MathML等文本类字形新增outline_shape属性PR #13620允许为文本的外轮廓选择预定义形状。实现位于 src/bokeh/models/glyphs.py#L1733-L1751outline_shape DataSpec(Enum(OutlineShapeName), defaultbox, help Specify the shape of the outline for the text box. The default outline is of a text box is its bounding box (or rectangle). This can be changed to a selection of pre-defined shapes, like circle, ellipse, diamond, parallelogram, etc. Those shapes are circumscribed onto the bounding box, so that the contents of a box fit inside those shapes. )要点如下默认box即文本的包围矩形可选circle、ellipse、diamond、parallelogram等形状这些形状外接于包围盒保证文本内容仍在形状内部该属性仅在设置了边框线border_line_*、背景填充background_fill_*或背景填充纹理background_hatch_*时才生效设为none可完全禁用轮廓绘制目前命中测试仍基于文本内容的包围盒等价于box形状这是源码中明确标注的限制该属性为实验性可能随版本调整。搭配padding与border_radius圆角使用可获得更精细的标注效果。Legend点击事件 API3.5.0 为Legend增加条目点击事件及配套 APIPR #13922。在 src/bokeh/models/annotations/legends.py#L575-L579 中新增了两个方法def on_click(self, handler: PyEventCallback) - None: ... def js_on_click(self, handler: JsEventCallback) - None: ...用法与 Bokeh 既有的事件回调约定一致from bokeh.models import Legend def handle_legend_click(event): print(fclicked on legend item: {event}) legend Legend(items[...]) legend.on_click(handle_legend_click) # Python 回调需运行 Bokeh Server legend.js_on_click(customjs_callback) # JavaScript 回调纯前端可用结合Legend.click_policynone/hide/mute见 src/bokeh/models/annotations/legends.py#L480现在可以在用户点击图例条目的同时触发自定义的数据联动或业务逻辑例如联动外部表格高亮、统计选中项等。FileInput目录上传支持FileInput控件新增directory属性PR #13873允许用户选择一个目录而非单个/多个文件。源码定义位于 src/bokeh/models/widgets/inputs.py#L207-L224multiple Bool(defaultFalse, help set multipleFalse (default) for single file selection, set multipleTrue if ...) directory Bool(defaultFalse, help ... The filename will be relative paths to the uploaded directory. ...)使用注意启用directoryTrue后上传的是目录内全部文件filename将保存为相对于所选目录的相对路径上传目录时会弹出确认对话框源码注释明确指出accept参数只对文件扩展名生效且与directory组合使用时被接受文件的数量语义会不同需要结合实际需求验证过滤行为。FileInput的只读输出属性valuebase64 编码内容、mime_type、filename见 src/bokeh/models/widgets/inputs.py#L137-L167在目录模式下会相应变为列表形态注意按列表处理。ClearInput服务端事件驱动的输入清空3.5.0 扩展了服务端事件server-sent events的支持其中代表性事件是作用于输入控件的ClearInputPR #13890。该能力面向Bokeh Server架构服务端 Python 代码可以将清空输入框作为事件推送到前端实现跨会话的联动——例如在协作面板中某位用户点击重置后其他用户的输入控件同步清空。相关服务端基础设施可参考 src/bokeh/server 目录的会话实现输入控件模型则集中在 src/bokeh/models/widgets。ValueRef 格式化器与 HoverTool 模板增强ValueRef模型用于Slope、Whisker、Band等注解的标签文本新增了格式化器支持同时HoverTool的工具提示模板能力得到改进PR #13650。这意味着注解标签与悬浮提示现在可以更灵活地控制数值显示格式而不仅限于field占位符。相关交互式示例可参考 examples/interaction/tools/hover_tooltip_formatting.py 与 examples/interaction/tools/hover_tooltip_advanced.py。CSS 变量驱动的渲染器样式3.5.0 为绘图渲染器renderers新增了基于CSS 变量的样式能力PR #13828。该特性的模型基础位于 src/bokeh/models/css.py其中定义了如outline_color、outline_width等与 CSS 轮廓属性对应的模型字段见 src/bokeh/models/css.py#L344-L347。其价值在于将部分视觉属性交给浏览器 CSS 层接管后可以通过主题、媒体查询等方式统一切换外观而无需重建图形对象。css相关模型同时出现在 src/bokeh/models/css.pyi 的类型声明中供类型检查使用。Python 版本支持变更3.5.0移除了对 Python 3.9 的支持并对代码库进行了现代化改造PR #13634。在当前仓库的 pyproject.toml#L10 中可见requires-python 3.12这意味着当前代码库要求 Python 3.12 及以上版本。如果你正在维护依赖 Bokeh 3.5.0 的应用请确保运行环境满足该版本要求并留意因代码现代化类型注解、语法更新等带来的潜在兼容性变化。小结Bokeh 3.5.0 的变更集中在四个方向注解交互增强BoxAnnotation.inverted与手柄体系、文本轮廓形状、工具手势精细化滚轮修饰键、RangeTool.start_gesture、子坐标命中缩放、事件 API 扩展Legend.on_click/js_on_click、ClearInput服务端事件、以及样式与平台现代化CSS 变量、Python 3.12。动手验证时可直接在 Python 3.12 环境安装本仓库并运行 examples/basic/annotations 与 examples/interaction 下的示例多数新特性一两个参数即可复现。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Bokeh 3.5.0 新特性深度解析：交互注解、工具手势与事件 API 实战指南
Bokeh 3.5.0 新特性深度解析交互注解、工具手势与事件 API 实战指南【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh导读Bokeh 3.5.02024 年 7 月发布是 Bokeh 项目的一个小型里程碑版本集中强化了浏览器端交互能力BoxAnnotation新增反选与拖拽手柄、滚轮工具支持修饰键与子坐标命中、图例与输入控件新增事件 API。本文以官方发布说明 docs/bokeh/source/docs/releases/3.5.0.rst 为主线结合当前仓库源码逐条解析这些新特性并给出可直接运行的配置示例帮助你在实际项目中准确使用这些能力。版本概览Bokeh3.5.0是 2024 年 7 月发布的小型里程碑版本核心方向是增强交互工具的可配置性与扩展注解/控件的事件能力同时完成了对旧版 Python 的清理。完整变更清单可在 docs/bokeh/source/docs/releases/3.5.0.rst 查看。本版本所有新增属性均在 Python 模型层src/bokeh/models定义经由现有序列化通道自动同步到 BokehJS 前端因此你只需在 Python 侧配置即可获得浏览器端交互效果。BoxAnnotation反选几何与交互手柄inverted属性让填充作用到矩形外部3.5.0 为BoxAnnotation新增了inverted布尔属性对应 PR #13810。在源码 src/bokeh/models/annotations/geometry.py#L318-L322 中定义如下inverted Bool(defaultFalse, help Inverts the geometry of the box, i.e. applies fill and hatch visuals to the outside of the box instead of the inside. Visuals are applied between the box and its parent, e.g. the frame. )默认False时BoxAnnotation在矩形内部绘制填充与填充纹理设置为True后视觉效果被应用到矩形外部矩形与其父容器——通常是绘图 frame——之间的区域。典型场景是排除法高亮例如在时间序列中高亮非工作时段只需在相应区间上放置一个invertedTrue的盒子其余区域自动被罩上底色。参考示例 examples/basic/annotations/box_annotation.py 中BoxAnnotation的基本用法在此基础上增加一个参数即可from bokeh.models import BoxAnnotation box BoxAnnotation( left5, right15, fill_color#ef6548, fill_alpha0.4, invertedTrue, # 3.5.0 新增填充 box 外部区域 )editable交互手柄体系同版本还引入了BoxAnnotation的交互手柄能力PR #13906。结合 src/bokeh/models/annotations/geometry.py#L262-L316 中的定义相关属性包括属性默认值作用editableFalse是否允许用户交互式修改盒子的几何形状resizableall允许调整尺寸的边组合限制缩放方向movableboth允许移动的方向水平/垂直symmetricFalse围绕中心还是围绕角落缩放use_handlesFalse是否显示独立的手柄为False时整个盒子含边框与四角都充当手柄handles默认BoxInteractionHandles手柄外观配置可分级覆盖all→move/resize→sides/corners→ 具体边/角min_width/min_height/max_width/max_height0/0/inf/inf盒子尺寸上下限left_limit/right_limit/top_limit/bottom_limitNone各方向移动边界实验性border_radius0圆角配合RangeTool使用editable盒子可打造可拖拽的选区面板交互式示例见 examples/interaction/annotations/editable_box_annotation.py。需要说明的是上述交互属性在源码注释中均标注为experimental and may change at any point生产使用前请留意后续版本变更。滚轮工具修饰键、自动激活与子坐标命中为 WheelZoomTool / WheelPanTool 配置修饰键3.5.0 允许为WheelZoomTool和WheelPanTool设置修饰键组合PR #13815只有在按住指定按键的同时滚动滚轮工具才会触发。modifiers属性定义于 src/bokeh/models/tools.py#L763-L790WheelZoomTool与 src/bokeh/models/tools.py#L624-L651WheelPanTool支持两种等价的写法from bokeh.models import WheelZoomTool, WheelPanTool # 方式一字典 tool WheelZoomTool(modifiersdict(ctrlTrue, shiftTrue)) # 方式二字符串由 _parse_modifiers 解析 tool WheelPanTool(modifiersctrlshift) plot.add_tools(tool)从 src/bokeh/models/tools.py#L169-L179 的_parse_modifiers解析器可见字符串形式支持alt、ctrl、shift三个键位遇到未知键名会抛出ValueError。modifiers属性的帮助文档同时给出了两点重要提示自动激活设置修饰键后若Toolbar.active_scroll设为auto该滚轮工具会被自动激活平台相关性警告修饰键是平台相关特性例如在移动设备上可能完全不可用。这一特性可有效缓解同一图表既要滚轮缩放又要页面滚动的冲突场景例如按住Ctrl滚轮缩放、直接滚动翻页。子坐标下的光标处缩放配合复合比例尺sub-coordinates场景3.5.0 支持滚轮缩放光标正下方的渲染器PR #13826。WheelZoomTool为此提供了两组属性见 src/bokeh/models/tools.py#L687-L728level配置缩放作用于哪一组范围默认缩放顶层 frame 范围hit_test是否只缩放被指针命中的渲染器默认False仅对配置了子坐标的渲染器生效hit_test_mode命中测试几何取point、hline、vlinehit_test_behavior命中后缩放哪些渲染器可传GroupBy模型实现命中一个、联动一组。这三个属性在源码中标注为实验性。此外WheelZoomTool还支持speed默认1/600建议区间0.0010.09、zoom_on_axis、zoom_togethernone/cross/all等细粒度控制。RangeTool可配置的范围设定手势RangeTool在 3.5.0 中新增start_gesture属性PR #13855允许选择在何处用何种手势开始一个新范围的交互方式。RangeTool本身是Drag工具的子类src/bokeh/models/tools.py#L523-L587其核心属性包括x_range/y_range与 overlay 同步的范围对象为None时 overlay 铺满对应维度overlay默认的BoxAnnotation用于可视化当前范围x_interaction/y_interaction是否响应对应维度的平移调整拖拽 box 内部或上下边start_gesturepan、tap或none默认none。start_gesture的语义src/bokeh/models/tools.py#L579-L587pan指针开始拖拽的位置即新范围的起点拖拽过程中范围连续更新松手确定终值tap在某个位置点击即开始新范围none不使用手势在当前视图内新建范围范围只能通过拖拽既有 overlay 边界调整。典型应用是联动缩放大图在大图上放置RangeTool将x_range绑定到小图的x_range用户拖拽/点击即可控制小图的显示窗口from bokeh.models import RangeTool range_tool RangeTool(x_rangeplot_small.x_range, start_gesturetap) plot_large.add_tools(range_tool)文本类字形可定制的轮廓形状Text、TeX、MathML等文本类字形新增outline_shape属性PR #13620允许为文本的外轮廓选择预定义形状。实现位于 src/bokeh/models/glyphs.py#L1733-L1751outline_shape DataSpec(Enum(OutlineShapeName), defaultbox, help Specify the shape of the outline for the text box. The default outline is of a text box is its bounding box (or rectangle). This can be changed to a selection of pre-defined shapes, like circle, ellipse, diamond, parallelogram, etc. Those shapes are circumscribed onto the bounding box, so that the contents of a box fit inside those shapes. )要点如下默认box即文本的包围矩形可选circle、ellipse、diamond、parallelogram等形状这些形状外接于包围盒保证文本内容仍在形状内部该属性仅在设置了边框线border_line_*、背景填充background_fill_*或背景填充纹理background_hatch_*时才生效设为none可完全禁用轮廓绘制目前命中测试仍基于文本内容的包围盒等价于box形状这是源码中明确标注的限制该属性为实验性可能随版本调整。搭配padding与border_radius圆角使用可获得更精细的标注效果。Legend点击事件 API3.5.0 为Legend增加条目点击事件及配套 APIPR #13922。在 src/bokeh/models/annotations/legends.py#L575-L579 中新增了两个方法def on_click(self, handler: PyEventCallback) - None: ... def js_on_click(self, handler: JsEventCallback) - None: ...用法与 Bokeh 既有的事件回调约定一致from bokeh.models import Legend def handle_legend_click(event): print(fclicked on legend item: {event}) legend Legend(items[...]) legend.on_click(handle_legend_click) # Python 回调需运行 Bokeh Server legend.js_on_click(customjs_callback) # JavaScript 回调纯前端可用结合Legend.click_policynone/hide/mute见 src/bokeh/models/annotations/legends.py#L480现在可以在用户点击图例条目的同时触发自定义的数据联动或业务逻辑例如联动外部表格高亮、统计选中项等。FileInput目录上传支持FileInput控件新增directory属性PR #13873允许用户选择一个目录而非单个/多个文件。源码定义位于 src/bokeh/models/widgets/inputs.py#L207-L224multiple Bool(defaultFalse, help set multipleFalse (default) for single file selection, set multipleTrue if ...) directory Bool(defaultFalse, help ... The filename will be relative paths to the uploaded directory. ...)使用注意启用directoryTrue后上传的是目录内全部文件filename将保存为相对于所选目录的相对路径上传目录时会弹出确认对话框源码注释明确指出accept参数只对文件扩展名生效且与directory组合使用时被接受文件的数量语义会不同需要结合实际需求验证过滤行为。FileInput的只读输出属性valuebase64 编码内容、mime_type、filename见 src/bokeh/models/widgets/inputs.py#L137-L167在目录模式下会相应变为列表形态注意按列表处理。ClearInput服务端事件驱动的输入清空3.5.0 扩展了服务端事件server-sent events的支持其中代表性事件是作用于输入控件的ClearInputPR #13890。该能力面向Bokeh Server架构服务端 Python 代码可以将清空输入框作为事件推送到前端实现跨会话的联动——例如在协作面板中某位用户点击重置后其他用户的输入控件同步清空。相关服务端基础设施可参考 src/bokeh/server 目录的会话实现输入控件模型则集中在 src/bokeh/models/widgets。ValueRef 格式化器与 HoverTool 模板增强ValueRef模型用于Slope、Whisker、Band等注解的标签文本新增了格式化器支持同时HoverTool的工具提示模板能力得到改进PR #13650。这意味着注解标签与悬浮提示现在可以更灵活地控制数值显示格式而不仅限于field占位符。相关交互式示例可参考 examples/interaction/tools/hover_tooltip_formatting.py 与 examples/interaction/tools/hover_tooltip_advanced.py。CSS 变量驱动的渲染器样式3.5.0 为绘图渲染器renderers新增了基于CSS 变量的样式能力PR #13828。该特性的模型基础位于 src/bokeh/models/css.py其中定义了如outline_color、outline_width等与 CSS 轮廓属性对应的模型字段见 src/bokeh/models/css.py#L344-L347。其价值在于将部分视觉属性交给浏览器 CSS 层接管后可以通过主题、媒体查询等方式统一切换外观而无需重建图形对象。css相关模型同时出现在 src/bokeh/models/css.pyi 的类型声明中供类型检查使用。Python 版本支持变更3.5.0移除了对 Python 3.9 的支持并对代码库进行了现代化改造PR #13634。在当前仓库的 pyproject.toml#L10 中可见requires-python 3.12这意味着当前代码库要求 Python 3.12 及以上版本。如果你正在维护依赖 Bokeh 3.5.0 的应用请确保运行环境满足该版本要求并留意因代码现代化类型注解、语法更新等带来的潜在兼容性变化。小结Bokeh 3.5.0 的变更集中在四个方向注解交互增强BoxAnnotation.inverted与手柄体系、文本轮廓形状、工具手势精细化滚轮修饰键、RangeTool.start_gesture、子坐标命中缩放、事件 API 扩展Legend.on_click/js_on_click、ClearInput服务端事件、以及样式与平台现代化CSS 变量、Python 3.12。动手验证时可直接在 Python 3.12 环境安装本仓库并运行 examples/basic/annotations 与 examples/interaction 下的示例多数新特性一两个参数即可复现。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考