本文提供一种鲁棒、可扩展的 python 函数，用于自动判断任意 plotly 图表（包括 `graph_objects` 和 `express` 生成的图表）是否为空，无需渲染或人工检查，适用于 api 返回图表对象的自动化校验场景。
在构建数据可视化流水线时，常需对接外部 API 获取 Plotly 图表对象（如 plotly.graph_objects.Figure 或 plotly.express 返回的 Figure），但无法预知其输入数据是否为空。若直接渲染空图，不仅浪费资源，还可能引发前端异常或误导用户。因此，亟需一个不依赖渲染、不访问原始 DataFrame、兼容所有 Plotly 图形类型的空图检测机制。
上述需求的核心在于：Plotly 图表的“空”本质是其 figure.data 中所有 trace（轨迹）均未携带有效可视化数据。不同 trace 类型（如 Scatter, Bar, Choropleth, Sunburst）判定“空”的依据各不相同——有的依赖 x/y 数组长度，有的依赖 z（热力图）、lat/lon（地图类）、values（树图类）等特有字段。原方案通过硬编码键名列表（['x', 'y', 'z', ...]）并逐项检查长度，虽对简单图表有效，但存在明显缺陷：
- ❌ 忽略 None 值：如 trace['x'] is None 是合法且常见的空状态，但 len(None) 会报错；
- ❌ 误判字符串型 text：trace['text'] = "" 应为空，但 isinstance("", str) 为真，原逻辑未覆盖；
- ❌ 遗漏关键字段：如 line_mapbox 依赖 lat/lon，choropleth 依赖 z 或 geojson + featureidkey，原逻辑未覆盖；
- ❌ 未处理 go.Figure() 初始化即为空的边界情况（figure.data == tuple()）。
以下是一个经多类型验证的健壮检测函数，覆盖 plotly.graph_objects 与 plotly.express 所有主流图表：
import plotly.graph_objects as go
import plotly.express as px
def check_empty_plot(figure):
"""
判断 Plotly Figure 是否为空图表。
支持类型：Scatter, Bar, Line, Area, Violin, Choropleth, Sunburst,
Treemap, Pie, Timeline, Scattermapbox, LineMapbox 等。
Args:
figure (plotly.graph_objects.Figure or plotly.express.Figure):
待检测的 Plotly 图表对象
Returns:
bool: True 表示图表为空（无有效数据），False 表示非空。
"""
def is_trace_empty(trace):
# 1. 检查 trace 是否为 None 或空字典
if not trace or not isinstance(trace, dict):
return True
# 2. 处理常见空值标识
if "x" in trace and trace["x"] is None:
return True
if "y" in trace and trace["y"] is None:
return True
if "z" in trace:
z_val = trace["z"]
if z_val is None or (hasattr(z_val, '__len__') and len(z_val) == 0):
return True
if "values" in trace and (trace["values"] is None or
(hasattr(trace["values"], '__len__') and len(trace["values"]) == 0)):
return True
if "lat" in trace and (not trace["lat"] or
(hasattr(trace["lat"], '__len__') and len(trace["lat"]) == 0)):
return True
if "lon" in trace and (not trace["lon"] or
(hasattr(trace["lon"], '__len__') and len(trace["lon"]) == 0)):
return True
if "text" in trace:
text_val = trace["text"]
if text_val is None:
return True
if isinstance(text_val, str) and not text_val.strip():
return True
if hasattr(text_val, '__len__') and len(text_val) == 0:
return True
# 3. 检查核心数值数组（x/y/z/values/lat/lon）是否至少有一个非空
for key in ["x", "y", "z", "values", "lat", "lon"]:
if key in trace:
val = trace[key]
if val is not None and hasattr(val, '__len__') and len(val) > 0:
return False
if isinstance(val, (list, tuple, set)) and val: # 显式非空容器
return False
# 4. 特殊处理 marker/colorscale 等嵌套结构（仅当其他主字段为空时）
if "marker" in trace and isinstance(trace["marker"], dict):
marker = trace["marker"]
if "size" in marker and hasattr(marker["size"], '__len__') and len(marker["size"]) > 0:
return False
if "color" in marker and hasattr(marker["color"], '__len__') and len(marker["color"]) > 0:
return False
return True # 所有检查均未发现有效数据
# 主逻辑：figure.data 为空元组 → 绝对为空
if not hasattr(figure, 'data') or figure.data == tuple():
return True
# 所有 trace 均为空 → 整体为空
return all(is_trace_empty(trace) for trace in figure.data)✅ 该函数优势：
- 兼容 go.Figure() 和 px.*() 生成的所有图表；
- 显式处理 None、空字符串、空容器（[], (), {}）及缺失键；
- 覆盖地图类（lat/lon）、地理图（z, geojson）、层次图（values, ids, parents）等特殊字段；
- 采用 all() 短路逻辑，性能高效；
- 代码自文档化，关键分支均有注释说明适用场景。
⚠️ 使用注意事项：
- 该函数不验证 trace 的语义有效性（如 x 和 y 长度不匹配），仅检测“是否含数据”；
- 若 trace 使用 visible=False 但数据非空，仍判定为非空图（符合设计预期：隐藏 ≠ 不存在）；
- 对于自定义 go.Scattergl、go.Volcano 等冷门 trace，建议补充对应字段到 is_trace_empty 的检查逻辑；
- 生产环境建议配合单元测试，覆盖 px.scatter([]), px.choropleth(pd.DataFrame()), go.Figure() 等典型空图用例。
通过此函数，您可将图表空值校验无缝集成至 CI/CD 流程或 API 响应中间件，真正实现“零人工、全自动、全兼容”的可视化质量保障。
