Flet Charts 雷达图图形形状(RadarShape)完整指南:圆形与多边形网格的用法与实现

原创2026-09-21 11:02:061,751 阅读
文章标签:前端跨平台UI组件桌面应用移动开发Web框架

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 的数量一一对应。

快速上手指南

  1. 安装依赖:确保已安装 flet 与 flet-charts(雷达图功能位于 sdk/python/packages/flet-charts 扩展包中)。
  2. 导入命名空间:import flet as ft 与 import flet_charts as fch。
  3. 构造数据:为每个维度准备一个 fch.RadarDataSetEntry(value),多个数据集组成 data_sets 列表,所有数据集条目数保持一致。
  4. 配置标题:用 fch.RadarChartTitle(text=...) 提供与条目数相等的维度标签。
  5. 选择形状:设置 radar_shape=fch.RadarShape.CIRCLE(圆形)或 fch.RadarShape.POLYGON(多边形,默认)。
  6. 运行: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)是两种形态最直接的可运行参考。

登录后查看全文
flet