Plotly中hovertemplate的text、customdata与meta区别及多维customdata用法

一、text、customdata、meta的核心区别 #

1. text：兼具显示与hover文本功能 #

• 最初设计是用来设置单个数据点的默认hover文本，如果不配置hovertemplate，鼠标悬停时会直接显示text的内容
• 额外功能：配合textposition参数（比如top center），可直接把text内容显示在对应数据点旁作为可视化标签
• 在hovertemplate中通过%{text}引用

2. customdata：专属自定义附加数据 #

• 完全为存储隐藏辅助数据设计，无任何默认显示行为，必须通过hovertemplate或交互回调主动调用
• 支持任意格式数据（字符串、数字、数组等），但需保证长度与x/y数据点数量一致
• 适合存放无需直接展示在图表上，但hover或交互逻辑中需要用到的信息（如数据ID、原始备注）
• 在hovertemplate中通过%{customdata}引用，多维数据可使用%{customdata[索引]}调用

3. meta：Trace级别的全局元数据 #

• 注意：它是整个轨迹（trace）共用的元数据，并非绑定单个数据点（你示例中给了列表形式，但Plotly不会将列表元素分配给单个点，整个trace只会使用meta的单个值或最后一个值）
• 用途是给整个trace添加备注信息，比如数据源说明、轨迹类型标注等
• 在hovertemplate中通过%{meta}引用，所有数据点hover时显示的都是同一个值

二、customdata支持二维数据的实现方式 #

customdata完全支持二维数据，只需将每个数据点对应的customdata设置为数组/元组形式，再在hovertemplate中通过索引调用即可。修正后的示例代码如下：

import plotly.graph_objects as go

fig = go.Figure(go.Scatter(
    x = [1,2,3,4,5],
    y = [2.02825,1.63728,6.83839,4.8485,4.73463],
    # 每个点对应一组二维自定义数据
    customdata=[
        ['cd1_1', 'cd1_2'],
        ['cd2_1', 'cd2_2'],
        ['cd3_1', 'cd3_2'],
        ['cd4_1', 'cd4_2'],
        ['cd5_1', 'cd5_2']
    ],
    hovertemplate =
    '<i>Price</i>: $%{y:.2f}'+ 
    '<br><b>X</b>: %{x}'+ 
    '<br><b>第一组自定义数据</b>: %{customdata[0]}'+ 
    '<br><b>第二组自定义数据</b>: %{customdata[1]}',
    showlegend = False))

fig.update_layout(
    hoverlabel_align = 'right',
    title = "使用二维customdata的hover模板示例")

fig.show()

你之前尝试失败大概率是以下原因：

• 未将每个数据点的customdata设置为数组形式，或传入的二维列表长度与x/y数据点数量不匹配
• 在hovertemplate中引用时语法错误，比如漏掉大括号或索引格式不正确

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