Flet Charts 雷达图图形形状(RadarShape)完整指南:圆形与多边形网格的用法与实现
Flet Charts 雷达图图形形状(RadarShape)完整指南:圆形与多边形网格的用法与实现
本篇技术指南以 Flet Charts 扩展包中
RadarShape枚举为核心,讲解雷达图网格与数据多边形形状的控制方式:如何通过RadarChart.radar_shape参数在圆形(CIRCLE)与多边形(POLYGON)两种渲染形态之间切换,并结合 Python 端枚举定义、Flutter 渲染端解析逻辑、官方示例与集成测试,给出可直接运行的完整代码。
RadarShape 是什么:控制雷达图"骨架"的枚举
在 Flet 生态中,雷达图(Radar Chart)由 flet-charts 扩展包提供,核心控件是 flet_charts.RadarChart。一个雷达图由多条数据序列(RadarDataSet)、环绕的标题(RadarChartTitle)以及背后的刻度网格组成,而网格与数据轮廓的绘制形态正是由 RadarShape 这个枚举决定的。
RadarShape 定义在 radar_chart.py 中,是一个标准的 Python Enum,仅包含两个成员:
| 枚举值 | 底层字符串 | 渲染效果 |
|---|---|---|
RadarShape.CIRCLE |
"circle" |
网格与数据外轮廓以径向圆形绘制 |
RadarShape.POLYGON |
`"polygon" | 直线边多边形绘制网格与数据外轮廓(默认值) |
它在 Python 端的完整定义如下(源码注释即为官方语义):
class RadarShape(Enum):
"""Shape of the radar grid and data polygons."""
CIRCLE = "circle"
"""Draws radial circles for the grid and data outlines."""
POLYGON = "polygon"
"""Draws straight-edged polygons for the grid and data outlines."""
从源码注释可以清晰看出它的职责:它不仅决定背景刻度网格的形状(圆形网格线还是多边形网格线),同时决定每个数据集填充区域的外轮廓形状,二者在同一个 radar_shape 参数下统一生效。
该枚举在包导出层被公开暴露,flet-charts 的 __init__.py 中通过 from .radar_chart import ... RadarShape 引入,并在 __all__ 中列出,因此使用者可以直接通过 import flet_charts as fch 后以 fch.RadarShape.CIRCLE 访问。
在哪里使用:RadarChart.radar_shape 参数
RadarShape 唯一的消费入口是 RadarChart 控件的 radar_shape 属性,定义于 radar_chart.py:
radar_shape: RadarShape = RadarShape.POLYGON
"""
The shape of the radar area.
"""
关键事实:
- 默认值是
RadarShape.POLYGON。也就是说,如果你不显式指定该参数,Flet 雷达图会以直线边多边形(正多边形)的形态渲染网格与数据区域。 - 该属性接受
RadarShape枚举实例,赋值时需使用fch.RadarShape.CIRCLE或fch.RadarShape.POLYGON这样的枚举成员,而非原始字符串。
下面是一个同时体现两种形状的完整可运行示例,来自仓库官方示例 radar_chart/main.py,它构建了一个包含 3 个平台维度(macOS / Linux / Windows)、3 组数据的雷达图:
import flet as ft
import flet_charts as fch
def main(page: ft.Page):
page.title = "Radar chart"
page.padding = 20
page.theme_mode = ft.ThemeMode.LIGHT
categories = ["macOS", "Linux", "Windows"]
page.add(
ft.SafeArea(
expand=True,
content=fch.RadarChart(
expand=True,
titles=[fch.RadarChartTitle(text=label) for label in categories],
center_min_value=True,
tick_count=4,
ticks_text_style=ft.TextStyle(size=20, color=ft.Colors.ON_SURFACE),
title_text_style=ft.TextStyle(
size=24, weight=ft.FontWeight.BOLD, color=ft.Colors.ON_SURFACE
),
on_event=lambda e: print(e.type),
data_sets=[
fch.RadarDataSet(
fill_color=ft.Colors.with_opacity(0.2, ft.Colors.DEEP_PURPLE),
border_color=ft.Colors.DEEP_PURPLE,
entry_radius=4,
entries=[
fch.RadarDataSetEntry(300),
fch.RadarDataSetEntry(50),
fch.RadarDataSetEntry(250),
],
),
fch.RadarDataSet(
fill_color=ft.Colors.with_opacity(0.15, ft.Colors.PINK),
border_color=ft.Colors.PINK,
entry_radius=4,
entries=[
fch.RadarDataSetEntry(250),
fch.RadarDataSetEntry(100),
fch.RadarDataSetEntry(200),
],
),
fch.RadarDataSet(
fill_color=ft.Colors.with_opacity(0.12, ft.Colors.CYAN),
border_color=ft.Colors.CYAN,
entry_radius=4,
entries=[
fch.RadarDataSetEntry(200),
fch.RadarDataSetEntry(150),
fch.RadarDataSetEntry(50),
],
),
],
),
)
)
if __name__ == "__main__":
ft.run(main)
若想切换为圆形网格形态,只需在 RadarChart 构造函数中追加一行:
fch.RadarChart(
...,
radar_shape=fch.RadarShape.CIRCLE, # 圆形网格与圆形数据轮廓
)
官方示例与测试中的实际用法
文档示例截图对应的测试用例
RadarChart 的官方文档(radarchart.md)展示了 radar_shape=fch.RadarShape.CIRCLE 的雷达图。该示例对应的集成测试位于 test_radar_chart.py,其中使用四个季节标题与两组数据,并显式指定了圆形形态:
fch.RadarChart(
titles=[
fch.RadarChartTitle(text="winter", position_percentage_offset=0.1),
fch.RadarChartTitle(text="spring", position_percentage_offset=0.1),
fch.RadarChartTitle(text="summer", position_percentage_offset=0.1),
fch.RadarChartTitle(text="autumn", position_percentage_offset=0.1),
],
radar_shape=fch.RadarShape.CIRCLE,
data_sets=[
fch.RadarDataSet(
fill_color=ft.Colors.with_opacity(0.2, ft.Colors.BLUE_GREY_700),
entries=[
fch.RadarDataSetEntry(130),
fch.RadarDataSetEntry(95),
fch.RadarDataSetEntry(190),
fch.RadarDataSetEntry(60),
],
),
fch.RadarDataSet(
fill_color=ft.Colors.with_opacity(0.2, ft.Colors.CYAN_400),
entries=[
fch.RadarDataSetEntry(90),
fch.RadarDataSetEntry(45),
fch.RadarDataSetEntry(265),
fch.RadarDataSetEntry(150),
],
),
],
)
这是验证 CIRCLE 形态渲染效果的官方依据:当你使用圆形网格时,测试期望渲染出与上图一致的截图。
两种形状的视觉效果差异
POLYGON(默认):网格由一圈圈正多边形刻度环构成(如五边形、六边形,取决于条目数),每个数据集的填充区域轮廓也是直线边多边形。适合强调"分类轴"的硬朗风格,是雷达图最经典的外观。CIRCLE:网格刻度环为同心圆,数据轮廓则为平滑的圆形边(fl_chart 会以圆形方式绘制各数据点间的连线)。视觉上更柔和,接近"蜘蛛网"与"雷达圈"混合的形态。
选择建议:展示离散分类维度对比(如平台、季度)时,POLYGON 的直线边更利于观察顶点数值;追求更柔和、偏向"仪表盘"风格时,CIRCLE 更合适。
底层渲染原理:Flutter 端如何解析 radar_shape
Flet 是"Python 声明 UI、Flutter 渲染"的框架。radar_shape 参数从 Python 端序列化为控件属性字符串后,由 Flutter 端解析并映射到 fl_chart 库的 RadarShape 枚举。
解析逻辑位于 utils/radar_chart.dart:
RadarShape? parseRadarShape(String? value, [RadarShape? defaultValue]) {
if (value == null) return defaultValue;
return RadarShape.values.firstWhereOrNull(
(e) => e.name.toLowerCase() == value.toLowerCase()) ??
defaultValue;
}
该函数按不区分大小写的方式匹配枚举名(circle / polygon),若传入未知值则回退到默认值。在 radar_chart.dart 中,Flutter 控件这样消费该属性:
radarShape: parseRadarShape(
widget.control.get("radar_shape"), RadarShape.polygon)!,
可以看到:如果 Python 端未设置该属性,Flutter 端默认回退为 RadarShape.polygon,与 Python 端枚举的默认值 RadarShape.POLYGON 保持一致,两端默认行为完全对齐。
同一个 Flutter 实现还展示了与雷达图外观密切相关的兄弟参数如何被读取,这些参数与 radar_shape 一起决定了雷达图最终观感:
radar_bgcolor:雷达区域背景色,默认透明;radar_border_side:雷达区域外轮廓线,默认 2.0 宽度;grid_border_side:雷达网格线样式,默认 2.0 宽度;tick_border_side:刻度环线样式,默认 2.0 宽度;tick_count:从中心到边缘绘制的刻度环数量,默认 1;center_min_value:最小值是否放置在图表中心。
这些参数与 radar_shape 配合,即可完整控制"圆形/多边形 + 网格 + 刻度环 + 外框"的整体骨架。
与 RadarShape 配套使用的完整参数体系
围绕 radar_shape,RadarChart 提供了一组专门控制雷达区域外观与刻度的参数(全部定义于 radar_chart.py),建议组合使用以获得理想的图表效果:
| 参数 | 默认值 | 说明 |
|---|---|---|
radar_shape |
RadarShape.POLYGON |
网格与数据轮廓形状,可选 CIRCLE / POLYGON |
radar_bgcolor |
ft.Colors.TRANSPARENT |
雷达区域背景色 |
radar_border_side |
BorderSide(width=2.0) |
雷达区域外轮廓描边 |
grid_border_side |
BorderSide(width=2.0) |
雷达网格线样式 |
tick_border_side |
BorderSide(width=2.0) |
刻度环线样式 |
tick_count |
1 |
从中心到边缘的刻度环数量,必须 >= 1,否则抛出 ValueError |
ticks_text_style |
None |
刻度标签文字样式 |
center_min_value |
False |
最小值是否位于图表中心 |
title_position_percentage_offset |
0.2 |
标题相对中心的距离比例,必须在 0~1 之间,否则抛出 ValueError |
title_text_style |
None |
环绕标题的文字样式 |
animation |
150ms 线性动画 |
图表数据更新时的隐式动画 |
源码中的参数校验逻辑(radar_chart.py)值得注意:
def init(self):
super().init()
entries_lengths = {len(ds.entries) for ds in self.data_sets}
if len(entries_lengths) > 1:
raise ValueError(
"All data sets in the data_sets list must have equal number of entries"
)
if not (0 <= self.title_position_percentage_offset <= 1):
raise ValueError("title_position_percentage_offset must be between 0 and 1")
if self.tick_count is not None and self.tick_count < 1:
raise ValueError("tick_count must be greater than or equal to 1")
即:所有数据集的条目数必须一致(否则形状无法闭合、角度无法对齐)、标题偏移必须在 0~1 之间、刻度环数量不能小于 1。编写雷达图时,条目数一致性是最容易踩的坑——titles 的数量也应与每个 RadarDataSetEntry 的数量一一对应。
快速上手指南
- 安装依赖:确保已安装
flet与flet-charts(雷达图功能位于sdk/python/packages/flet-charts扩展包中)。 - 导入命名空间:
import flet as ft与import flet_charts as fch。 - 构造数据:为每个维度准备一个
fch.RadarDataSetEntry(value),多个数据集组成data_sets列表,所有数据集条目数保持一致。 - 配置标题:用
fch.RadarChartTitle(text=...)提供与条目数相等的维度标签。 - 选择形状:设置
radar_shape=fch.RadarShape.CIRCLE(圆形)或fch.RadarShape.POLYGON(多边形,默认)。 - 运行:
ft.run(main)启动应用,即可在桌面 / Web / 移动端看到雷达图。
小结
RadarShape 是 Flet 雷达图外观体系中一个虽小却关键的枚举:仅两个成员,却决定了整张雷达图的网格骨架与数据轮廓风格。通过 RadarChart(radar_shape=...) 一行参数即可在圆形与多边形两种形态间切换;其默认值在 Python 端(RadarShape.POLYGON)与 Flutter 渲染端(RadarShape.polygon)保持一致,字符串解析不区分大小写,容错友好。配合 tick_count、center_min_value、grid_border_side 等参数,你可以快速定制出符合业务风格的多维对比图表。仓库中的官方示例(radar_chart/main.py)与集成测试(test_radar_chart.py)是两种形态最直接的可运行参考。