Communitygithub.com

Flutter 动效 UI

构建精致、流畅的 Flutter 用户界面,将动效与状态统一设计——包括页面过渡、Hero/共享元素动画、液态玻璃浮动导航栏、交错入场、底部弹窗确认、滑动确认、OTP 验证码与多步骤认证流、加载转成功的变形按钮、滚动数字、列表插入/删除动画、实时追踪界面、主题切换,以及保持界面一致的状态管理(密封流程状态、单一数据源、乐观更新)。当用户要求构建、设计、重新样式、动画化或让任何 Flutter 页面、组件、流程或应用(启动屏、引导页、认证、首页、详情页、结账、个人资料、配送、拼车、钱包、健身)更流畅、更高级时,或提及 Flutter 过渡、Hero、玻璃拟态/液态玻璃、微交互、UI 一致性、设计令牌、卡顿动画或用于 UI 的状态管理(Riverpod、Bloc、Provider、混乱的 setState)时,请使用此技能。

Flutter 动效 UI 是什么?

Flutter Motion UI 技能旨在帮助开发者为 Flutter 应用构建高度精致、流畅且状态驱动的用户界面。其核心理念是“状态驱动动效”:通过将屏幕状态建模为密封类,并在状态切换时使用隐式动画(如 AnimatedSwitcher、AnimatedContainer),使动效与状态管理自然融合,避免了手动控制动画控制器的复杂性和潜在错误。该技能提供了一套完整的 Motion Kit(位于 lib/core/motion/),包含丰富的预构建动效组件,如 Entrance(交错入场)、StateSwitcher(状态切换动画)、MorphButton(加载转成功按钮)、SlideToConfirm(滑动确认)等,覆盖了从页面过渡、列表操作到微交互的常见场景。此外,它强调 UI 一致性,要求通过主题扩展、间距比例和组件规范来实现统一的设计语言,并内置了严格的代码质量标准,如无状态组件、资源正确释放、布局鲁棒性、辅助功能支持等。无论是创建新项目还是优化现有 UI,该技能都提供了从设计到实施再到验证的完整工作流,参考了 22 个实际应用的帧级分析,确保输出专业、稳定的代码。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Ismail554/flutter-motion-ui-skill/tree/HEAD/flutter-motion-ui

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Flutter 动效 UI 是做什么的?

此技能生成的 Flutter 页面,使用户感觉像是一个连贯、精雕细琢的产品:每个元素都带有意图地出现,每次点击都有回应,每个状态变化都清晰可见,数据在各个页面间保持一致。

该技能基于对 22 个参考应用录屏(钱包、配送、拼车、健身、认证/OTP、闹钟、结账、预订、设备配对)的逐帧分析蒸馏而来。references/video-analysis.md 列出了每个录屏的功能以及对应的复现方案。

核心理念:状态驱动动效

参考应用中的几乎所有“流畅”时刻都遵循相同的机制:某段状态发生了变化,UI 从旧值动画过渡到了新值。 没有任何人从按钮处理程序中调用 controller.forward()。因此,工作流程始终是:

  1. 明确地建模页面的状态(使用密封类,而不是五个布尔值)。
  2. 通过 switch 分支来根据状态渲染 UI。
  3. 将变化的部分包裹在隐式动画中(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.dartMotion.fast/base/slow/page/hero、曲线、弹簧、减少动效辅助函数 — 唯一存放持续时间的地方;Haptics.tap/selection/success/error — 唯一触发触觉反馈的地方
entrance.dartEntrance(交错的淡入/滑动/模糊入场)、StateSwitcher(带动画的状态 switch)
page_routes.dartAppRoute、AppPageTransitions.theme()、showAppSheet、heroFadeShuttle
glass_nav_bar.dartGlassNavBar 浮动液态玻璃药丸型导航栏,带有滑动镜头指示器
morph_button.dartPressable、MorphButton(空闲→旋转器→成功)、AsyncMorphButton
slide_to_confirm.dartSlideToConfirm 拖动提交,带触觉反馈和状态
rolling_number.dartCountUpText、RollingText(里程表数字效果)
otp_boxes.dartOtpBoxes、Shake
animated_items.dartAnimatedItems<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.fadeThroughpage
同一流程中的下一步(手机→OTP→密码)AppTransition.sharedAxisX + 带动画的步骤指示器page
列表项 → 其详情页在图片/卡片上使用 Hero,详情页其余部分随后淡入hero
确认 / 选择 / 评分 / 挑选showAppSheet,内部内容交错入场page
请求进行中使用带有 status 的 MorphButton 或 SlideToConfirmbase 每个阶段
值变化(价格、预计到达时间、余额)RollingText(离散) / CountUpText(数量级)base / long
项目添加/移除AnimatedItemsbase
页面状态变化(加载→内容→错误)StateSwitcherbase
选择(选项芯片、卡片、标签、星级)AnimatedContainer 颜色/边框 + 小 AnimatedScalefast
任何点击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 是最快的判官)而不是猜测。
  • 完成后,简要告诉用户哪些时刻被动画化了,以及状态结构是什么。

相关技能