使用Plotly create_annotated_heatmap调用fig.add_trace报错求助

问题根源 #

你触发错误的核心原因是：create_annotated_heatmap返回的是完整的Plotly Figure实例，而fig.add_trace()仅接受单个Trace对象（如go.Heatmap），无法直接传入整个Figure。Plotly的错误提示"data属性接收无效元素"就是在告诉你传入的类型不匹配。

解决方案 #

根据你的需求，分两种场景给出具体实现：

1. 重构自定义函数，返回Trace+注释（推荐）

直接修改函数，让它返回热力图的Trace对象和对应的注释列表，而非完整Figure，这样就能适配add_trace的要求：

import plotly.graph_objects as go

def create_annotated_heatmap(x, y, z):
    # 生成热力图Trace
    heatmap_trace = go.Heatmap(
        x=x,
        y=y,
        z=z,
        colorscale="Viridis",
        showscale=True
    )
    
    # 生成坐标对应的注释文本
    annotations = []
    for y_idx, y_val in enumerate(y):
        for x_idx, x_val in enumerate(x):
            annotations.append(
                dict(
                    x=x_val,
                    y=y_val,
                    text=str(z[y_idx][x_idx]),
                    showarrow=False,
                    font=dict(
                        color="white" if z[y_idx][x_idx] > z.max()/2 else "black"
                    )
                )
            )
    return heatmap_trace, annotations

# 使用示例
x_data = ["A", "B", "C"]
y_data = ["X", "Y", "Z"]
z_data = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

fig = go.Figure()
# 添加热力图Trace
trace, annots = create_annotated_heatmap(x_data, y_data, z_data)
fig.add_trace(trace)
# 应用注释
fig.update_layout(annotations=annots)
fig.show()

2. 不修改原函数，合并Figure内容

如果不想改动已写好的create_annotated_heatmap（假设它返回完整Figure），可以提取其内部的Trace和布局元素，合并到目标Figure中：

# 假设原函数返回完整Figure
custom_heatmap_fig = create_annotated_heatmap(x_data, y_data, z_data)

# 初始化目标Figure
fig = go.Figure()

# 提取并添加热力图Trace
for trace in custom_heatmap_fig.data:
    fig.add_trace(trace)

# 合并注释（若目标Fig已有注释，改用extend）
fig.update_layout(annotations=custom_heatmap_fig.layout.annotations)
# 可同时合并其他布局设置（如标题、色标）
fig.update_layout(title=custom_heatmap_fig.layout.title)
fig.show()

3. 排查传入类型错误

如果上述方案仍报错，检查是否存在以下情况：

• 函数返回的不是Figure或Trace，而是普通字典：需用go.Heatmap(**dict_data)转为合法Trace对象
• 误将z数据的维度传错：确保z的维度与x、y匹配（比如x长度为N，y长度为M，z应为M×N的二维数组）

内容的提问来源于stack exchange，提问作者kalin.klinkov