flutter-visual-effects

Flutter 视觉效果

将预期的材质或光学行为转化为易于维护的 Flutter 渲染栈，而不是把效果包当作设计系统。

范围

负责效果保真度、图层合成、模糊与折射实现、着色器或 CustomPainter 的选择、效果分组、平台／后端回退，以及渲染效果验证。

是否应在产品中使用该效果，应转交给 flutter-ui-design。时序、编排、弹簧、Hero 和中断行为应转交给 flutter-animation；实测卡顿诊断应转交给 flutter-performance；原生视图或平台通道应转交给 flutter-platform-integration。

预检

1. 检查 pubspec.yaml、Flutter/Dart 约束、已启用的平台、现有图形包，以及目标表面周围的渲染代码。
2. 在内容、背景、状态和视口相同的条件下检查提供的参考。孤立的半透明矩形不足以证明效果在依赖背景时的表现。
3. 说明关键的光学行为：模糊、着色、边缘高光、深度、折射、形状融合、辉光、噪点或响应式形变。
4. 确定所需的平台覆盖范围、可接受的保真度损失、无障碍回退方案，以及是否能在有代表性的硬件上进行性能分析。
5. 从项目当前的渲染方案和依赖项出发。保留足够完善的现有效果实现；不要仅因风格偏好就用核心代码或其他包替换它。

根据证据选择，而非意识形态

1. 复用项目中已有的、足够完善的方案或包，包括其主题和回退行为。
2. 对 Flutter 核心功能能够清晰表达的简单效果，使用装饰、渐变、遮罩、阴影、CustomPainter 或裁剪后的 BackdropFilter。当只需过滤一个已知子项，而非现有背景时，使用 ImageFiltered。
3. 对复杂且常见的能力，若维护良好的包能显著降低实现风险，且满足项目的 SDK、渲染器、平台、许可证、维护和性能约束，则使用该包。
4. 当效果具有产品特异性、可接受的包无法满足保真度或平台要求，或实测证明可控性值得其维护成本时，使用自定义片段着色器或渲染器。
5. 仅当原生渲染本身是需求时才使用原生集成；并为其他每个受支持的目标定义明确的行为。

决策记录必须指出检查过的现有方案，说明为何核心功能／包／自定义实现／原生实现是保真度足够且最精简的选择，以及哪些证据会促使改变这一选择。不要仅因某个包的演示与参考相似就添加它，也不要重复实现已有成熟基础设施，而项目中已有足够完善且维护良好的依赖项。

当效果包或共享渲染器已经存在时，在提出代码方案前，必须明确检查其 pubspec／锁文件条目、源码用法、主题约定、支持的目标平台和回退方案。保留稳定的变更前样例，并在变更后使用相同内容和视口进行对比，同时标明截图或性能分析数据是计划获取还是已观察到。检查后确认足够完善的包，应在原有基础上扩展，而非替换成并行的渲染器。

对于普通的核心 Material 实现，应在决策记录中明确说明：BackdropFilter 对表面后方已绘制的内容进行采样，ImageFiltered 过滤一个由当前实现拥有的子项，不会添加效果包，并且装饰图层不提供语义信息，也不提供按下、悬停或聚焦的交互提示。

实现不变量

• 将滤镜裁剪到最小的有效范围；无界的背景滤镜可能处理远超可见表面的场景内容。
• 将玻璃效果分层构建：采样背景、可控模糊或折射、着色、边框/高光，然后是清晰易读的内容。仅靠不透明度无法营造玻璃效果。
• 将光学效果置于语义和命中测试之后。装饰性或只读图层不得提供按压、悬停、焦点或交互式辉光等交互提示；只有真正的控件才应具备这些效果。
• 在 SDK 和组合方式允许的情况下，复用或分组共享效果图层。不要在每个滚动行后方各放置一个独立的实时模糊或着色器。
• 以语义化方式集中配置效果，并为不受支持的渲染器、减少透明度、高对比度和受限硬件提供不透明或成本更低的替代方案。
• 形状变形时保持身份稳定。动画所有者负责控制时间；效果图层根据该状态推导几何形状和 uniform 参数。
• 绝不要声称与 Apple 原生材质像素级一致。请说明复现了哪些可移植属性，以及近似处理了哪些原生光学行为。

条件参考资料

• 当需要在 Flutter 中复现 SwiftUI、Liquid Glass、Material、PhaseAnimator 或匹配几何效果的参考时，请阅读 iOS 效果转换。
• 当涉及自定义 GLSL、FragmentProgram、背景扭曲、效果包、渲染器兼容性或 GPU 开销时，请阅读 着色器、软件包与性能。

验证

在具有代表性的简洁和繁杂背景上，分别使用浅色和深色主题渲染效果。比较普通、高对比度以及不透明或低成本的回退方案时，保持视口、内容、效果几何形状和交互状态一致。相关时，捕获交互或变形后的状态。检查可读性、裁剪、边缘瑕疵、滚动行为、文本缩放、高对比度、减少动态效果以及可用的减少透明度路径。

Golden 测试可以锁定确定性的几何形状和绘制输出，但若要对平台合成、系统界面或特定后端着色器作出结论，则必须使用设备截图。对于非简单的模糊、着色器或持续动画效果，应在代表性硬件上以 profile 模式进行性能分析；报告所测试的渲染器、设备类别、场景和回退方案，不要根据 debug 模式的结果进行泛化。

来源

• 自定义绘制和图形
• 编写和使用片段着色器
• BackdropFilter
• ImageFilter