企业官网建设流程全解析

• 前端
• 跨平台
• 桌面应用
• 移动开发

FadingFour 是 Flet 扩展包flet-spinkit提供的 30 个动画加载指示器（Spinner）之一：四个圆点按方阵排列、依次淡入淡出，构成经典的旋转加载动效。本文将围绕该控件的类定义、三个核心属性（color、size、duration）、渲染层的实现原理、示例用法与测试验证展开，帮助你直接在 Flet 应用中用纯 Python 代码接入这套基于 Flutterflutter_spinkit的动画体系。

FadingFour 在 Flet 生态中的定位

flet-spinkit是一个 Flet 扩展包，提供了 30 个动画加载指示器控件，全部构建在 Flutter 的flutter_spinkit包之上。这些控件以ft.control("SpinKit...")装饰器注册为 Flet 自定义控件，Python 端属性经 Flet 协议下发到 Flutter 端渲染。

FadingFour的 Python 类定义位于 spinkit.py：

@ft.control("SpinKitFadingFour") class FadingFour(ft.LayoutControl): """Four dots arranged in a square that fade in sequence.""" color: Optional[ft.ColorValue] = None """The color of the spinner.""" size: Optional[ft.Number] = None """The size of the spinner in pixels. Defaults to 50.""" duration: Optional[ft.DurationValue] = None """The duration of one animation cycle."""

从源码结构看，FadingFour继承自ft.LayoutControl，即它属于布局型控件，可像普通容器一样放入Row、Column、Container等任意布局中，并参与间距、对齐、滚动等布局计算。整个 SpinKit 家族在spinkit.py中采用完全一致的类结构（RotatingPlain、Wave、WanderingCubes、Pulse等 30 个控件均为此模式），因此掌握FadingFour的用法后即可举一反三。

安装与引入

在 Flet 项目中启用flet-spinkit：

uv add flet-spinkit

或使用 pip：

pip install flet-spinkit

使用 pip 安装后，需要手动将该包加入requirements.txt或pyproject.toml，以保证依赖可复现。安装完成后在应用中引入：

import flet_spinkit as spins

FadingFour已从包根导出（见init.py），可直接通过spins.FadingFour访问。

属性详解

FadingFour共有三个可配置属性，均为可选参数（省略时使用 Flutter 端默认值）：

color

控制四个圆点的颜色。若未指定，Flutter 端会回退到主题主色Theme.of(context).primaryColor，因此它能自动适配应用的明暗主题。传入ft.Colors.BLUE、ft.Colors.RED等常量即可快速换色。

size

指示器的整体尺寸（逻辑像素）。spinkit_props示例中对ThreeBounce展示了 20、30、40、50、70 的梯度效果，FadingFour同理——尺寸越大，四个圆点的间距与半径等比放大。

duration

一个动画周期（四个圆点依次淡入淡出一遍）的时长。类型为ft.DurationValue，传入方式：

spins.FadingFour(color=ft.Colors.BLUE, size=50, duration=ft.Duration(milliseconds=1800))

Flutter 端渲染代码位于 spinkit.dart：

case "SpinKitFadingFour": return SpinKitFadingFour( color: color, size: size, duration: duration ?? const Duration(milliseconds: 1200), );

即FadingFour的默认周期为 1200ms，与Wave、FadingCircle、CubeGrid等多数 SpinKit 动画一致。若想放缓动画节奏，可传入更大的duration；反之传入更小值让指示器显得更急促。

渲染原理：从 Python 属性到 Flutter 动画

在 Flutter 端，spinkit.dart 中的SpinKitControl负责把 Flet 下发的控件属性解析为flutter_spinkit的配置：

• color通过widget.control.getColor("color", context)读取，未设置时取主题主色；
• size通过getDouble("size", 50.0)读取，默认 50；
• duration通过getDuration("duration")读取，未设置时由createSpinKit按各动画类型给出推荐默认值。

解析完成后，createSpinKit依据控件类型字符串（如"SpinKitFadingFour"）创建对应的flutter_spinkitWidget，最后包裹在LayoutControl中参与页面布局。这也是 30 个 SpinKit 控件共享的同一套渲染管线——类型字符串与 Python 类装饰器@ft.control("SpinKitFadingFour")一一对应，实现了 Python 控件名到 Flutter Widget 的精确映射。

在 Flet 应用中使用 FadingFour

基础用法

import flet as ft import flet_spinkit as spins def main(page: ft.Page): page.title = "FadingFour Demo" page.add( ft.Row( [ spins.FadingFour(color=ft.Colors.BLUE, size=50), ft.Text("加载中…", size=16), ], alignment=ft.MainAxisAlignment.CENTER, ) ) if __name__ == "__main__": ft.run(main)

组合展示：参照官方 Showcase

仓库在 spinkit_showcase/main.py 提供了一个完整的 GridView 展示页，将 30 个 SpinKit 控件（含FadingFour）逐格陈列，每格附带控件名称与居中展示：

ft.Container( content=ft.Column( [ ft.Container( content=cls(color=color, size=50), alignment=ft.Alignment.CENTER, expand=True, ), ft.Text(name, size=11, text_align=ft.TextAlign.CENTER), ], horizontal_alignment=ft.CrossAxisAlignment.CENTER, spacing=8, ), bgcolor=ft.Colors.SURFACE_CONTAINER_HIGHEST, border_radius=12, padding=12, )

该示例展示了把加载指示器嵌入Container/Column的标准做法：用alignment=ft.Alignment.CENTER让动画在卡片内居中，expand=True让动画占满可用空间。FadingFour同样适用于这种展示场景。

属性对照示例

spinkit_props/main.py 演示了如何系统化对比属性差异，其模式可迁移到FadingFour：

• color：同一动画分别用BLUE、RED、GREEN等颜色渲染，对比观感；
• size：ThreeBounce取 20/30/40/50/70 梯度展示尺寸对布局的影响；
• duration：Pulse取 400ms/700ms/1000ms/2000ms/4000ms，直观感受动画快慢。

按同样的section+labeled辅助函数组织页面，即可快速试出适合FadingFour的颜色、尺寸与周期组合。

与其他 SpinKit 控件的异同

FadingFour属于"方阵四圆点依次淡入"型动画。仓库中与之同族（四元素方阵布局）的还有：

• FadingCube：四个小方块组成大立方体，淡入的同时伴随旋转；
• FadingGrid：3×3 圆点阵按螺旋顺序淡入；
• FoldingCube：四个方块折叠展开，默认周期 2400ms；
• WanderingCubes：两个方块互相环绕旋转，默认周期 1800ms。

属性接口上，三者完全一致（color/size/duration），区别仅在动画形态与默认周期。若你希望指示器更"静"（纯淡入淡出），FadingFour是最直接的选择；若想要更复杂的形态，可参考 index.md 中完整的 30 控件列表。

集成测试佐证

仓库在 test_spinkit.py 中为 SpinKit 家族编写了基于flet.testing的异步集成测试。其中test_all_controls_render将全部 30 个控件（含FadingFour）放入可滚动Column渲染，验证每个控件都能正常构建；其余测试分别验证了自定义duration、wave_type、item_count、line_width、border_width等属性的传参链路。这为FadingFour的color/size/duration属性下发与渲染链路提供了自动化验证，也说明该控件可在 Flet 测试框架下按相同模式编写断言。

延伸：SpinKit Boot Screen

除了作为页面内控件，flet-spinkit还提供名为spinkit的启动屏（boot screen），在打包后的应用启动期间显示动画加载器。在pyproject.toml中配置即可，例如：

[tool.flet.boot_screen] name = "spinkit" [tool.flet.boot_screen.spinkit] spinner = "FadingFour" # 任意 SpinKit 动画（去掉 "SpinKit" 前缀） spinner_color_light = "#7c4dff" spinner_color_dark = "#b388ff" spinner_size = 60 bgcolor_light = "#ffffff" bgcolor_dark = "#0d0d12" prepare_message = "Preparing your app…" startup_message = "Starting up…"

spinner选项可直接指定FadingFour，从而让应用启动动画与页面内加载动画保持视觉一致。该启动屏是createBootScreen扩展钩子的完整实战示例，相关源码位于 boot_screen.dart，具体配置说明参见 publish/index.md 与 user-extensions.md。

小结

FadingFour是flet-spinkit中最具代表性的纯淡入淡出型加载动画之一：Python 端以@ft.control("SpinKitFadingFour")注册，暴露color、size、duration三个属性；Flutter 端通过createSpinKit工厂函数映射到flutter_spinkit的SpinKitFadingFourWidget。无论是页面内临时加载态、按钮提交反馈，还是打包应用的启动屏，只需几行纯 Python 代码即可接入。对照仓库中的 spinkit_showcase 与 spinkit_props 示例，你还可以把FadingFour的形态、配色与节奏调校到与品牌风格完全一致。

• 前端
• 跨平台
• 桌面应用
• 移动开发