1. 简介
构建内容
Material 3 是 Google 的开源设计体系,用于构建富有表现力、自适应的界面。在此 Codelab 中,您将从一个空白 Flutter 应用开始,然后与 Google Antigravity 协作,构建一个由 material_ui 软件包赋能、完全样式化且动画形式的即时通讯应用。
您完成的应用满足以下要求:
- 采用自适应设计,可在手机、平板电脑和桌面设备屏幕尺寸之间无缝调整。
- 编排交错动画,在底部
NavigationBar、侧边NavigationRail和双窗格列表详情视图之间流畅过渡。 - 使用
package:material_ui/material_ui.dart应用 Material 3 配色方案、表面色调和排版。 - 在 Android、iOS、Web、Windows、Linux 和 macOS 上运行。

您的学习之旅
此 Codelab 将逐步引导您构建自适应即时通讯应用:
- 设置 Flutter 环境 - 为目标平台配置 Flutter SDK 和 Google Antigravity。
- 开始使用 - 提示 Antigravity 使用
material_ui软件包搭建一个空的 Flutter 项目。 - 制作一款即时通讯应用 - 添加用户头像、消息模型和 Material 3 收件箱 widget(
EmailListView、EmailWidget、SearchBar和StarButton)。 - 添加
NavigationBar- 定义顶级目的地,并为窄屏设备连接底部NavigationBar。 - 添加
NavigationRail- 当窗口宽度超过600像素时,在底部的NavigationBar和左侧的NavigationRail之间切换。 - 为过渡添加动画效果 - 精心编排交错的
CurvedAnimation间隔和过渡微件,以便在调整大小时,底部导航栏、侧边导航栏和 FAB 能够顺畅变形。 - 添加列表详情视图 - 使用
ListDetailTransition在宽屏上展开为双窗格收件箱和消息串式回复布局。
学习内容
- 如何与 Google Antigravity 协作,以迭代方式构建和自定义自适应 Material 3 Flutter 应用。
- 如何使用 Material 3
ColorScheme角色、Color.alphaBlend表面色调以及TextTheme和package:material_ui/material_ui.dart为 widget 设置样式。 - 如何使用 widget 级约束条件 (
LayoutBuilder) 和屏幕级指标 (MediaQuery) 构建自适应布局。 - 如何使用
AnimationController、CurvedAnimation、Interval和TweenSequence协调多部分显式动画。
前提条件
- 基本熟悉 Flutter 和 Dart 语法。
2. 设置您的 Flutter 环境
编辑者
此 Codelab 使用 Google Antigravity 作为 AI 优先的开发环境。在每个步骤中,您都会提示 Antigravity 生成或改进应用的组件,查看生成的代码中的关键 Flutter 和 Material 3 概念,并可选择探索不同的设计。
安装 Flutter
如需获取关于如何安装 Flutter SDK 的最新说明,请随时访问 docs.flutter.dev。
对于此 Codelab,请安装以下软件:
- Flutter SDK
- 已启用官方 Dart 和 Flutter 插件的 Google Antigravity(可在插件市场的 Build with Google 部分中找到)。
- 您选择的目标开发平台所需的编译器软件(例如:以 Windows 为目标开发平台时,需要 Visual Studio;以 macOS 或 iOS 为目标开发平台时,需要 Xcode;以 Web 为目标开发平台时,需要 Chrome)。
如需验证您的环境是否已针对所选部署目标进行设置,请运行 flutter doctor:
flutter doctor
如果输出中列出的问题会影响您选择的部署目标,请运行 flutter doctor -v 查看详细的问题排查步骤,或联系 Flutter 社区。
3. 使用入门
提示 Antigravity 创建项目
大多数 Flutter 开发者会使用 flutter create 创建一个基本的计数器应用,然后花费几分钟时间移除不需要的样板。传递 --empty 标志会创建一个仅包含基本要素的最小 Flutter 项目,然后您可以将其与 material_ui 软件包配对。
- 启动 Google Antigravity,然后打开一个空目录,用于构建项目(选择不需要提权或不包含空格的路径,例如主目录中的文件夹或
C:\src\)。 - 在 Antigravity 智能体对话面板中,发送以下提示,以创建 Flutter 项目、添加
material_ui并关联初始应用:
Create a new empty Flutter project named `animated_responsive_layout` for a Material 3 adaptive messaging app. Add the `material_ui` package, and update `lib/main.dart` to import `package:material_ui/material_ui.dart` and run the initial `MainApp` widget.
了解生成的代码
Antigravity 会运行 flutter create animated_responsive_layout --empty,将 material_ui 添加到 pubspec.yaml,并更新 lib/main.dart 以导入 package:material_ui/material_ui.dart:
import 'package:material_ui/material_ui.dart';
void main() {
runApp(const MainApp());
}
运行并测试应用
在您选择的目标设备(例如 Chrome 或桌面设备)上运行应用,以验证空脚手架是否能顺利构建和启动:

4. 创建一个通讯交流应用
头像素材资源和收件箱微件
每个即时通讯应用都需要用户头像和对话示例。在此步骤中,Antigravity 会将 8 个图片素材资源(avatar_1.png 到 avatar_7.png 以及 thumbnail_1.png)下载到项目根目录下的 assets/ 文件夹中:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
除了在 pubspec.yaml 中注册这些资源外,您还需要提示 Antigravity 创建数据模型(lib/models/models.dart 和 lib/models/data.dart)以及 lib/widgets/ 下的四个 Material 3 界面 widget:
search_bar.dart:一个胶囊状搜索输入框,其中显示活跃用户的头像。star_button.dart:一个收藏按钮,在切换时会与AnimatedRotation一起旋转。email_widget.dart:一种多功能卡片,可呈现邮件预览、完整会话串消息 (EmailContent)、会话串标题 (EmailHeadline) 和操作按钮 (EmailReplyOptions)。email_list_view.dart:一个可滚动列表,其中包含搜索栏和电子邮件卡片。
提示 Antigravity 构建收件箱界面
在 Antigravity 中发送以下提示:
Download `avatar_1.png` through `avatar_7.png` and `thumbnail_1.png` from `https://github.com/flutter/codelabs/tree/main/animated-responsive-layout/step_04/assets` (using raw URLs like `https://raw.githubusercontent.com/flutter/codelabs/main/animated-responsive-layout/step_04/assets/avatar_1.png`) into `assets/` and register them under `flutter: assets:` in `pubspec.yaml`. Create the messaging data models (`Attachment`, `Email`, `Name`, and `User`) in `lib/models/models.dart` and populate sample users (`user_0` through `user_4`), `emails`, and `replies` in `lib/models/data.dart`. Then create the Material 3 messaging widgets using `package:material_ui/material_ui.dart`: a rounded `SearchBar` (`lib/widgets/search_bar.dart`), a toggleable `StarButton` using `AnimatedRotation` (`lib/widgets/star_button.dart`), an `EmailWidget` (`lib/widgets/email_widget.dart`) with `EmailContent`, `EmailHeadline`, and `EmailReplyOptions` that adapt to `LayoutBuilder` constraints and selection state, and an `EmailListView` (`lib/widgets/email_list_view.dart`, importing `search_bar.dart as search_bar`). Finally, update `lib/main.dart` to display `Feed(currentUser: data.user_0)` with a surface-tinted background and a tertiary-colored `FloatingActionButton`.
了解生成的代码
EmailWidget 中的表面色调和 Dart 3 switch 表达式
在 lib/widgets/email_widget.dart 中,_EmailWidgetState 会从周围的 Theme.of(context).colorScheme 派生其卡片颜色。它不会对十六进制颜色码进行硬编码,而是在 _colorScheme.surface 上混合 _colorScheme.primary 的细微色调,并使用 Dart 3 对象模式 switch 表达式为会话视图、所选预览和未选预览选择合适的 Surface 颜色:
late final ColorScheme _colorScheme = Theme.of(context).colorScheme;
late Color unselectedColor = Color.alphaBlend(
_colorScheme.primary.withAlpha(20),
_colorScheme.surface,
);
Color get _surfaceColor => switch (widget) {
EmailWidget(isPreview: false) => _colorScheme.surface,
EmailWidget(isSelected: true) => _colorScheme.primaryContainer,
_ => unselectedColor,
};
同样,EmailContent 会使用关系模式通过 Duration getter(inSeconds: < 60、inMinutes: < 60、inHours: < 24 和 inDays: < 365)设置发送者的相对 lastActiveLabel 的格式。
使用 LayoutBuilder 实现微件级自适应
即使在您添加屏幕级导航断点之前,EmailContent、EmailHeadline 和 EmailReplyOptions 也会使用 LayoutBuilder 来防止在单个卡片变窄时(例如在分屏过渡期间)发生布局溢出:
LayoutBuilder(
builder: (context, constraints) {
return Row(
crossAxisAlignment: CrossAxisAlignment.center,
children: [
if (constraints.maxWidth - 200 > 0) ...[
CircleAvatar(
backgroundImage: AssetImage(
widget.email.sender.avatarUrl,
),
),
const Padding(
padding: EdgeInsets.symmetric(horizontal: 6.0),
),
],
// Sender name and last active timestamp...
if (constraints.maxWidth - 200 > 0) ...[const StarButton()],
],
);
},
),
当 constraints.maxWidth 降至 200 像素或更少时,头像和星标按钮会自动隐藏,因此发件人的姓名和时间戳永远不会溢出。
StarButton 中的隐式轮换和导入别名
在 lib/widgets/star_button.dart 中,切换已加星标的消息会更新 state,并使用 Flutter 的隐式 AnimatedRotation widget 平滑旋转图标:
@override
Widget build(BuildContext context) {
return AnimatedRotation(
turns: turns,
curve: Curves.decelerate,
duration: const Duration(milliseconds: 300),
child: FloatingActionButton(
elevation: 0,
shape: const CircleBorder(),
backgroundColor: _colorScheme.surface,
onPressed: () => _toggle(),
child: Padding(padding: const EdgeInsets.all(10.0), child: icon),
),
);
}
运行并测试应用
执行热重启(或停止并重新运行应用,以便 Flutter 捆绑 pubspec.yaml 中的新 assets/ 条目)。您应该会看到设置了样式的收件箱列表和搜索栏:

5. 添加 NavigationBar
在上一步末尾,应用会显示一个消息列表,但没有顶级导航。在此步骤中,您将定义四个应用目的地(Inbox、Articles、Messages 和 Groups),并在 Scaffold 底部添加 Material 3 NavigationBar。
向 Antigravity 发出提示,让它添加一条NavigationBar
在 Antigravity 中发送以下提示:
Create `lib/destinations.dart` using `package:material_ui/material_ui.dart` with a `Destination(this.icon, this.label)` class and four `destinations`: Inbox (`Icons.inbox_rounded`), Articles (`Icons.article_outlined`), Messages (`Icons.messenger_outline_rounded`), and Groups (`Icons.group_outlined`). In `lib/main.dart`, add `int selectedIndex = 0` to `_FeedState`, wire `selectedIndex` and `onSelected` into `EmailListView`, and add a Material 3 `NavigationBar` as the `Scaffold.bottomNavigationBar` mapped from `destinations`.
了解生成的代码
对导航目的地进行建模
将导航元数据分离到 lib/destinations.dart 中,可使数据独立于呈现它的特定导航 widget。在下一步中,当底部 NavigationBar 和侧边 NavigationRail 共享同一列表时,这一点至关重要:
class Destination {
const Destination(this.icon, this.label);
final IconData icon;
final String label;
}
const List<Destination> destinations = <Destination>[
Destination(Icons.inbox_rounded, 'Inbox'),
Destination(Icons.article_outlined, 'Articles'),
Destination(Icons.messenger_outline_rounded, 'Messages'),
Destination(Icons.group_outlined, 'Groups'),
];
lib/main.dart中的NavigationBar布线
在 _FeedState.build 中,destinations 直接映射到 Scaffold.bottomNavigationBar 内的 NavigationDestination widget,并与 EmailListView 共享 selectedIndex:
bottomNavigationBar: NavigationBar(
elevation: 0,
backgroundColor: Colors.white,
destinations: destinations.map<NavigationDestination>((d) {
return NavigationDestination(icon: Icon(d.icon), label: d.label);
}).toList(),
selectedIndex: selectedIndex,
onDestinationSelected: (index) {
setState(() {
selectedIndex = index;
});
},
),
在 NavigationBar 中选择一个目的地后,EmailListView 中的相应卡片会突出显示;点按电子邮件卡片后,NavigationBar 中的有效目的地会更新。
运行并测试应用
热重载应用,然后点按底部 NavigationBar 或电子邮件列表中的内容,验证所选内容是否保持同步:

这种布局在窄屏纵向模式下效果很好,但如果您加宽窗口或将移动模拟器旋转到横向模式,则在宽屏上拉伸底部栏会浪费横向空间。在下一步中,您将在屏幕足够宽时在左侧引入一个 NavigationRail。
6. 添加侧边导航栏
为了使导航布局适应当前屏幕宽度,您需要将底部栏重构为 DisappearingBottomNavigationBar,为宽屏创建 DisappearingNavigationRail,并在 600 像素宽度断点处在两者之间切换。
提示 Antigravity 添加自适应 NavigationRail
在 Antigravity 中发送以下提示:
Refactor the bottom `NavigationBar` into a `DisappearingBottomNavigationBar` widget (`lib/widgets/disappearing_bottom_navigation_bar.dart`), and create a `DisappearingNavigationRail` widget (`lib/widgets/disappearing_navigation_rail.dart`) using `NavigationRail` with a leading menu `IconButton`, a rounded-rectangle compose `FloatingActionButton`, `groupAlignment: -0.85`, and `destinations`. In `lib/main.dart`, track `bool wideScreen = width > 600` in `didChangeDependencies()` using `MediaQuery.of(context).size.width`, show `DisappearingNavigationRail` in a `Row` alongside the expanded `EmailListView` when `wideScreen` is true, and hide the `Scaffold`'s `floatingActionButton` and `bottomNavigationBar` on wide screens.
了解生成的代码
构建 DisappearingNavigationRail
在 lib/widgets/disappearing_navigation_rail.dart 中,NavigationRail 会垂直呈现相同的 destinations 列表,并将菜单按钮和撰写 FloatingActionButton 放入其 leading 槽中:
return NavigationRail(
selectedIndex: selectedIndex,
backgroundColor: backgroundColor,
onDestinationSelected: onDestinationSelected,
leading: Column(
children: [
IconButton(onPressed: () {}, icon: const Icon(Icons.menu)),
const SizedBox(height: 8),
FloatingActionButton(
shape: const RoundedRectangleBorder(
borderRadius: BorderRadius.all(Radius.circular(15)),
),
backgroundColor: colorScheme.tertiaryContainer,
foregroundColor: colorScheme.onTertiaryContainer,
onPressed: () {},
child: const Icon(Icons.add),
),
],
),
groupAlignment: -0.85,
destinations: destinations.map((d) {
return NavigationRailDestination(
icon: Icon(d.icon),
label: Text(d.label),
);
}).toList(),
);
正在检测 didChangeDependencies 中的屏幕宽度
在 lib/main.dart 中,_FeedState 会替换 didChangeDependencies(),以便在窗口大小或设备屏幕方向发生变化时查询 MediaQuery.of(context).size.width:
bool wideScreen = false;
@override
void didChangeDependencies() {
super.didChangeDependencies();
final double width = MediaQuery.of(context).size.width;
wideScreen = width > 600;
}
当 wideScreen 为 true 时,Scaffold 会将 DisappearingNavigationRail 作为正文 Row 的第一个子级插入,并将 floatingActionButton 和 bottomNavigationBar 都设置为 null。
运行并测试应用
热重载应用,并调整窗口大小,使其跨越 600 像素阈值,以比较窄布局和宽布局:
|
|
在两种不同的布局之间切换是可行的,但从导航栏到侧边导航栏的瞬间跳转会让人感觉很突兀。在下一步中,您将在这两个布局之间编排流畅的动画。
7. 为过渡添加动画效果
创建精美的自适应过渡效果需要沿共享时间轴编排多个动画。您无需立即将微件换成 if (wideScreen),而是在屏幕宽度超过 600 像素时向前驱动 AnimationController,在屏幕宽度变窄时向后驱动,将其 0.0 到 1.0 时间轴切分为交错的 Interval 曲线。
提示 Antigravity 为布局过渡添加动画效果
在 Antigravity 中发送以下提示:
Create `lib/animations.dart` defining staggered `CurvedAnimation` and `ReverseAnimation` classes (`BarAnimation`, `OffsetAnimation`, `RailAnimation`, `RailFabAnimation`, `ScaleAnimation`, `ShapeAnimation`, and `SizeAnimation`) using `Interval`s and `Curves.easeInOutCubicEmphasized`. Create `BottomBarTransition` (`lib/transitions/bottom_bar_transition.dart`) and `NavRailTransition` (`lib/transitions/nav_rail_transition.dart`) that combine `ClipRect`, `Align` (`heightFactor` and `widthFactor`), and `FractionalTranslation` to slide and size the navigation widgets, plus an `AnimatedFloatingActionButton` (`lib/widgets/animated_floating_action_button.dart`) that animates scale and border radius (`lerpDouble(30, 15, ...)`). Update `DisappearingBottomNavigationBar` and `DisappearingNavigationRail` to wrap their widgets in these transitions, and update `_FeedState` in `lib/main.dart` with `SingleTickerProviderStateMixin`, an `AnimationController` driven in `didChangeDependencies()` when `width > 600`, and an `AnimatedBuilder` wrapping the `Scaffold`.
了解生成的代码
lib/animations.dart中的交错间隔
lib/animations.dart 中的每个动画类都会将父级 AnimationController 封装在 CurvedAnimation(或 ReverseAnimation,用于底部栏,随着控制器向 1.0 推进,底部栏会隐藏)中,并具有不同的正向和反向 Interval 窗口:
class BarAnimation extends ReverseAnimation {
BarAnimation({required AnimationController parent})
: super(
CurvedAnimation(
parent: parent,
curve: const Interval(0, 1 / 5),
reverseCurve: const Interval(1 / 5, 4 / 5),
),
);
}
class OffsetAnimation extends CurvedAnimation {
OffsetAnimation({required super.parent})
: super(
curve: const Interval(
2 / 5,
3 / 5,
curve: Curves.easeInOutCubicEmphasized,
),
reverseCurve: Interval(
4 / 5,
1,
curve: Curves.easeInOutCubicEmphasized.flipped,
),
);
}
使用 Curves.easeInOutCubicEmphasized(以及反向时的 .flipped)可应用 Material 3 的标志性富有表现力的加/减速曲线。
BottomBarTransition和NavRailTransition中的滑动和尺寸调整
在 lib/transitions/nav_rail_transition.dart 中,NavRailTransition 结合了两个派生自 widget.animation 的子动画:widthAnimation(由 SizeAnimation 驱动)和 offsetAnimation(由 OffsetAnimation 驱动,遵循文本 Directionality):
child: AnimatedBuilder(
animation: widthAnimation,
builder: (context, child) {
return Align(
alignment: Alignment.topLeft,
widthFactor: widthAnimation.value,
child: FractionalTranslation(
translation: offsetAnimation.value,
child: widget.child,
),
);
},
),
为 Align.widthFactor(以及 BottomBarTransition 中的 heightFactor)添加动画效果可平滑地展开或收起该 widget 在布局中占用的空间,而 FractionalTranslation 会使该 widget 从 ClipRect 剪裁的边缘滑入。
在lib/main.dart驾驶AnimationController
在 _FeedState 中,didChangeDependencies() 会检查当前窗口宽度,并在宽度超过 600 像素时运行 _controller.forward(),在宽度小于 像素时运行 _controller.reverse():
final double width = MediaQuery.of(context).size.width;
final AnimationStatus status = _controller.status;
if (width > 600) {
if (status != AnimationStatus.forward &&
status != AnimationStatus.completed) {
_controller.forward();
}
} else {
if (status != AnimationStatus.reverse &&
status != AnimationStatus.dismissed) {
_controller.reverse();
}
}
if (!controllerInitialized) {
controllerInitialized = true;
_controller.value = width > 600 ? 1 : 0;
}
直接在初始 build (!controllerInitialized) 上设置 _controller.value 可确保应用立即以适当的布局启动,而无需在启动时播放进入过渡效果。
运行并测试应用
在 600 像素宽度阈值范围内来回调整应用窗口大小。底部 NavigationBar、NavigationRail 和撰写 FloatingActionButton 现在可在移动模式和桌面模式之间流畅切换。
8. 添加列表/详情视图
当显示屏足够宽时,即时通讯应用自然适合采用双窗格列表-详情布局。在最后一步中,您将添加一个 ReplyListView 微件来显示所选邮件会话串,并添加一个 ListDetailTransition 微件,以便在窗口变宽时,让“详细信息”窗格以动画形式显示在 EmailListView 旁边,并按比例调整其弹性分配。
提示 Antigravity 添加列表-详情视图
在 Antigravity 中发送以下提示:
Create a `ReplyListView` widget (`lib/widgets/reply_list_view.dart`) using `package:material_ui/material_ui.dart` that renders `data.replies` as threaded `EmailWidget` cards (`isPreview: false`, `isThreaded: true`, and `showHeadline: index == 0`). Then create a `ListDetailTransition` widget (`lib/transitions/list_detail_transition.dart`) that animates a second `Flexible` detail pane into a `Row` alongside `widget.one` using `SizeAnimation`, `OffsetAnimation`, `TweenSequence`, and a width-responsive flex factor (`lerpDouble` across `800`, `1200`, and `1600` px breakpoints). Finally, wrap `EmailListView` and `const ReplyListView()` in `ListDetailTransition(animation: _railAnimation, ...)` inside `lib/main.dart`.
了解生成的代码
ListDetailTransition中的按比例宽度分配
在 lib/transitions/list_detail_transition.dart 中,didChangeDependencies() 使用 Dart 3 关系模式 switch 表达式,计算 nextFlexFactor 相对于 widget.one 的固定 flex: 1000 分配:
final double width = MediaQuery.of(context).size.width;
double nextFlexFactor = switch (width) {
>= 800 && < 1200 => lerpDouble(1000, 2000, (width - 800) / 400)!,
>= 1200 && < 1600 => lerpDouble(2000, 3000, (width - 1200) / 400)!,
>= 1600 => 3000,
_ => 1000,
};
- 当窗口宽度小于
800像素时,nextFlexFactor为1000,从而使收件箱列表 (widget.one) 和回复窗格 (widget.two) 各占可用空间的1/2。 - 在
800到1200像素之间,收件箱列表的比例会平滑插值到1/3,详细信息视图的比例会平滑插值到2/3。 - 在
1600像素及更宽的屏幕上,详细信息窗格会获得3/4(3000与1000)的可用宽度。
当 widthAnimation.value.toInt() == 0(在窄屏上)时,ListDetailTransition 仅返回 widget.one,因此隐藏的详细信息窗格不使用任何布局资源:
@override
Widget build(BuildContext context) {
return widthAnimation.value.toInt() == 0
? widget.one
: Row(
children: [
Flexible(flex: 1000, child: widget.one),
Flexible(
flex: widthAnimation.value.toInt(),
child: FractionalTranslation(
translation: offsetAnimation.value,
child: widget.two,
),
),
],
);
}
运行并测试应用
热重载(或热重启)应用,然后加宽窗口,即可看到导航栏、收件箱列表和会话式详情视图协同工作:

9. 恭喜
恭喜!您已使用 Flutter、material_ui 软件包和 Google Antigravity 构建了一个动画形式的响应式即时通讯应用。
您构建的内容
- Material 3 消息传递界面(
EmailListView、EmailWidget、SearchBar和StarButton),采用package:material_ui/material_ui.dart、ColorScheme表面色调和LayoutBuilder约束条件。 - 自适应导航,可在窄屏上的底部
NavigationBar和宽屏上的侧边NavigationRail之间切换。 - 精心编排的布局转换(
BottomBarTransition、NavRailTransition和AnimatedFloatingActionButton),由交错的CurvedAnimation间隔和 Material 3 强调的加/减速曲线驱动。 - 自适应双窗格列表详情布局(
ListDetailTransition和ReplyListView),可流畅地将“详细信息”窗格动画化,并根据桌面设备断点缩放其弹性比例。
后续步骤
继续向 Antigravity 发出提示,让它扩展您的即时通讯应用:
- 深色模式支持:让 Antigravity 在
NavigationRail前导槽中添加darkTheme: ThemeData.dark()配置和主题模式切换按钮。 - 移动设备详情导航:在窄屏 (
width <= 600) 上,当用户点按电子邮件预览卡片时,让 Antigravity 将ReplyListView推送到Navigator堆栈。 - 搜索过滤:连接
SearchBar的TextField,以便按发件人姓名、主题或邮件正文实时过滤显示的emails列表。
接下来怎么做?
查看以下相关 Codelab:









