Python Plotly绘制动态多级雷达图及悬停提示设置

图 0：Plotly 动态多级雷达图与自定义悬停提示交互整体方案

一、核心概念与数据准备：极坐标系的闭环与多级维度定义

雷达图（Radar Chart，又称蜘蛛网图）在数学本质上是以极坐标系（Polar Coordinates）为基础的二维多边形表达。角轴（Angular Axis）对应评估维度（如各项技能或业务指标），径向轴（Radial Axis）对应指标的数值大小。

在实际工程中，绘制多级动态雷达图有两个极易被忽视的关键细节：

1. 几何闭环处理（Loop Closure）：雷达图的多边形必须闭合。如果输入 5 个维度的数据，仅传入 5 个点，Plotly 的多边形轮廓线在绘制到第 5 个点后不会自动连回第 1 个点，导致填充区域出现缺口。标准做法是在数据末尾追加首个维度及其对应数值。
2. 多级尺度定义（Multi-level Ticks）：常规雷达图使用连续数值，而多级雷达图通常承载等级化语义（例如“初级、中级、高级、专家”或不同达标线）。需要对 polar.radialaxis 的取值范围、刻度点与文本标签进行显式对齐。

图 1：从数据规整到交互动画装配的完整流水线

以下代码展示了如何对多维评估数据进行首尾闭合处理，并组织用于提示框展示的富上下文元数据：

import pandas as pd
import numpy as np

# 1. 原始评估维度
dimensions = ["系统架构", "算法工程", "自动化测试", "持续集成", "业务洞察", "团队协同"]

# 2. 闭环函数：使首末项坐标连通
def close_radar_loop(data_list):
    """追加首项元素以实现几何多边形完全闭合"""
    return list(data_list) + [data_list[0]]

# 处理后的角轴坐标
theta_closed = close_radar_loop(dimensions)

# 打印验证结果
print("闭环后的角轴维度:", theta_closed)
# 示例输出：['系统架构', '算法工程', '自动化测试', '持续集成', '业务洞察', '团队协同', '系统架构']

二、基础多级雷达图绘制：极坐标布局与多系列层叠

在 Plotly 中，推荐使用 plotly.graph_objects.Scatterpolar 构建雷达图。相比高级封装的 express.line_polar，graph_objects 提供了对样式属性、多图层混合、多级径向轴控制以及底层动画帧的完整操纵能力。

图 2：极坐标几何模型与多层 Trace 空间堆叠结构

多级雷达图通常需要同时对比“实际表现”与“多级标准线”。我们通过叠加两个 go.Scatterpolar 图层，并在 layout.polar.radialaxis 中声明多级标尺：

import plotly.graph_objects as go

# 维度与各层指标数据
categories = ["系统架构", "算法工程", "自动化测试", "持续集成", "业务洞察", "团队协同"]
score_current = [86, 92, 74, 80, 88, 79]
score_benchmark = [70, 70, 70, 70, 70, 70] # 团队中位数要求

# 闭环补全
categories_closed = close_radar_loop(categories)
score_current_closed = close_radar_loop(score_current)
score_benchmark_closed = close_radar_loop(score_benchmark)

# 实例化图表对象
fig = go.Figure()

# 1. 绘制基准达标线（底层）
fig.add_trace(go.Scatterpolar(
    r=score_benchmark_closed,
    theta=categories_closed,
    name="合格基准线 (L2)",
    mode="lines",
    line=dict(color="#94A3B8", width=1.5, dash="dash"),
    hoverinfo="skip" # 跳过基准线的繁杂悬停，聚焦实际数据
))

# 2. 绘制实际评估多边形（上层）
fig.add_trace(go.Scatterpolar(
    r=score_current_closed,
    theta=categories_closed,
    name="当前评估人员",
    mode="lines+markers",
    fill="toself",
    fillcolor="rgba(101, 155, 155, 0.28)", # 采用低透明度灰青填充
    line=dict(color="#17324D", width=2.5),
    marker=dict(size=7, color="#17324D")
))

# 3. 配置多级径向轴体系
fig.update_layout(
    polar=dict(
        radialaxis=dict(
            visible=True,
            range=[0, 100], # 严格锁定 0-100，防止尺度自适应形变
            tickmode="array",
            tickvals=[25, 50, 75, 100],
            ticktext=["初级 (25)", "中级 (50)", "高级 (75)", "专家 (100)"],
            tickfont=dict(size=10, color="#64748B"),
            gridcolor="#E2E8F0",
            linecolor="#CBD5E1"
        ),
        angularaxis=dict(
            tickfont=dict(size=12, color="#17324D", family="Arial, 'PingFang SC'"),
            rotation=90, # 使第一个维度居顶垂直显示
            direction="clockwise", # 顺时针排列维度
            gridcolor="#E2E8F0"
        ),
        bgcolor="#FAFBFD"
    ),
    showlegend=True,
    legend=dict(x=0.02, y=1.1, orientation="h"),
    margin=dict(l=60, r=60, t=60, b=40),
    paper_bgcolor="#FFFFFF"
)

三、悬停提示（Hovertemplate）深度定制与 Customdata 注入

Plotly 默认的悬停浮窗仅显示 (r, theta)，对于专业评估图表而言信息密度明显不足。读者往往需要知道：“该维度具体考核什么？”、“距离标准差了多少？”、“具体的关键成果是什么？”。

实现多字段悬停提示的核心是 customdata 参数与 hovertemplate 模板语法的配合使用：

• customdata：传入一个与 r 等长的二维数组或元组列表，每一个元素包含该节点对应的补充数据 [基准分, 差值说明, 详细描述]。同样需要对 customdata 做首尾闭环补充。
• %{theta} 与 %{r}：提取当前节点的极坐标维度和数值。可以通过 %{r:.1f} 控制浮点数位数。
• %{customdata[i]}：按索引读取 customdata 中的字段。
• <extra></extra> 标记：Plotly 默认会在浮窗右侧或下方附带 Trace 名称标签，通常会破坏紧凑排版。通过在模板末尾声明空的 <extra></extra>，即可彻底隐藏默认标签。

图 3：customdata 多维注入与 hovertemplate 结构化富文本映射机制

以下为具备完整上下文解析能力的悬停模板配置代码：

# 1. 准备多字段元数据矩阵：[基准分, 差异说明, 业务项目支撑]
meta_info = [
    ["70分", "+16分 (超标)", "主持重构核心网关架构"],
    ["70分", "+22分 (专家)", "完成核心推理引擎优化"],
    ["70分", "+4分 (达标)", "核心用例覆盖率达 85%"],
    ["70分", "+10分 (良好)", "流水线构建耗时缩减 50%"],
    ["70分", "+18分 (超标)", "推进 3 个关键商业化项目落地"],
    ["70分", "+9分 (良好)", "指导 2 名初级工程师快速成长"]
]

# 元数据同样需要做闭合处理，确保索引对应
meta_info_closed = close_radar_loop(meta_info)

# 2. 构建定制化悬停模板字符串
custom_hovertemplate = (
    "<b style='font-size: 14px;'>%{theta}</b><br>"
    "-----------------------------<br>"
    "<span style='color: #659B9B;'>当前得分：</span><b>%{r:.1f}</b> 分<br>"
    "<span style='color: #94A3B8;'>基准要求：</span>%{customdata[0]}<br>"
    "<span style='color: #10B981;'>评估差距：</span><b>%{customdata[1]}</b><br>"
    "<span style='color: #CBD5E1;'>关键支撑：</span>%{customdata[2]}"
    "<extra></extra>" # 隐藏默认 Trace 标签
)

# 3. 将模板与数据绑定至 Scatterpolar
fig.add_trace(go.Scatterpolar(
    r=score_current_closed,
    theta=categories_closed,
    name="当前评估人员",
    mode="lines+markers",
    fill="toself",
    fillcolor="rgba(101, 155, 155, 0.25)",
    line=dict(color="#17324D", width=2.5),
    marker=dict(size=8, color="#17324D"),
    customdata=meta_info_closed,
    hovertemplate=custom_hovertemplate,
    hoveron="points+fills" # 既支持顶点触发，也支持点击填充面触发
))

# 4. 美化悬停浮层外观
fig.update_layout(
    hoverlabel=dict(
        bgcolor="#17324D",
        bordercolor="#659B9B",
        font_size=12,
        font_color="#FAFBFD",
        font_family="Arial, 'PingFang SC', 'Microsoft YaHei'"
    )
)

四、动态时序演进：基于 Frames 与 Sliders 的雷达图动画

动态雷达图常用于展示评估对象随时间（如季度 Q1-Q4 或多轮评审阶段）的演进轨迹。在 Plotly 中，实现平滑形变动画需要配置 frames 序列，并在 layout 中装配 updatemenus（播放/暂停按钮）与 sliders（时间轴进度滑块）。

以下是具备完整时间滑块与播放控件的动态多级雷达图生成代码：

import plotly.graph_objects as go

# 维度定义
categories = ["系统架构", "算法工程", "自动化测试", "持续集成", "业务洞察", "团队协同"]
theta_closed = close_radar_loop(categories)
benchmark_closed = close_radar_loop([70, 70, 70, 70, 70, 70])

# 4 个季度的动态评估分
quarterly_scores = {
    "Q1": [65, 70, 60, 68, 72, 65],
    "Q2": [72, 78, 68, 74, 76, 70],
    "Q3": [80, 85, 72, 78, 82, 75],
    "Q4": [86, 92, 75, 82, 88, 80]
}

# 4 个季度的支撑说明
quarterly_notes = {
    "Q1": ["熟悉规范", "基础算法实现", "手工测试为主", "参与脚本编写", "熟悉业务流程", "团队融入"],
    "Q2": ["模块化重构", "模型初步调优", "引入单元测试", "搭建基本CI", "主导小型需求", "积极交流"],
    "Q3": ["高并发治理", "推理加速试验", "自动化用例集", "流水线提速", "识别核心痛点", "跨组协同"],
    "Q4": ["全链路架构", "核心引擎上线", "自动化达85%", "全面持续交付", "落地商业化项目", "带教新人"]
}

# 构建初始图形（展示 Q1）
init_scores_closed = close_radar_loop(quarterly_scores["Q1"])
init_meta = [["70分", f"{s-70:+d}分", note] for s, note in zip(quarterly_scores["Q1"], quarterly_notes["Q1"])]
init_meta_closed = close_radar_loop(init_meta)

fig = go.Figure()

# 静态基准线 (Trace 0)
fig.add_trace(go.Scatterpolar(
    r=benchmark_closed,
    theta=theta_closed,
    name="合格基准 (70分)",
    mode="lines",
    line=dict(color="#94A3B8", width=1.5, dash="dash"),
    hoverinfo="skip"
))

# 动态评估面 (Trace 1)
fig.add_trace(go.Scatterpolar(
    r=init_scores_closed,
    theta=theta_closed,
    name="能力成长演进",
    mode="lines+markers",
    fill="toself",
    fillcolor="rgba(101, 155, 155, 0.28)",
    line=dict(color="#17324D", width=2.5),
    marker=dict(size=8, color="#17324D"),
    customdata=init_meta_closed,
    hovertemplate=(
        "<b>%{theta}</b><br>"
        "得分: <b>%{r}</b> 分<br>"
        "偏离: %{customdata[1]}<br>"
        "重点: %{customdata[2]}<extra></extra>"
    )
))

# 构建 4 个动画帧
frames = []
for q_name in ["Q1", "Q2", "Q3", "Q4"]:
    q_score_closed = close_radar_loop(quarterly_scores[q_name])
    q_meta = [["70分", f"{s-70:+d}分", note] for s, note in zip(quarterly_scores[q_name], quarterly_notes[q_name])]
    q_meta_closed = close_radar_loop(q_meta)
    
    frame = go.Frame(
        name=q_name,
        data=[
            # 保持 Trace 0 不变
            go.Scatterpolar(r=benchmark_closed, theta=theta_closed),
            # 更新 Trace 1
            go.Scatterpolar(
                r=q_score_closed,
                theta=theta_closed,
                customdata=q_meta_closed
            )
        ]
    )
    frames.append(frame)

fig.frames = frames

# 构建滑动块配置
sliders = [dict(
    active=0,
    currentvalue=dict(prefix="评估周期：", font=dict(size=14, color="#17324D", family="Arial")),
    pad=dict(t=50, b=10),
    steps=[
        dict(
            method="animate",
            args=[[q_name], dict(mode="immediate", frame=dict(duration=500, redraw=False), transition=dict(duration=300))],
            label=q_name
        ) for q_name in ["Q1", "Q2", "Q3", "Q4"]
    ]
)]

# 构建播放与暂停按钮
updatemenus = [dict(
    type="buttons",
    showactive=False,
    x=0.02, y=-0.15,
    xanchor="left", yanchor="top",
    pad=dict(t=10, r=10),
    buttons=[
        dict(
            label="▶ 播放演变",
            method="animate",
            args=[None, dict(frame=dict(duration=800, redraw=False), transition=dict(duration=400), fromcurrent=True)]
        ),
        dict(
            label="❚❚ 暂停",
            method="animate",
            args=[[None], dict(mode="immediate", frame=dict(duration=0, redraw=False))]
        )
    ]
)]

# 组装最终布局
fig.update_layout(
    polar=dict(
        radialaxis=dict(
            range=[0, 100],
            tickmode="array",
            tickvals=[25, 50, 75, 100],
            ticktext=["初级", "中级", "高级", "专家"],
            gridcolor="#E2E8F0"
        ),
        angularaxis=dict(rotation=90, direction="clockwise", gridcolor="#E2E8F0"),
        bgcolor="#FAFBFD"
    ),
    sliders=sliders,
    updatemenus=updatemenus,
    title=dict(text="年度技术能力阶梯演化雷达图", font=dict(size=18, color="#17324D")),
    margin=dict(l=60, r=60, t=80, b=100)
)

# 导出为独立可交互 HTML 文件
fig.write_html("dynamic_multilevel_radar.html", include_plotlyjs="cdn")

五、核心配置速查与常见避坑指南

为了在实际项目中高效排查问题，下表列出了核心参数的最佳实践与常见错误对照：

图 4：Plotly 动态多级雷达图配置矩阵与避坑策略速查

通过遵循上述“首尾闭环规整、多级径向轴约束、元数据矩阵映射与同构动画帧装配”的开发原则，即可使用 Python Plotly 构建出兼具严谨度与交互表现力的高质量多级动态雷达图。