Bokeh HoverTool悬停提示日期时间显示为???问题求助

问题描述 #

• 查阅大量相关技术资料后仍未解决该异常：使用Bokeh的HoverTool组件时，悬停提示内的日期时间无法正常显示，对应位置显示???。已知该现象通常代表Hover工具无法读取绑定数据源中的对应列数据。
• 已尝试多种常规修复方案，代码逻辑按官方文档说明本应正常运行，但异常复现稳定。
• 现有代码分为两个模块：
  • 数据采集模块：基于OpenCV实现摄像头运动检测，将运动开始、结束的datetime时间存入pandas DataFrame的Start、End列。
  • 绘图模块：将DataFrame的Start、End列转为datetime类型，配置HoverTool的日期时间格式化规则，调用quad方法绘制时间区间四边形，最终生成的HTML文件中悬停提示的日期时间仍显示为???。

根因分析 #

该问题90%以上的触发原因不是字段名拼写错误，而是pandas datetime类型列传入Bokeh时，ColumnDataSource自动类型推断失败，没有被识别为时间类型字段，HoverTool的格式化器无法读取对应值，就会返回???占位符。
常见触发场景：

• 直接将pandas DataFrame传给quad等绘图方法，没有手动构造ColumnDataSource做类型校验
• 配置HoverTool时只写了tooltip的格式化模板，没有显式给对应字段绑定datetime格式化器
• DataFrame中时间列的dtype为object，哪怕存储的值是datetime类型，Bokeh也无法自动识别

修复步骤 #

按顺序执行以下操作即可解决问题：

1. 显式转换时间列类型，构造独立的ColumnDataSource

   import pandas as pd
   from bokeh.models import ColumnDataSource
   
   # 强制转换时间列为datetime64类型，禁止object类型
   df["Start"] = pd.to_datetime(df["Start"]).astype("datetime64[ns]")
   df["End"] = pd.to_datetime(df["End"]).astype("datetime64[ns]")
   # 手动构造数据源，不要直接传df给绘图方法
   source = ColumnDataSource(df)
   

2. 配置HoverTool时显式绑定字段格式化器

   from bokeh.models import HoverTool
   
   hover = HoverTool(
       tooltips=[
           ("运动开始时间", "@Start{%Y-%m-%d %H:%M:%S}"),
           ("运动结束时间", "@End{%Y-%m-%d %H:%M:%S}")
       ],
       # 必须单独指定对应字段使用datetime格式化器，缺省这步就会出???
       formatters={
           "@Start": "datetime",
           "@End": "datetime"
       }
   )
   

3. 调用quad绘图时显式绑定数据源

   # left/right参数直接传字段名字符串，所有字段统一从source读取
   p.quad(
       left="Start",
       right="End",
       bottom=0,
       top=1,
       source=source
   )
   p.add_tools(hover)
   

补充：如果使用Bokeh 3.x版本，需要避免将pandas 2.0以上的datetime64[us]类型列直接传入，Bokeh 3.x目前仅支持到datetime64[ns]精度，显式转成ns精度即可识别。

内容的提问来源于stack exchange，提问作者kmedri