深入 Superset：自定义图表开发完全指南

Words 1630Read Time≈ 5 min
2026-2-11
cover
type
Post
status
Published
date
Apr 26, 2020 09:31
slug
summary
本文详细介绍了 Superset 0.35 版本中图表的组成结构、开发流程和渲染逻辑。从前端组件封装、控制面板配置到后端处理类的实现，带你完整掌握如何在 Superset 中自定义一个图表类型。
tags
Superset
React
Python
category
Data Engineering
icon
password
wordCount
1573

前言

Superset 作为开源 BI 领域的明星项目，其灵活的图表扩展机制让开发者可以轻松打造定制化的可视化组件。从 0.33 版本开始，Superset 团队重构了图表架构，采用组件化 + 注册机制，将所有内置图表封装进 @superset-ui 包。本文将带你深入了解 Superset 图表的渲染流程，掌握自定义图表的完整开发路径。
📊
核心要点
本文基于 Superset 0.35 版本，介绍应用层面的图表呈现逻辑。0.36 版本除了文件位置调整外，核心流程保持一致。

图表的三大组成部分

Superset 中的每个图表都由三个核心部分协同工作：
组件
作用
技术栈
控制面板
配置数据源、图表类型、时间范围等参数
React 组件 + JSON 配置
图表展示
负责最终的可视化渲染
React + D3/ECharts 等图表库
后台处理类
执行 SQL 查询并处理数据转换
Python (Flask)
notion image
💡
控制面板中，数据源 & 图表类型和时间是固定属性，其他选项都可以根据图表特性自定义。所有组件都必须注册到 Superset 配置文件才能生效。

前端图表组件开发

标准图表包结构

以 @superset-ui/legacy-plugin-chart-chord 为例，一个完整的图表包包含以下文件：
notion image
让我们逐一解析每个文件的作用。

images：图表缩略图

这个文件夹存放图表在选择器中显示的预览图：
  • thumbnail.png：普通分辨率（用于标准显示）
  • thumbnailLarge.png：高分辨率（用于 Retina 屏幕）
⚠️
文件名不可更改，否则 Superset 无法正确识别缩略图。
notion image

index.js：图表入口

这是整个图表的注册入口，返回一个继承自 ChartPlugin 的图表类：
🔑
ChartPlugin 构造函数三要素：
  • metadata：图表元信息（名称、描述、缩略图）
  • transformProps：数据转换器，连接后端与前端
  • loadChart：图表渲染函数的加载器

transformProps.js：数据转换层

作为前后端的桥梁，这个文件负责将后端返回的数据转换为 React 组件可用的格式：
参数
说明
width / height
前端容器尺寸，直接透传
formData
控制面板用户配置的参数
queryData
后端处理后的数据结果

ReactChord.js：组件包装器

将渲染函数转换为 React 组件，代码极其简洁：
只需替换 Component 为你的自定义渲染函数即可。

Chord.js：核心渲染逻辑

这是真正的图表绘制代码。以 ECharts 柱状图为例：
✨
开发提示
  • propTypes 用于类型检查，确保数据格式正确
  • 你可以使用任何图表库（D3、ECharts、Plotly 等）
  • 记得处理容器尺寸自适应

图表注册

完成开发后，需要在两个文件中注册图表：

1. MainPreset.js

2. VizTypeControl.jsx

将图表的 key 添加到 DEFAULT_ORDER 数组：

控制面板配置

面板配置文件

所有控制面板配置都在 /explore/controlPanels/ 目录下：
notion image
以 Chord 图为例：
📋
配置结构说明
  • controlPanelSections：定义面板的布局和控件
  • controlSetRows：每个数组代表一行，字符串对应 controls.jsx 中的配置项
  • controlOverrides：覆盖默认控件的属性

controls.jsx：控件定义

这个文件包含所有可用的控件类型。两个示例：
渲染效果：
notion image
notion image

注册控制面板

修改 /setup/setupPlugins.ts：

后端处理类

所有图表的后端逻辑都在 /superset/viz.py 中。

自定义指标配置

如果你使用了自定义的 SQL 相关选项，必须在 METRIC_KEYS 中声明：

图表处理类实现

🔄
执行流程
  1. 用户点击查询 → 触发 query_obj() 方法
  1. Superset 执行 SQL 查询
  1. 查询结果传入 get_data() 方法
  1. 处理后的数据返回给前端的 transformProps
  1. 前端执行渲染逻辑
属性/方法
说明
viz_type
图表类型标识，必须与前端注册的 key 一致
query_obj()
查询前的参数校验和处理
get_data()
查询后的数据转换，返回给前端
form_data.get()
获取控制面板的配置值

总结

通过本文的介绍，你已经掌握了 Superset 图表开发的完整流程：
前端部分：封装 React 组件 → 定义数据转换 → 实现渲染逻辑 → 注册图表类型
控制面板：配置控件布局 → 定义参数选项 → 注册到系统
后端部分：继承基类 → 实现查询逻辑 → 数据格式转换
Superset 的组件化架构让图表扩展变得非常灵活。无论是集成 ECharts、D3 还是其他可视化库，都可以通过这套标准流程快速实现。未来，随着前端技术的发展，你还可以探索更多创新的图表类型，比如 3D 可视化、实时数据流图表等。
Loading...