在 Bokeh 中自定义手势工具GestureTool以拖拽手绘工具为例的完整实现指南【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh导读Bokeh 允许开发者通过自定义扩展Custom Extension把全新的交互能力注入浏览器端画布。本文以官方示例 examples/advanced/extensions/tool.py 为骨架完整讲解如何用 Python TypeScript 编写一个自定义的GestureTool子类实现在绘图画布上按住鼠标或触屏手指拖拽即可手绘线条的交互工具。读完本文你将掌握 Bokeh 工具系统的分类与生命周期、手势事件pan在 Python 端与 TypeScript 端的对接方式以及屏幕坐标与数据坐标的换算方法从而能够独立开发任意自定义交互工具。Bokeh 工具系统概览自定义工具从哪里接入在动手写代码之前需要先理解 Bokeh 内置工具的分类。在 src/bokeh/models/tools.py 的模块文档中Bokeh 明确将工具交互分为五类Pan/Drag平移/拖拽Click/Tap点击/轻触Scroll/Pinch滚动/捏合Actions动作如保存、重置Inspectors检查器如 HoverTool被动报告信息其中前三类统称为手势工具gesture tools同一时刻每个手势只能有一个工具处于激活状态激活的工具在工具栏上会有高亮标识Actions 是即时的或模态的操作Inspectors 则是可以始终激活的被动工具。从源码结构看这套分类在 TypeScript 端对应bokehjs/src/lib/models/tools/下的三个目录gestures/手势工具、actions/动作工具、inspectors/检查器工具。自定义工具时只需选择对应基类继承即可——本文要做的拖拽手绘工具属于手势工具因此直接继承GestureTool。示例目标一个可拖拽手绘的自定义工具本示例要实现的工具名为DrawTool其行为是在画布上按下鼠标/手指时清空已绘制的数据拖拽过程中把鼠标经过的每个点追加进数据源松开时结束本次绘制。绘制结果通过一个普通的line字形实时渲染出来最终效果是按住拖拽即可在画布上随意涂鸦。官方文档 docs/bokeh/source/docs/user_guide/advanced/extensions/tool.rst 通过.. bokeh-plot::指令直接渲染并展示该示例属于 Bokeh 扩展能力用户指南中的典型范例。完整的示例代码整个扩展由两部分组成内嵌在 Python 字符串里的 TypeScript 代码浏览器端逻辑以及一个继承Tool的 Python 模型服务端/文档端定义。完整代码见 examples/advanced/extensions/tool.py核心结构如下from bokeh.core.properties import Instance from bokeh.models import ColumnDataSource, Tool from bokeh.plotting import figure, show from bokeh.util.compiler import TypeScript CODE ...TypeScript 代码... class DrawTool(Tool): __implementation__ TypeScript(CODE) source Instance(ColumnDataSource) source ColumnDataSource(datadict(x[], y[])) plot figure(x_range(0,10), y_range(0,10), titleClick and drag to draw, background_fill_color#efefef, tools) plot.add_tools(DrawTool(sourcesource)) plot.line(x, y, line_width3, sourcesource) show(plot)要点拆解__implementation__ TypeScript(CODE)这是 Bokeh 自定义扩展的标准接入点。TypeScript类来自 src/bokeh/util/compiler.py它把内嵌的 TypeScript 源码在运行时编译为浏览器可执行的 JavaScript无需单独的构建流程source Instance(ColumnDataSource)声明自定义工具的一个属性类型为ColumnDataSource实例。这个属性在 Python 端与 TypeScript 端通过p.Ref(ColumnDataSource)对应实现两端共享同一个数据源plot.add_tools(DrawTool(sourcesource))把工具挂载到 figure 上。注意这里tools即不启用任何内置工具避免干扰手绘交互plot.line(x, y, line_width3, sourcesource)用一个line字形消费数据源中的点拖拽产生的点实时连线呈现。浏览器端实现DrawToolView 的手势生命周期手势工具的核心逻辑在 TypeScript 端的View类中。本示例的DrawToolView继承自GestureToolView后者定义于 bokehjs/src/lib/models/tools/gestures/gesture_tool.ts其关键能力是提供了get plot_view()让视图可以访问所在的绘图画布视图。DrawToolView重写了三个生命周期方法这三个方法与 Bokeh 手势事件流一一对应// 拖拽开始时执行 _pan_start(_e: PanEvent): void { this.model.source.data {x: [], y: []} } // 后续每次鼠标/手指移动时执行 _pan(e: PanEvent): void { const {frame} this.plot_view const {sx, sy} e if (!frame.bbox.contains(sx, sy)) return const x frame.x_scale.invert(sx) const y frame.y_scale.invert(sy) const {source} this.model source.get_array(x).push(x) source.get_array(y).push(y) source.change.emit() } // 拖拽结束时执行 _pan_end(_e: PanEvent): void {}这段代码揭示了 Bokeh 手势工具的内部机制坐标换算核心事件对象e携带的是屏幕像素坐标sx/sy而绘图需要的是数据坐标。frame.x_scale.invert(sx)通过坐标轴的 scale 对象把屏幕坐标反算为数据坐标——frame来自plot_view即 Cartesian 框架视图frame.bbox.contains(sx, sy)先做边界检查确保只记录画布框架内的点。边界约束frame.bbox.contains(sx, sy)保证拖出绘图区域比如拖到坐标轴或标题上时不会产生越界数据点。数据驱动渲染每次移动都把新点push进数据源的x/y数组随后调用source.change.emit()发出变更信号Bokeh 的响应式系统会据此重绘绑定的line字形形成实时手绘效果。生命周期对称性_pan_start清空旧数据、_pan追加新数据、_pan_end收尾三个钩子保证了一次完整手势的干净闭环。从底层看这三个方法正是 bokehjs/src/lib/models/tools/tool.ts 中ToolView声明的可选钩子_pan_start?、_pan?、_pan_end?。而事件的分发由 bokehjs/src/lib/core/ui_events.ts 中的pan:start、pan、pan:end三个 UI 信号驱动UI 事件系统把浏览器拖拽事件转换为PanEvent再按工具声明的事件类型路由到对应工具的_pan_start/_pan/_pan_end方法参见ui_events.ts中信号到方法名的映射逻辑。这也解释了为什么DrawToolView无需自己监听 DOM 事件——Bokeh 已经统一完成。浏览器端实现DrawTool 模型声明DrawToolView之外TypeScript 端还需要定义DrawTool模型类它继承自GestureToolexport class DrawTool extends GestureTool { declare properties: DrawTool.Props declare __view_type__: DrawToolView tool_name Draw Tool tool_icon bk-tool-icon-lasso-select event_type pan as pan default_order 12 static { this.prototype.default_view DrawToolView this.defineDrawTool.Props(({Ref}) ({ source: [ Ref(ColumnDataSource) ], })) } }逐个字段说明其含义与取值约束字段作用说明tool_name工具栏提示与菜单中显示的名称任意可读字符串这里为 Draw Tooltool_icon工具栏按钮图标CSS 类名不含点号复用内置图标bk-tool-icon-lasso-select也可以提供自定义 CSSevent_type声明工具消费的事件类型必须取 ui_events.ts 中EventType联合类型之一pan \| pinch \| rotate \| move \| tap \| doubletap \| press \| pressup \| scroll。本工具用pan因此浏览器端才走_pan_*钩子default_order多个手势工具共享同一手势时的激活优先级从GestureTool抽象类的要求来看gesture_tool.ts每个手势工具都必须实现default_order与event_type两个抽象成员数字越小优先级越高source自定义属性与 Python 端Instance(ColumnDataSource)对应在static块中通过this.define声明类型为p.PropertyColumnDataSource注意static { ... }块中的两条关键语句this.prototype.default_view DrawToolView把模型与视图绑定Bokeh 在渲染时会根据模型自动实例化对应的 Viewthis.defineDrawTool.Props(({Ref}) ({source: [Ref(ColumnDataSource)]}))用 Bokeh 的属性系统声明source属性Ref表示这是一个到其他模型的引用类型。这样该属性才能享受响应式绑定、序列化等基础设施。Python 端模型如何与 TypeScript 对接Python 端的DrawTool非常简单class DrawTool(Tool): __implementation__ TypeScript(CODE) source Instance(ColumnDataSource)继承自Tool而非GestureTool这是 Bokeh 扩展的惯例——Python 侧的工具基类统一使用Tool真正的手势语义由 TypeScript 侧继承GestureTool来表达__implementation__Bokeh 自定义扩展的注册入口TypeScript(CODE)指示编译器把内嵌 TypeScript 源码编译进最终资源source属性在 Python 端声明为Instance(ColumnDataSource)与 TypeScript 端的define声明一一对应。Python 端负责创建/持有数据源TypeScript 端在交互时读写该数据源两端共享同一对象。这种Python 定义属性、TypeScript 实现行为的配对模式是所有 Bokeh 自定义工具、字形、注释扩展的共同结构。与内置手势工具的对照这不是特例而是通用模式DrawTool的实现方式并非 Bokeh 专门为扩展开放的特例内置手势工具本身就用同一套模式编写。以几个典型实现为例bokehjs/src/lib/models/tools/gestures/box_select_tool.tsBoxSelectToolView同样重写_pan_start记录起点、_pan更新选框、_pan_end提交选择bokehjs/src/lib/models/tools/gestures/lasso_select_tool.ts套索选择工具在_pan中累积轨迹点与DrawTool的绘图逻辑几乎同构bokehjs/src/lib/models/tools/gestures/pan_tool.ts平移工具在_pan中按拖拽增量更新坐标范围。这意味着阅读 bokehjs/src/lib/models/tools/gestures/ 目录下的任意一个内置手势工具都能直接复用到自定义扩展的写作中反过来学会了DrawTool这一套_pan_*钩子也就理解了 Bokeh 全部拖拽类交互工具的底层原理。运行方式与实操验证该示例采用内嵌编译的扩展形式直接运行即可本地需已安装当前仓库对应的 Bokeh 开发环境python examples/advanced/extensions/tool.py运行后会弹出或由 notebook 环境展示一个标题为 Click and drag to draw 的绘图窗口按住鼠标在灰色画布background_fill_color#efefef上拖拽即可实时绘制出粗线条line_width3松开后再次按下拖拽会清空上一次的痕迹重新绘制。可以自行验证的调整点把plot.add_tools(DrawTool(sourcesource))改为plot.add_tools(DrawTool(sourcesource), reset)等观察自定义工具与内置工具在工具栏上的共存修改default_order 12再同时添加一个BoxSelectTool观察激活优先级的变化在_pan中移除frame.bbox.contains(sx, sy)边界检查拖出绘图区观察坐标越界行为。扩展方向从手绘工具到更复杂的交互DrawTool虽小却是完整的扩展范式可以沿以下方向继续扩展更多事件类型把event_type改为tap或press重写_tap等钩子即可实现点击打点、按压缩放等交互多数据源/多属性仿照source的声明方式用Instance/Ref增加第二个数据源或配置属性如线条颜色、线宽覆盖层overlayToolView支持通过overlays返回渲染器可用于像框选工具那样绘制临时视觉反馈自定义图标修改tool_icon为自定义 CSS 类或在 Python 端通过IconLike属性注入图标资源。若想了解同一扩展体系下的其他形态可继续阅读同目录下的 ticking.rst自定义坐标轴刻度、widget.rst自定义 UI 组件与 wrapping.rst将第三方 JS 库封装为扩展。小结本文以官方示例DrawTool为线索完整走通了 Bokeh 自定义手势工具从声明到运行的整条链路Python 端用Tool基类 __implementation__注册 TypeScript 实现并声明共享属性TypeScript 端用GestureTool/GestureToolView提供模型与视图通过_pan_start/_pan/_pan_end三个钩子接入 Bokeh 统一的手势事件分发ui_events.ts并用frame.x_scale.invert完成屏幕坐标到数据坐标的换算最后通过数据源变更驱动line字形实时渲染。这套模式与 Bokeh 内置的框选、套索、平移工具完全一致掌握了它你就掌握了 Bokeh 全部拖拽类交互的扩展能力。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考