Flutter 动效 UI 是做什么的?
此技能生成的 Flutter 页面,使用户感觉像是一个连贯、精雕细琢的产品:每个元素都带有意图地出现,每次点击都有回应,每个状态变化都清晰可见,数据在各个页面间保持一致。
该技能基于对 22 个参考应用录屏(钱包、配送、拼车、健身、认证/OTP、闹钟、结账、预订、设备配对)的逐帧分析蒸馏而来。references/video-analysis.md 列出了每个录屏的功能以及对应的复现方案。
核心理念:状态驱动动效
参考应用中的几乎所有“流畅”时刻都遵循相同的机制:某段状态发生了变化,UI 从旧值动画过渡到了新值。 没有任何人从按钮处理程序中调用 controller.forward()。因此,工作流程始终是:
- 明确地建模页面的状态(使用密封类,而不是五个布尔值)。
- 通过
switch分支来根据状态渲染 UI。 - 将变化的部分包裹在隐式动画中(
AnimatedSwitcher、AnimatedContainer、TweenAnimationBuilder或 Motion Kit 组件),使得状态之间的差异自动产生动画效果。
做到这一步时,动画和状态管理就不再是两个问题。中断的动画、双击以及“加载中旋转器旁边显示成功对勾”的 Bug 都会消失,因为不可能的状态组合无法被表示出来。
显式的 AnimationController 仅用于三种情况:手指驱动的交互手势、循环的环境氛围(脉冲、扫描线)以及精心编排的多部分序列。
工作流程
1. 在编写任何代码之前,先阅读项目
pubspec.yaml:Flutter/Dart SDK 版本、已使用的状态管理库(riverpod / bloc / provider / getx / 无)、路由方案(go_router / auto_route / Navigator)、已有的动画包。- 现有主题、颜色、间距、共享组件。扩展现有内容;不要引入第二套设计系统或第二套状态管理库。与项目的文件夹结构和命名保持一致。在已有的应用中,只做任务要求的最小改动(例如添加
Hero包裹器、调整内边距),除非被要求,否则不要修改无关的 lint 或样式问题,并在总结中列出所有重写的文件,以便 diff 中没有意外变动。 - 如果是新项目或没有约定,则使用此技能的默认配置(Riverpod
Notifier、带有扩展的 Material 3 主题、lib/core/+lib/features/<name>/结构)。
2. 一次性安装动效工具包
将任务所需的核心文件复制到项目的共享 UI 文件夹(默认 lib/core/motion/):始终复制 motion.dart,以及你将实际用到的组件,并精简 barrel 文件使其只包含这些组件。如果为了一个只用三个组件的页面而复制全部十个文件,会导致用户得到无人调用的代码。Motion Kit 是纯 Flutter 实现,无额外依赖,且通过了 analyzer 检查和组件测试。如果项目已经有等价组件(例如自己的时间常量文件、自己的导航栏),则适配使用他们的组件,而不是重复创建。
| 文件 | 功能 |
|---|---|
motion.dart | Motion.fast/base/slow/page/hero、曲线、弹簧、减少动效辅助函数 — 唯一存放持续时间的地方;Haptics.tap/selection/success/error — 唯一触发触觉反馈的地方 |
entrance.dart | Entrance(交错的淡入/滑动/模糊入场)、StateSwitcher(带动画的状态 switch) |
page_routes.dart | AppRoute、AppPageTransitions.theme()、showAppSheet、heroFadeShuttle |
glass_nav_bar.dart | GlassNavBar 浮动液态玻璃药丸型导航栏,带有滑动镜头指示器 |
morph_button.dart | Pressable、MorphButton(空闲→旋转器→成功)、AsyncMorphButton |
slide_to_confirm.dart | SlideToConfirm 拖动提交,带触觉反馈和状态 |
rolling_number.dart | CountUpText、RollingText(里程表数字效果) |
otp_boxes.dart | OtpBoxes、Shake |
animated_items.dart | AnimatedItems<T> — 能够为不可变列表中的插入和删除项添加动画的列表组件 |
assets/examples/send_money_flow.dart 是一个完整的流程示例(列表→键盘→滑动→发送中→成功→返回,新行以动画形式插入)。在构建任何多状态流程时请阅读它;这是需要模仿的模式。旁边的 send_money_flow_test.dart 展示了如何测试此类流程(完整路径、小屏幕溢出、减少动效)。
assets/project_setup/analysis_options.yaml 是 Motion Kit 通过的严格 lint 规则集。建议将其合并到项目的 analyzer 配置中;不要覆盖团队已选择的规则。
3. 将页面设计为状态和时刻,然后构建
在编写页面代码之前,先写下(在脑海中或简短注释中):
- 状态:这个页面可以处于哪些不同的状态?(例如
Editing → Submitting → Done | Failed) - 共享数据:这个页面展示的哪些数据也在其他页面展示?那些数据只有一个所有者。
- 时刻:入场、主要操作、每次状态变化和退出。每个操作都从下表中选择一个合适的动效。其他部分保持静止。
然后按以下顺序构建:令牌/主题 → 静态布局 → 状态层 → 状态变化动画 → 入场交错 → 导航过渡 → 触觉反馈 → 减少动效和小屏幕检查。
4. 验证
对你修改的文件运行 dart format,然后运行 flutter analyze 直到没有错误。如果有设备/模拟器,运行应用并实际观察流程;否则编写一个简短的组件测试来遍历状态(参见示例测试的结构)并运行它。然后检查 references/consistency-checklist.md。
不同时刻使用哪种动效
| 时刻 | 使用 | 时序 |
|---|---|---|
| 页面首次出现 | 对 3–7 个顶级块使用 Entrance(index: n),从上到下 | slow,间隔 55 毫秒 |
| 跳转到不相关的页面(启动→主页、认证→应用) | AppTransition.fadeThrough | page |
| 同一流程中的下一步(手机→OTP→密码) | AppTransition.sharedAxisX + 带动画的步骤指示器 | page |
| 列表项 → 其详情页 | 在图片/卡片上使用 Hero,详情页其余部分随后淡入 | hero |
| 确认 / 选择 / 评分 / 挑选 | showAppSheet,内部内容交错入场 | page |
| 请求进行中 | 使用带有 status 的 MorphButton 或 SlideToConfirm | base 每个阶段 |
| 值变化(价格、预计到达时间、余额) | RollingText(离散) / CountUpText(数量级) | base / long |
| 项目添加/移除 | AnimatedItems | base |
| 页面状态变化(加载→内容→错误) | StateSwitcher | base |
| 选择(选项芯片、卡片、标签、星级) | AnimatedContainer 颜色/边框 + 小 AnimatedScale | fast |
| 任何点击 | Pressable 缩放 + 轻微触觉反馈 | instant |
| 验证失败 | Shake + 红色边框 + 消息;保留输入 | slow |
| 成功 | 对勾以 Motion.overshoot 弹出,保持 successHold 时长,然后继续 | — |
保持品味的原则:
- 入场仅播放一次。 在懒加载列表中,滚动回视图的行会被重建并再次播放动画;请使用
Entrance(enabled: …)使得只有首次出现时才播放动画。 - 每次导航只展示一个亮点。 一个 Hero 或 一个模糊过渡 或 一个大交错 — 而不是三者都用。
- 慢入快出。 退出动画的运行时长约为进入时长的 60–80%,使用
Motion.exit。 - 相关的事物一起运动;无关的事物交错进行。
- 对变换和透明度进行动画;避免在长列表中动画化布局。 模糊代价高昂 — 仅在少数 Hero 元素上使用,绝不要在列表行中使用。
- 绝不为装饰而阻塞输入。 入场不能延迟可点击性;只有真正的工作(如网络请求)才能禁用控件。
- 尊重减少动效设置:Motion Kit 已通过
Motion.of(context, …)折叠了持续时间;在你编写的任何控制器中也应同样处理。
状态管理要点
完整指南(包含 Riverpod / Bloc / ChangeNotifier 对应方式):references/state.md。不可妥协的原则:
- 流程状态是一个密封类;UI 是穷尽的
switch。将每种状态所需的数据携带在里面。 - 每段共享数据只有一个所有者。 列表页面和详情/流程页面读取同一个 provider;由流程页面负责写入。不要通过
Navigator.pop传回结果并修补本地副本——这样会导致页面数据不同步。 - 失败时保留用户的输入。 失败的提交回到编辑状态,字段保持完整并附带错误信息。
- 副作用放在监听器中,而不是
build方法中。 导航、Snackbar、触觉反馈响应状态变化(ref.listen、BlocListener)。 - 动画状态保留在组件中;业务状态绝不保留在组件中。 控制器知道状态
Submitting;它不知道有关AnimationController的任何事情。 - 实时数据是映射到状态的流(例如预计到达时间、司机位置、订单状态),组件在两次更新之间插值,使得即使更新频率为每秒一次,动画也能连续平滑。
- 在
await之后,访问状态前要检查异步间隙的安全(ref.mounted/isClosed/mounted)。
UI 一致性
一致性是将设计良好的应用与一堆漂亮页面区分开来的关键。将令牌放在主题中,不要在组件中硬编码:
- 颜色:
ColorScheme+ 用于品牌额外内容的ThemeExtension(成功色、玻璃色调、渐变)。组件读取Theme.of(context);这也使得明暗主题的动画切换变得零成本。 - 间距:4 点刻度(4、8、12、16、20、24、32)。整个应用使用统一的水平页面内边距。
- 圆角:三个值(例如 12 小 / 20 卡片 / 28 底部弹窗)加上药丸形。相同卡片在任何地方都使用相同圆角。
- 字体:仅使用
TextTheme角色;任何会变化的数字使用表格数字。 - 动效:仅使用
Motion.*。 - 组件:一个主按钮、一种底部弹窗样式、一种输入框样式、一个导航栏。如果出现第二个变体,将其提升为带参数的共享组件。
详情和审查清单:references/consistency-checklist.md。
代码质量标准
动画 UI 会放大粗心代码的代价:每秒运行 120 次的 build 方法、生命周期超过页面的控制器、只适配一款手机的布局。确保每个文件都达到 Motion Kit 的质量标准。references/flutter-best-practices.md 提供了完整的指导;最容易出错的几点:
- 使用小组件类,而不是
_buildX()辅助方法,并带有const构造函数 — 这样重建时只影响变化了的部分。 - 所有创建的内容都要释放:动画/文本/滚动/页面控制器、
CurvedAnimation、焦点节点、计时器、订阅。 - 保护每个异步间隙(
context.mounted/ref.mounted/isClosed),绝不静默丢弃 Future(await或unawaited)。 - 稳定的键:在动态列表和
AnimatedSwitcher的子组件上使用ValueKey(item.id);绝不使用索引键,绝不在build中创建键。 - 布局可滚动而不是溢出:任何包含键盘、表单或选择器的页面必须能在 320×480 视口、打开键盘和 1.3 倍字体大小的情况下正常工作。
- 每个页面都能在窄屏和大字体下生存,而不仅仅是你被要求处理的流程:在 320 宽度、1.6 倍字体大小下,包含标题和金额的
Row、包含数字和标签的卡片或列表磁贴,如果不使用Expanded/Flexible配合maxLines和overflow,就会横向溢出。编写一个测试,在 320×568 下渲染应用的第一个页面(和每个标签页),并设置tester.platformDispatcher.textScaleFactorTestValue = 1.6,预期不抛出异常。 - 测试不愉快的交互:提前释放的拖动、加载时的第二次点击、请求中按返回键。这些路径包含了从头到尾的测试从未触及的崩溃点。
- 功能代码中无字面量:颜色、圆角、间距、持续时间、触觉反馈都来自主题/令牌/
Motion/Haptics;面向用户的字符串遵循项目的本地化设置。 - 懒加载列表和局部重建:任何可滚动内容使用 builder,对变化的值使用
select,静态子树作为child传入。 - 可访问性内建:自定义控件上添加语义信息,为仅手势操作提供替代方案,尊重减少动效设置。一个
Semantics(label: …, excludeSemantics: true)包装器也会移除子组件的点击操作——同时将onTap传递给Semantics。 - 在关键处进行测试:控制器状态转换作为单元测试;每个流程编写一个组件测试来断言结果,而不是动画内部细节。
参考文件 — 阅读与任务匹配的文件
references/motion-system.md— 令牌说明、编排、以及 Motion Kit 未包含的效果的配方(启动屏序列、模糊聚焦、进度环、扫描线、颜色/主题插值、滚动关联的头部)。references/navigation-transitions.md— 页面过渡、Hero 的正确用法、容器变换、底部弹窗、多步骤流程、与 go_router 的集成。references/glass-nav-bar.md— 液态玻璃导航栏的构建、调优、性能、外壳/标签状态、已知陷阱。references/state.md— 流程状态、共享状态、异步/乐观模式、实时流,分别用于 Riverpod、Bloc 和 ChangeNotifier。references/components.md— 配方:步骤进度、可选卡片/芯片、带响应式标签的星级评分、重新着色的卡片轮播、滚轮选择器、骨架屏、实时追踪页 + 路线标记、持久迷你状态栏。references/video-analysis.md— 分析的 22 个录屏:屏幕上发生的事情以及如何复现。references/flutter-best-practices.md— 项目结构、组件组合、生命周期、异步安全、Dart 3 习惯、鲁棒布局、性能、主题化、本地化/可访问性、错误状态、测试、工具。在创建新项目结构或审查/重构现有代码之前阅读。references/consistency-checklist.md— 令牌、交付前质量保证、性能和可访问性检查。
输出期望
- 在项目结构中交付完整、可运行的文件 — 而不是带有“……你的其余代码”的片段。
- 使用项目现有的包。仅当新包能明确证明其价值时才建议添加,并说明原因。
- Flutter API 变化很快。如果安装的 SDK 比你确定的版本更新,请检查签名(
flutter analyze是最快的判官)而不是猜测。 - 完成后,简要告诉用户哪些时刻被动画化了,以及状态结构是什么。