--- name: flutter-dev description: > Flutter 跨平台移动开发技能。覆盖 Flutter 入门、Material 3 迁移、布局约束、动画（Hero/Staggered）、自适应响应式布局、平台适配、大型屏幕支持、State 管理方案对比、持久化、网络请求、性能优化。当用户提到 Flutter、Dart、移动开发、跨平台、Material Design、 Flutter Widget、热重载、StatelessWidget、StatefulWidget、setState、Provider、Riverpod、 BLoC、布局约束、BoxConstraints、动画、Animation、Hero、Staggered、响应式、自适应时触发。 trigger: Flutter|flutter|Dart|移动开发|跨平台|Material Design|Flutter Widget|热重载|Hot Reload|StatelessWidget|StatefulWidget|setState|BuildContext|InheritedWidget|Provider|Riverpod|BLoC|布局约束|BoxConstraints|动画|Animation|Hero|Staggered|响应式|自适应|adaptive|MediaQuery|LayoutBuilder|平台适配|SharedPreferences|Hive|Dio|性能优化|重绘|rebuild tags: - flutter - dart - mobile-development - cross-platform - ui-design hermes: platform: hermes version: "1.1" last_updated: "2026-04-24" source: | https://flutter.cn/docs https://flutter.cn/docs/release/breaking-changes/material-3-migration https://flutter.cn/docs/development/ui/layout/constraints https://flutter.cn/docs/development/ui/animations/hero-animations https://flutter.cn/docs/development/ui/animations/staggered-animations --- # Widget 体系与 State 管理 ## Widget 类型 | 类型 | 说明 | 示例 | |------|------|------| | **StatelessWidget** | 不可变，props 决定 UI | `Text`, `Icon`, `Container` | | **StatefulWidget** | 可变，通过 State 管理变化 | `Checkbox`, `TextField`, `Scaffold` | ## State 管理基础 ```dart class MyWidget extends StatefulWidget { @override State createState() => _MyWidgetState(); } class _MyWidgetState extends State { int _counter = 0; void _increment() { setState(() { _counter++; }); // 触发重建 } } ``` ## BuildContext 每个 Widget 的 `build()` 方法接收 `BuildContext`。Context 包含： - 当前 widget 在 widget 树中的位置 - 访问 `Theme.of(context)`、`MediaQuery.of(context)` - 访问祖先 widget 提供的 `InheritedWidget` --- # 布局约束 ## 核心规则 > **"Constraints go down. Sizes go up. Parent sets position."** 父 widget 向下传递约束；子 widget 向上报告尺寸；父 widget 决定子 widget 的位置。 ## BoxConstraints | 类型 | 说明 | 场景 | |------|------|------| | **Tight** | `max == min`，固定尺寸 | `SizedBox(width: 100)` | | **Loose** | `min == 0`，尺寸可变 | `Container()` 默认 | | **Unbounded** | `max == double.infinity` | Scrollable、Flex 延伸方向 | ## 常用布局 Widget | Widget | 用途 | |--------|------| | `Container` | 通用盒子 | | `SizedBox` | 固定尺寸盒子 | | `ConstrainedBox` | 施加额外约束 | | `Padding` | 内边距 | | `Row` / `Column` | 线性布局（Flex） | | `Expanded` | 填充剩余空间 | | `Flexible` | 类似 Expanded，可控制策略 | | `Stack` | 绝对定位布局 | | `Positioned` | Stack 中定位 | | `LayoutBuilder` | 布局阶段获取约束 | ## 常见布局错误 ```dart // ❌ Expanded 在 Stack 中无效 → 用 Positioned 或 Align // ❌ 在 unbounded 约束中 Expanded 无效 → 用 Slivers // ✅ ConstrainedBox 在 Loose 约束内 ConstrainedBox( constraints: BoxConstraints(minWidth: 100, maxWidth: 200), child: Text('Hello'), ) ``` 详细参考：[layout-constraints.md](references/layout-constraints.md) --- # Material 3 迁移 ## 核心开关 ```dart MaterialApp( theme: ThemeData(useMaterial3: true), ); ``` ## 关键变化 | M2 | M3 | |----|-----| | `background` | `surface` | | `primarySwatch` | `ColorScheme.fromSeed()` | | `ButtonTheme` | `FilledButtonTheme` | | `MaterialState` | `WidgetState` | | `FlatButton` | `FilledButton` | ## 种子色 ```dart ColorScheme.fromSeed(seedColor: Colors.blue) ``` 详细参考：[material-3.md](references/material-3.md) --- # 动画系统 ## Hero 动画 ```dart // 页面 A 和 B Hero( tag: 'photo', child: Image.asset('photo.jpg'), ) ``` ## Staggered 动画 ```dart // 一个控制器驱动多个 Interval 动画 Animation get _opacity => Tween(begin: 0.0, end: 1.0).animate( CurvedAnimation(parent: _controller, curve: Interval(0.0, 0.5)), ); Animation get _scale => Tween(begin: 0.0, end: 1.0).animate( CurvedAnimation(parent: _controller, curve: Interval(0.5, 1.0)), ); ``` 详细参考：[hero-animations.md](references/hero-animations.md) | [staggered-animations.md](references/staggered-animations.md) --- # State 管理方案对比 ## Provider（入门级） ```dart // ChangeNotifier class CounterModel extends ChangeNotifier { int _count = 0; int get count => _count; void increment() { _count++; notifyListeners(); } } // 注册 runApp(ChangeNotifierProvider( create: (_) => CounterModel(), child: MyApp(), )); // 重建 UI Consumer( builder: (context, model, child) => Text('${model.count}'), ); // 读取（不重建） final count = context.read().count; ``` ## Riverpod（生产推荐） ```dart // 纯 Dart，无 context 依赖 final counterProvider = StateNotifierProvider((ref) { return CounterNotifier(); }); class CounterNotifier extends StateNotifier { CounterNotifier() : super(0); void increment() => state++; } // 使用 Widget build(BuildContext context, WidgetRef ref) { final count = ref.watch(counterProvider); return Text('$count'); } // ref.watch vs ref.read // watch: 重建 UI（监听变化） // read: 不重建，仅读取当前值（事件处理中常用） // 强制刷新 Provider ref.invalidate(counterProvider); // 重置状态，重新执行 Provider 回调 // 或者基于现有状态刷新 ref.invalidate(myProvider); // 下次访问时重新创建 // Family Provider（带参数） final userProvider = Provider.family((ref, id) { return User(id: id, name: 'User $id'); }); // 使用 final user = ref.watch(userProvider('abc')); ``` ### Provider 作用域 ```dart // ✅ 顶层 Provider：全局单例 final prefsProvider = Provider((ref) { return SharedPreferences.getInstance() as SharedPreferences; }); // ✅ 作用域 Provider：仅在子树内有效 ProviderScope( overrides: [counterProvider.overrideWith(() => MockCounter())], child: MyApp(), ); // ✅ Child Provider：可读取父 Provider final userProvider = Provider((ref) { final prefs = ref.watch(prefsProvider); // 依赖父 Provider return UserRepo(prefs: prefs); }); ``` ## BLoC（大型项目） ```dart class CounterBloc extends Bloc { CounterBloc() : super(0) { on((event, emit) => emit(state + 1)); } } BlocBuilder( builder: (context, count) => Text('$count'), ) ``` ## 方案选型 | 方案 | 复杂度 | 适用场景 | |------|--------|---------| | `setState` | 低 | 简单 widget | | Provider | 中 | 中小型应用 | | Riverpod | 中高 | **生产推荐** | | BLoC | 高 | 团队协作/大型项目 | --- # 持久化存储 ## SharedPreferences（轻量配置） ```dart final prefs = await SharedPreferences.getInstance(); await prefs.setString('username', 'yhong'); await prefs.setInt('counter', 42); final name = prefs.getString('username') ?? ''; await prefs.remove('counter'); ``` ## SQLite（结构化数据） ```dart final db = await openDatabase('myapp.db', version: 1, onCreate: (db, version) async { await db.execute( 'CREATE TABLE tasks(id INTEGER PRIMARY KEY, title TEXT)'); }); await db.insert('tasks', {'title': 'Finish report'}); final maps = await db.query('tasks', where: 'id = ?', whereArgs: [1]); // 批量事务 await db.transaction((txn) async { for (final task in tasks) await txn.insert('tasks', task); }); ``` ## Hive（高性能 KV） ```dart Hive.registerAdapter(TaskAdapter()); final box = await Hive.openBox('tasks'); box.put('task1', Task(title: 'Hello')); final task = box.get('task1'); ``` --- # 网络请求 ## Dio（推荐） ```dart final dio = Dio(BaseOptions( baseUrl: 'https://api.example.com', connectTimeout: Duration(seconds: 10), headers: {'Content-Type': 'application/json'}, )); // 全局拦截器：Token 自动附加 dio.interceptors.add(InterceptorsWrapper( onRequest: (options, handler) { final token = getToken(); // 从安全存储读取 if (token != null) { options.headers['Authorization'] = 'Bearer $token'; } handler.next(options); }, onError: (error, handler) { // Token 过期自动刷新重试 if (error.response?.statusCode == 401) { refreshToken().then((newToken) { // 重试原请求 final opts = error.requestOptions; opts.headers['Authorization'] = 'Bearer $newToken'; dio.fetch(opts).then( (r) => handler.resolve(r), (e) => handler.reject(e), ); }).catchError((e) => handler.reject(error)); } else { handler.next(error); } }, )); // GET / POST final resp = await dio.get('/users', queryParameters: {'page': 1}); final resp = await dio.post('/users', data: {'name': 'yhong'}); ``` ### 统一响应体处理 ```dart // 常见后端响应格式：{ code, data, message } class ApiResp { final int code; final T? data; final String? message; bool get ok => code == 0; } // Dio 响应拦截器统一解析 dio.interceptors.add(InterceptorsWrapper( onResponse: (resp, handler) { final body = resp.data; if (body is Map && body.containsKey('code')) { if (body['code'] != 0) { // 业务错误，转为异常 handler.reject( DioException( requestOptions: resp.requestOptions, error: body['message'] ?? 'Unknown error', type: DioExceptionType.badResponse, ), ); return; } // 替换为 data 部分 resp.data = body['data']; } handler.next(resp); }, )); // 使用时直接取 data final List users = await dio.get('/users').then((r) => r.data); ``` ### 错误处理 ```dart try { final resp = await dio.get('/users'); } on DioException catch (e) { switch (e.type) { case DioExceptionType.connectionTimeout: // 网络超时 case DioExceptionType.badResponse: final statusCode = e.response?.statusCode; if (statusCode == 401) { /* 未授权 */ } if (statusCode == 403) { /* 禁止 */ } if (statusCode == 404) { /* 资源不存在 */ } if (statusCode != null && statusCode >= 500) { /* 服务器错误 */ } case DioExceptionType.cancel: // 请求被取消 default: // 网络不可达等 } } ``` ## JSON 解析 ```dart @JsonSerializable() class User { final String name; final int age; factory User.fromJson(Map json) => _$UserFromJson(json); Map toJson() => _$UserToJson(this); } ``` --- # 性能优化 ## 重建控制 ```dart // ✅ Selector 精确重建（替代 Consumer） Selector( selector: (_, m) => m.title, builder: (_, title, __) => Text(title), ); // ✅ const 构造 const Text('Hello'); const Padding(padding: EdgeInsets.all(16)); // ❌ build 中创建新对象 Widget build(BuildContext context) { return SomeWidget(items: List.generate(100, (i) => Item(i))); // 每次重建 } // ✅ initState 中初始化 final items = List.generate(100, (i) => Item(i)); ``` ## 长列表优化 ```dart // ✅ ListView.builder 懒加载 ListView.builder( itemCount: items.length, itemBuilder: (context, index) => ListTile(title: Text(items[index])), ); // ✅ cacheExtent ListView.builder(cacheExtent: 200, itemBuilder: ...); // ✅ RepaintBoundary 隔离重绘 RepaintBoundary(child: MyComplexWidget()); ``` --- # 响应式布局实战 ## 自适应 Scaffold ```dart class AdaptiveScaffold extends StatelessWidget { @override Widget build(BuildContext context) { final width = MediaQuery.of(context).size.width; if (width < 600) { return Scaffold( body: body, bottomNavigationBar: NavigationBar( selectedIndex: currentIndex, onDestinationSelected: onIndexChanged, destinations: _destinations, ), ); } return Scaffold( body: Row( children: [ NavigationRail( selectedIndex: currentIndex, onDestinationSelected: onIndexChanged, labelType: width > 840 ? NavigationRailLabelType.all : NavigationRailLabelType.selected, destinations: _destinations .map((d) => NavigationRailDestination( icon: d.icon, label: d.label, )) .toList(), ), const VerticalDivider(thickness: 1, width: 1), Expanded(child: body), ], ), ); } } ``` ## 响应式列数 ```dart LayoutBuilder( builder: (context, constraints) { final cols = constraints.maxWidth > 900 ? 3 : constraints.maxWidth > 600 ? 2 : 1; return GridView.count( crossAxisCount: cols, childAspectRatio: 1.5, children: items.map((item) => Card(child: item)).toList(), ); }, ); ``` 详细参考：[adaptive-responsive.md](references/adaptive-responsive.md) | [large-screens.md](references/large-screens.md) --- # 平台适配 ## 平台检测 ```dart final idiom = MediaQuery.of(context).size.shortestSide >= 600 ? 'tablet' : 'phone'; final platform = Theme.of(context).platform; ``` ## 键盘快捷键 ```dart Shortcuts( shortcuts: { LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyS): SaveIntent(), }, child: Actions( actions: { SaveIntent: CallbackAction(onInvoke: (_) => _save()) }, child: focusNode, ), ) ``` ## 鼠标 Hover ```dart MouseRegion( onEnter: (_) => setState(() => _isHovered = true), onExit: (_) => setState(() => _isHovered = false), child: MyWidget(), ) ``` 详细参考：[platform-idioms.md](references/platform-idioms.md) --- # 避坑指南 ### State 管理 | 错误 | 正确 | |------|------| | ❌ 在 `build()` 中调用 `setState()` | ✅ 在回调中调用 | | ❌ `initState()` 中直接使用 `context` | ✅ `didChangeDependencies()` | | ❌ 大型对象放 State | ✅ `const` 构造函数 | ### 布局 | 错误 | 正确 | |------|------| | ❌ `Expanded` 在 `Stack` 中 | ✅ `Positioned`/`Align` | | ❌ 硬编码尺寸 | ✅ `MediaQuery`/`LayoutBuilder` | ### M3 迁移 | 错误 | 正确 | |------|------| | ❌ `ButtonTheme` | ✅ `FilledButtonTheme` | | ❌ `background`/`onBackground` | ✅ `surface`/`onSurface` | | ❌ `MaterialState` | ✅ `WidgetState` | --- # 快速参考 ## 热重载 vs 热重启 | 操作 | 效果 | |------|------| | **R** (Hot Reload) | 保持 State，仅重建 Widget 树 | | **Shift+R** (Hot Restart) | State 丢失，重新执行 `main()` | ## 常用 EdgeInsets ```dart EdgeInsets.all(16.0) EdgeInsets.symmetric(v: 8) EdgeInsets.only(left: 16) EdgeInsets.fromLTRB(4,8,4,8) ``` ## AnimationController 生命周期 ```dart _controller = AnimationController( duration: Duration(milliseconds: 300), vsync: this, ); @override void dispose() { _controller.dispose(); super.dispose(); } ``` ## 组件速查 | 按钮 | 导航 | 容器 | |------|------|------| | `FilledButton` | `AppBar` | `Card` | | `FilledButton.tonal` | `NavigationBar` | `Dialog` | | `OutlinedButton` | `NavigationRail` | `SnackBar` | | `TextButton` | `NavigationDrawer` | `BottomSheet` | 详细参考：[buttons-input.md](references/buttons-input.md) | [navigation-components.md](references/navigation-components.md) | [display-components.md](references/display-components.md) --- ## 来源 > 文档版本：Flutter 3.x + Material 3 > URL: https://flutter.cn/docs > 抓取时间：2026-04-24 ## 参考文档 | 文件 | 行数 | 覆盖内容 | |------|------|---------| | material-3.md | 767 | Material 3 迁移完整指南 | | layout-constraints.md | 368 | 布局约束与约束传递机制 | | overview-getting-started.md | 376 | Flutter 入门与平台能力 | | buttons-input.md | 424 | 按钮与输入组件 | | adaptive-responsive.md | 298 | 自适应响应式布局 | | platform-idioms.md | 358 | 平台适配与设备类型 | | large-screens.md | 264 | 大屏幕与折叠屏支持 | | navigation-components.md | 350 | 导航组件 | | display-components.md | 300 | 展示组件 | | hero-animations.md | 239 | Hero 动画 | | staggered-animations.md | 354 | 交错动画 | | testing.md | 121 | 测试指南（单元/Widget/集成/Mock） | | dependency-injection.md | 81 | 依赖注入（get_it/Riverpod/injectable） | --- | testing.md | 参考文档：测试指南 | ## 单元测试（flutter_test） > 详见 [testing.md](references/testing.md)（flutter_test / widget / integration / Mock） ```dart class CounterModel extends ChangeNotifier { int _count = 0; int get count => _count; void increment() { _count++; notifyListeners(); } } test('CounterModel increments correctly', () { final model = CounterModel(); expect(model.count, 0); model.increment(); expect(model.count, 1); }); ``` ## Widget 测试 ```dart testWidgets('CounterWidget displays count and increments', (tester) async { await tester.pumpWidget(MaterialApp(home: CounterWidget())); expect(find.text('0'), findsOneWidget); await tester.tap(find.byIcon(Icons.add)); await tester.pump(); expect(find.text('1'), findsOneWidget); }); ``` ## Riverpod Provider 测试 ```dart testProvider('counterProvider increments', (override) async { await runProviderScope((ref) async { final counter = ref.watch(counterProvider); expect(counter, 0); ref.read(counterProvider.notifier).increment(); expect(ref.watch(counterProvider), 1); }, overrides: []); }); ``` ## 集成测试 ```dart setUpAll(() async { await FlutterDriver.connect(); }); test('app loads and shows home', () async { final driver = await FlutterDriver.connect(); await driver.waitFor(find.byType('MyHomePage')); expect(find.text('Home'), findsOneWidget); }); ``` ## Mock + mockito ```dart @GenerateMocks([UserRepository]) void main() { late MockUserRepository mockRepo; setUp(() { mockRepo = MockUserRepository(); }); test('loads user data', () async { when(mockRepo.getUser('123')) .thenAnswer((_) async => User(id: '123', name: 'Alice')); final user = await mockRepo.getUser('123'); expect(user.name, 'Alice'); verify(mockRepo.getUser('123')).called(1); }); } ``` --- ## 依赖注入 > 详见 [dependency-injection.md](references/dependency-injection.md)（get_it / injectable / DI 陷阱） ```dart import 'package:get_it/get_it.dart'; final getIt = GetIt.instance; void setupDependencies() { getIt.registerLazySingleton(() => Dio()); getIt.registerFactory( () => UserRepository(dio: getIt()), ); getIt.registerSingleton(prefs); } final repo = getIt(); ``` ## Riverpod + get_it ```dart final dioProvider = Provider((ref) => getIt()); final userRepoProvider = Provider( (ref) => UserRepository(dio: ref.watch(dioProvider)), ); ``` ## injectable ```dart @injectable class AuthRepository { final Dio dio; AuthRepository({required this.dio}); } // configureDependencies(); // 自动生成 ``` ## DI 陷阱 | 错误 | 正确 | |------|------| | ❌ 在 `build()` 中 `GetIt.instance()` | ✅ 顶层 `setupDependencies()` 中注册 | | ❌ 单例中引用非单例 | ✅ 确保生命周期一致 | | ❌ 直接 `Dio()` 硬编码 | ✅ 通过 `getIt()` 注入 | --- ## 输出格式规范 ### 回复结构 1. **直接回答** — 一段简洁的话给出核心答案 2. **代码示例** — 提供完整的 Dart/Flutter 代码 3. **实现要点** — 关键步骤和注意事项 4. **避坑提醒** — 常见错误 + 正确做法 ### 禁用格式 - ❌ 不要显式分层（避免"第一层/第二层/框架分析"等字眼） - ❌ 不要长篇解释概念，要直接给出实现 - ❌ 不要只给代码片段，要给完整可运行的示例 - ✅ 输出应是一段干净的话 + 完整代码 FILE:README.md # Flutter 开发技能 Flutter 跨平台移动开发技能，覆盖 Widget 体系、布局约束、Material 3 迁移、动画、State 管理、网络请求、性能优化。当用户提到 Flutter、Dart、移动开发、跨平台时触发。 ## 概述本 skill 覆盖 Flutter 完整开发知识体系： - **Widget 体系** — StatelessWidget/StatefulWidget/State/BuildContext - **布局约束** — BoxConstraints 传递机制、Flex/Stack/Grid - **Material 3** — 种子色、组件重命名、ThemeData 迁移 - **动画** — Hero 页面转场、Staggered 交错动画 - **State 管理** — Provider/Riverpod/BLoC 方案对比与选型 - **网络层** — Dio 封装、Token 自动刷新、统一响应体 - **持久化** — SharedPreferences/SQLite/Hive - **性能优化** — 重建控制、长列表优化 - **自适应布局** — MediaQuery/LayoutBuilder/响应式列数 ## 核心章节 ### 基础 | 章节 | 内容 | |------|------| | [Widget 体系与 State 管理](SKILL.md#Widget-体系与-State-管理) | Widget 类型、State 生命周期、BuildContext | | [布局约束](SKILL.md#布局约束) | BoxConstraints 传递、Flex/Stack/Grid 布局 | | [Material 3 迁移](SKILL.md#Material-3-迁移) | useMaterial3 开关、组件重命名、种子色配置 | ### 架构与网络 | 章节 | 内容 | |------|------| | [State 管理方案对比](SKILL.md#State-管理方案对比) | Provider/Riverpod/BLoC 原理与选型 | | [网络请求](SKILL.md#网络请求) | Dio 封装、Token 刷新、响应体拦截、错误处理 | | [持久化存储](SKILL.md#持久化存储) | SharedPreferences/SQLite/Hive | | [动画系统](SKILL.md#动画系统) | Hero 页面转场、Staggered 交错动画 | ### 平台与进阶 | 章节 | 内容 | |------|------| | [响应式布局实战](SKILL.md#响应式布局实战) | MediaQuery/LayoutBuilder、响应式列数 | | [平台适配](SKILL.md#平台适配) | 平台检测、键盘快捷键、鼠标 Hover | | [性能优化](SKILL.md#性能优化) | 重建控制、长列表优化 | | [避坑指南](SKILL.md#避坑指南) | 常见错误与正确做法 | ### 参考文档 | 文件 | 行数 | 内容 | |------|------|------| | material-3.md | 767 | Material 3 迁移完整指南 | | layout-constraints.md | 368 | 布局约束与约束传递机制 | | overview-getting-started.md | 376 | Flutter 入门与平台能力 | | buttons-input.md | 424 | 按钮与输入组件 | | adaptive-responsive.md | 298 | 自适应响应式布局 | | platform-idioms.md | 358 | 平台适配与设备类型 | | large-screens.md | 264 | 大屏幕与折叠屏支持 | | navigation-components.md | 350 | 导航组件 | | display-components.md | 300 | 展示组件 | | hero-animations.md | 239 | Hero 动画 | | staggered-animations.md | 354 | 交错动画 | | testing.md | 121 | 测试指南（单元/Widget/集成/Mock） | | dependency-injection.md | 81 | 依赖注入（get_it/Riverpod/injectable） | ## 快速参考 ### Widget 类型对照 | 类型 | 说明 | 示例 | |------|------|------| | **StatelessWidget** | 不可变，props 决定 UI | `Text`, `Icon`, `Container` | | **StatefulWidget** | 可变，通过 State 管理变化 | `Checkbox`, `TextField`, `Scaffold` | ### State 管理方案对比 | 方案 | 适用场景 | 复杂度 | |------|---------|--------| | **setState** | 局部 UI 状态 | ★☆☆☆☆ | | **Provider** | 中小型应用 | ★★☆☆☆ | | **Riverpod** | 生产级应用（推荐） | ★★★☆☆ | | **BLoC** | 大型复杂项目 | ★★★★☆ | ### 布局 Widget | 组件 | 用途 | 关键属性 | |------|------|---------| | Column | 垂直布局 | `.spacing()`, `.crossAxisAlignment()` | | Row | 水平布局 | `.spacing()`, `.mainAxisAlignment()` | | Expanded | 弹性填充 | 在 Row/Column/Flex 内使用 | | Flexible | 弹性但不强制 | `.flex()`, `.fit()` | | Stack | 层叠布局 | `.alignment()`, `.children` | | GridView | 网格布局 | `.gridDelegate()`, `.children` | | ListView | 列表布局 | `.itemBuilder()`, `.separatorBuilder()` | ### 常用布局代码 ```dart // Column 垂直布局 Column( children: [ Text('Header'), Expanded(child: Content()), BottomBar(), ], ) // Row 水平布局 Row( children: [ Icon(Icons.menu), Expanded(child: Title()), Actions(), ], ) // Stack 层叠 Stack( children: [ Background(), Content(), FloatingButton(), ], ) ``` ### 种子色配置 ```dart MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.blue, brightness: Brightness.light, ), useMaterial3: true, ), ) ``` ### Riverpod 最小示例 ```dart // 定义 final counterProvider = StateProvider((ref) => 0); // 使用 Consumer(builder: (context, ref, child) { final count = ref.watch(counterProvider); return Text('$count'); }); // 修改 ref.read(counterProvider.notifier).state++; ``` ### Dio 网络请求 ```dart // Token 自动刷新拦截器 dio.interceptors.add(InterceptorsWrapper( onError: (e, handler) async { if (e.response?.statusCode == 401) { await dio.refreshToken(); final retry = await dio.fetch(e.requestOptions); return handler.resolve(retry); } handler.next(e); }, )); // 统一响应体 class ApiResp { final int code; final T? data; final String? message; } ``` ## 避坑指南 ### Widget 与 State | 错误做法 | 正确做法 | |---------|---------| | ❌ 在 build() 中直接修改 State | ✅ 通过 setState() 触发重建 | | ❌ setState() 内执行异步操作不带回调 | ✅ 异步后用 mounted 判断再 setState | | ❌ StatefulWidget 在 dispose 后继续操作 | ✅ 使用 if (mounted) 保护 | | ❌ 把 Widget 当可变容器 | ✅ Widget 不可变，状态放 State | ### 布局约束 | 错误做法 | 正确做法 | |---------|---------| | ❌ SizedBox 嵌套过多 | ✅ 使用 Column/Row + spacer 替代 | | ❌ Expanded/ Flexible 放在 Stack 内 | ✅ Expanded 仅在 Flex（Column/Row/Flex）内有效 | | ❌ 忽视 BoxConstraints 传递 | ✅ 父约束决定子组件尺寸，子不能超出父 | | ❌ ListView 内嵌套相同方向 ScrollView | ✅ 冲突导致无限扩展，用 CustomScrollView 统一 | ### Riverpod | 错误做法 | 正确做法 | |---------|---------| | ❌ 在 build() 内 watch Provider | ✅ 避免循环依赖，用 ref.watch 在组件顶层 | | ❌ 混用 ref.watch 和 ref.read | ✅ watch 监听变化触发重建，read 仅获取当前值 | | ❌ StateNotifier 不检查 dispose | ✅ 异步回调中用 if (mounted) 保护 | | ❌ Provider 顶层注册依赖未初始化 | ✅ 用 Provider.family 处理需要参数的 Provider | ### 网络层 | 错误做法 | 正确做法 | |---------|---------| | ❌ Dio 实例全局单例不配拦截器 | ✅ 按业务拆分多个 Dio 实例或用配置类 | | ❌ Token 刷新后不重试原请求 | ✅ 使用 QueueInterceptor 队列管理重试 | | ❌ 不处理网络异常统一抛 Exception | ✅ 区分 DioExceptionType 做分类处理 | | ❌ 响应数据不判空直接用 | ✅ 用 `?.` 或判空检查防止空指针 | ## 来源 > Flutter 官方文档（2026-04-24 访问） > - 官方文档：https://flutter.cn/docs > - Widget 目录：https://docs.flutter.dev/ui/widgets > - Material 3 迁移：https://flutter.cn/docs/release/breaking-changes/material-3-migration > - 布局约束：https://flutter.cn/docs/development/ui/layout/constraints > - Hero 动画：https://flutter.cn/docs/development/ui/animations/hero-animations > - Staggered 动画：https://flutter.cn/docs/development/ui/animations/staggered-animations > > 版本：Flutter 3.x + Material 3 FILE:references/adaptive-responsive.md --- name: flutter-adaptive-responsive description: Flutter 响应式/自适应设计完整参考。 source: https://flutter.cn/docs --- # Flutter 响应式/自适应设计本文档涵盖 Flutter 平台自动适配机制、尺寸测量工具（`MediaQuery`、`LayoutBuilder`）、断点策略以及窗口尺寸类的完整参考。 ## 平台自动适配（Platform Adaptations） Flutter 为 Android 和 iOS 自动适配以下系统级体验。 ### 导航转场动画 **Android**：默认 [`Navigator.push()`][] 使用 [`ZoomPageTransitionsBuilder`][] 动画——路由跳转时界面缩放到下一页，返回时缩回上一页。 **iOS**： - 默认 Push 转场动画：从后向前滑动（根据语言 RTL 设置方向），背景页同步视差滑动 - `PageRoute.fullscreenDialog == true` 时为 Present/Modal 样式，自下而上全屏模态 **返回导航**： - Android：系统返回按钮触发 `Navigator.pop()` - iOS：屏幕边缘右滑触发返回 [`Navigator.push()`]: {{site.api}}/flutter/widgets/Navigator/push.html [`ZoomPageTransitionsBuilder`]: {{site.api}}/flutter/material/ZoomPageTransitionsBuilder-class.html ### 滚动行为 | 特性 | Android | iOS | |---|---|---| | 物理仿真 | 静态摩擦更多，加速快，停止急促 | 动态摩擦更多，渐近达高速，停止柔和 | | 越界效果 | GlowingOverscrollIndicator 灰色光晕 | BouncingScrollPhysics 弹簧回弹 | | 动量 | 无叠加 | 同方向连续滑动速度叠加 | | 返回顶部 | 无 | 点击状态栏滚动到顶 | ```dart // Android 越界效果 ScrollConfiguration( behavior: ScrollConfiguration.of(context).copyWith( overscrollIndicator: GlowingOverscrollIndicator, ), child: ListView(children: ...), ); // iOS 越界效果 ScrollConfiguration( behavior: ScrollConfiguration.of(context).copyWith( overscrollIndicator: BouncingScrollPhysics, ), child: ListView(children: ...), ); ``` ### 排版 - Material 主题：Android → Roboto，iOS → San Francisco - Cupertino 主题：始终使用 San Francisco（Android 上使用替代字体） ```dart // 平台感知字体 TextTheme cupertinoTextTheme = TextTheme( headlineMedium: CupertinoThemeData() .textTheme .navLargeTitleTextStyle .copyWith(letterSpacing: -1.5), titleLarge: CupertinoThemeData().textTheme.navTitleTextStyle, ); ThemeData( textTheme: Platform.isIOS ? cupertinoTextTheme : null, ) ``` ### 图标 Material 包根据平台自动切换图标样式（如更多按钮：iOS 横排三点 / Android 竖排三点；返回按钮：iOS 纯 V 型 / Android V 型加短横线）。也可通过 [`Icons.adaptive`][] 获取平台自适应图标。 [`Icons.adaptive`]: {{site.api}}/flutter/material/PlatformAdaptiveIcons-class.html ### 触摸反馈 | 场景 | Android | iOS | |---|---|---| | 文本长按选中单词 | 震动 'buzz' | 无 | | 选择器滚动 | 无 | 'light impact' 轻敲 | ### 文本编辑 | 手势 | Android (Material) | iOS (Material/Cupertino) | |---|---|---| | 单击 | 光标移到点击处，有可拖动把手 | 光标移到最近单词边缘，无把手 | | 长按 | 选中单词，释放显示工具栏 | 放置光标，释放显示工具栏 | | 长按拖动 | 扩展选中词范围 | 移动光标 | | 双击 | 选中单词 | 选中单词 | | 空格键滑动 | 移动光标 | — | | 3D Touch 拖动 | — | 浮动光标任意方向移动 | ### UI 组件 .adaptive() 构造器以下 Material widget 提供 `.adaptive()` 构造器，在 iOS 上自动替换为对应 Cupertino 组件： ```dart // 开关 Switch.adaptive(value: value, onChanged: ...) // 滑块 Slider.adaptive(value: value, onChanged: ...) // 进度指示器 CircularProgressIndicator.adaptive() // 刷新指示器 RefreshIndicator.adaptive() // 复选框 Checkbox.adaptive(value: value, onChanged: ...) // 单选框 Radio.adaptive(value: value, groupValue: ..., onChanged: ...) // 警告对话框 AlertDialog.adaptive(title: ..., content: ...); ``` ### 顶部应用栏适配 ```dart AppBar( surfaceTintColor: Platform.isIOS ? Colors.transparent : null, shadowColor: Platform.isIOS ? CupertinoColors.darkBackgroundGray : null, scrolledUnderElevation: Platform.isIOS ? .1 : null, toolbarHeight: Platform.isIOS ? 44 : null, ), ``` ### 底部导航栏 ```dart Scaffold( body: _currentWidget, bottomNavigationBar: Platform.isIOS ? CupertinoTabBar( currentIndex: _currentIndex, onTap: (index) => setState(() => _currentIndex = index), items: _navigationItems.entries .map( (e) => BottomNavigationBarItem( icon: e.value, label: e.key, )) .toList(), ) : NavigationBar( selectedIndex: _currentIndex, onDestinationSelected: (index) => setState(() => _currentIndex = index), destinations: _navigationItems.entries .map((e) => NavigationDestination( icon: e.value, label: e.key, )) .toList(), ), ); ``` --- ## 测量窗口尺寸 ### MediaQuery.sizeOf vs MediaQuery.of `MediaQuery.sizeOf` 仅读取 size 属性，性能优于包含全部数据的 `MediaQuery.of`。 ```dart // 推荐：用 sizeOf 获取窗口尺寸 Size size = MediaQuery.sizeOf(context); // 而非： Size size = MediaQuery.of(context).size; ``` `MediaQuery.sizeOf(context)` 在尺寸变化时触发 `BuildContext` 重建。 ### LayoutBuilder `LayoutBuilder` 返回父级 `BoxConstraints`（含 min/max 范围），而非固定 `Size`。适用于仅关心特定 widget 可用空间而非整个 App 窗口的场景。 ```dart LayoutBuilder( builder: (context, constraints) { if (constraints.maxWidth < 600) { return _buildMobileLayout(); } else { return _buildDesktopLayout(); } }, ) ``` ### SafeArea `SafeArea` 用 `MediaQuery` 数据检测系统 UI（状态栏、异形屏、圆角）并留出安全边距。它会修改传递给子 widget 的 `MediaQuery`，使嵌套的 `SafeArea` 不会重复累加内边距。 ```dart // 推荐：仅包裹需要安全区的内容 Scaffold( appBar: AppBar(...), // AppBar 已处理状态栏区域 body: SafeArea( top: false, // AppBar 已处理顶部，不需要重复 child: content, ), ); // 不推荐：包裹整个 Scaffold（AppBar 会重复处理） Scaffold( body: SafeArea(child: ...), // 错误 ); ``` --- ## 断点与窗口尺寸类 Material 3 推荐的响应式断点（基于**窗口宽度**，而非设备类型）： | 窗口宽度 | 尺寸类 | 典型布局 | |---|---|---| | < 600 dp | Compact | 底部导航栏 | | 600–839 dp | Medium | 导航轨道 (NavigationRail) | | ≥ 840 dp | Expanded | 永久侧边导航 | > **重要**：根据**应用窗口的实际宽度**选择断点，而非设备类型。Flutter 应用可能在 ChromeOS 桌面窗口、平板多窗口模式、画中画等各式环境中运行。 ```dart Widget build(BuildContext context) { final width = MediaQuery.sizeOf(context).width; if (width < 600) { return BottomNavigationBar(...); // Compact } else if (width < 840) { return NavigationRail(...); // Medium } else { return NavigationDrawer(...); // Expanded } } ``` ```dart // 使用 ConstrainedBox 限制最大内容宽度 ConstrainedBox( constraints: const BoxConstraints(maxWidth: 1200), child: content, ); ``` --- ## 自适应三步法 ### Step 1: 抽象（Abstract）将 UI 拆分为可共享的小组件： ```dart // 抽象导航目标 class Destination { final IconData icon; final String label; const Destination({required this.icon, required this.label}); } const destinations = [ Destination(icon: Icons.home, label: 'Home'), Destination(icon: Icons.settings, label: 'Settings'), ]; ``` ### Step 2: 测量（Measure）使用 `MediaQuery.sizeOf` 或 `LayoutBuilder` 获取实际可用空间。 ### Step 3: 分支（Branching）根据测量结果选择不同 UI： ```dart Widget build(BuildContext context) { final screenWidth = MediaQuery.sizeOf(context).width; if (screenWidth >= 840) { return _buildExpandedLayout(); } else if (screenWidth >= 600) { return _buildMediumLayout(); } else { return _buildCompactLayout(); } } ``` 详细示例参见 [Material 3 动画响应式布局 Codelab]({{site.codelabs}}/codelabs/flutter-animated-responsive-layout)。 FILE:references/buttons-input.md --- name: flutter-buttons-input description: Flutter Buttons, Text Fields, Input 组件详解。 source: https://flutter.cn/docs --- # Buttons, Text Fields & Input Components ## Buttons (M2 → M3) ### 新按钮 API 概述 Flutter M3 引入了全新的按钮组件体系，替代了旧的 `FlatButton`、`RaisedButton`、`OutlineButton`： | Old Widget | Old Theme | New Widget | New Theme | |------------|-----------|------------|-----------| | `FlatButton` | `ButtonTheme` | `TextButton` | `TextButtonTheme` | | `RaisedButton` | `ButtonTheme` | `ElevatedButton` | `ElevatedButtonTheme` | | `OutlineButton` | `ButtonTheme` | `OutlinedButton` | `OutlinedButtonTheme` | ### ButtonStyle 核心概念新按钮使用 `ButtonStyle` 配置视觉属性，替代了原来的大量独立参数： ```dart TextButton( style: ButtonStyle( foregroundColor: MaterialStateProperty.all(Colors.blue), overlayColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.hovered)) return Colors.blue.withOpacity(0.04); if (states.contains(MaterialState.focused) || states.contains(MaterialState.pressed)) return Colors.blue.withOpacity(0.12); return null; }, ), ), onPressed: () { }, child: Text('TextButton'), ) ``` ### styleFrom() 便捷方法每个按钮类提供 `styleFrom()` 方法简化样式创建： ```dart // 自定义前景色 TextButton( style: TextButton.styleFrom( foregroundColor: Colors.blue, disabledForegroundColor: Colors.red, ), onPressed: () { }, child: Text('TextButton'), ) // 自定义背景色和前景色 ElevatedButton( style: ElevatedButton.styleFrom( backgroundColor: Colors.red, foregroundColor: Colors.white, ), onPressed: () { }, child: Text('ElevatedButton'), ) // 自定义形状 OutlinedButton( style: OutlinedButton.styleFrom( shape: StadiumBorder(), side: BorderSide(color: Colors.red, width: 2), ), onPressed: () { }, child: Text('OutlinedButton'), ) ``` ### 恢复 M2 按钮外观 ```dart // 恢复 FlatButton 外观 final ButtonStyle flatButtonStyle = TextButton.styleFrom( foregroundColor: Colors.black87, minimumSize: Size(88, 36), padding: EdgeInsets.symmetric(horizontal: 16), shape: const RoundedRectangleBorder( borderRadius: BorderRadius.all(Radius.circular(2)), ), ); // 恢复 RaisedButton 外观 final ButtonStyle raisedButtonStyle = ElevatedButton.styleFrom( foregroundColor: Colors.black87, backgroundColor: Colors.grey[300], minimumSize: Size(88, 36), padding: EdgeInsets.symmetric(horizontal: 16), shape: const RoundedRectangleBorder( borderRadius: BorderRadius.all(Radius.circular(2)), ), ); // 全局应用主题 MaterialApp( theme: ThemeData.from(colorScheme: ColorScheme.light()).copyWith( textButtonTheme: TextButtonThemeData(style: flatButtonStyle), elevatedButtonTheme: ElevatedButtonThemeData(style: raisedButtonStyle), outlinedButtonTheme: OutlinedButtonThemeData(style: outlineButtonStyle), ), ) ``` ### 状态相关颜色 ```dart // 自定义 overlay 颜色 TextButton( style: ButtonStyle( overlayColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.focused)) return Colors.red; if (states.contains(MaterialState.hovered)) return Colors.green; if (states.contains(MaterialState.pressed)) return Colors.blue; return null; }, ), ), onPressed: () { }, child: Text('TextButton'), ) // 自定义禁用颜色 ElevatedButton( style: ButtonStyle( backgroundColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.disabled)) return Colors.red; return null; }, ), foregroundColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.disabled)) return Colors.blue; return null; }, ), ), onPressed: null, child: Text('ElevatedButton'), ) ``` ### 自定义 Elevation ```dart // 使用 styleFrom ElevatedButton( style: ElevatedButton.styleFrom(elevation: 2), onPressed: () { }, child: Text('ElevatedButton with custom elevation'), ) // 单独覆盖某个状态 ElevatedButton( style: ButtonStyle( elevation: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.pressed)) return 16; return null; }, ), ), onPressed: () { }, child: Text('ElevatedButton with custom elevation'), ) ``` --- ## Text Fields & Input ### TextSelectionTheme 迁移 M3 将文本选择相关属性迁移到 `TextSelectionTheme`： | Before | After | |--------|-------| | `ThemeData.cursorColor` | `TextSelectionThemeData.cursorColor` | | `ThemeData.textSelectionColor` | `TextSelectionThemeData.selectionColor` | | `ThemeData.textSelectionHandleColor` | `TextSelectionThemeData.selectionHandleColor` | ```dart // 迁移前 ThemeData( cursorColor: Colors.red, textSelectionColor: Colors.green, textSelectionHandleColor: Colors.blue, ) // 迁移后 ThemeData( textSelectionTheme: TextSelectionThemeData( cursorColor: Colors.red, selectionColor: Colors.green, selectionHandleColor: Colors.blue, ), ) // 恢复旧默认值 (Light) ThemeData( textSelectionTheme: TextSelectionThemeData( cursorColor: const Color.fromRGBO(66, 133, 244, 1.0), selectionColor: const Color(0xff90caf9), selectionHandleColor: const Color(0xff64b5f6), ), ) // 恢复旧默认值 (Dark) ThemeData( textSelectionTheme: TextSelectionThemeData( cursorColor: const Color.fromRGBO(66, 133, 244, 1.0), selectionColor: const Color(0xff64ffda), selectionHandleColor: const Color(0xff1de9b6), ), ) ``` ### 焦点与键盘导航 ```dart // 使用 FocusableActionDetector class _BasicActionDetectorState extends State { bool _hasFocus = false; @override Widget build(BuildContext context) { return FocusableActionDetector( onFocusChange: (value) => setState(() => _hasFocus = value), actions: >{ ActivateIntent: CallbackAction( onInvoke: (intent) { print('Enter or Space was pressed!'); return null; }, ), }, child: Stack( clipBehavior: Clip.none, children: [ const FlutterLogo(size: 100), if (_hasFocus) Positioned( left: -4, top: -4, bottom: -4, right: -4, child: _roundedBorder(), ), ], ), ); } } // 控制遍历顺序 Column( children: [ FocusTraversalGroup(child: MyFormWithMultipleColumnsAndRows()), SubmitButton(), ], ) // 键盘快捷键 Widget build(BuildContext context) { return Shortcuts( shortcuts: const { SingleActivator(LogicalKeyboardKey.keyN, control: true): CreateNewItemIntent(), }, child: Actions( actions: >{ CreateNewItemIntent: CallbackAction( onInvoke: (intent) => _createNewItem(), ), }, child: Focus(autofocus: true, child: Container()), ), ); } // 全局键盘监听 @override void initState() { super.initState(); HardwareKeyboard.instance.addHandler(_handleKey); } @override void dispose() { HardwareKeyboard.instance.removeHandler(_handleKey); super.dispose(); } bool _handleKey(KeyEvent event) { bool isShiftDown = isKeyDown({ LogicalKeyboardKey.shiftLeft, LogicalKeyboardKey.shiftRight, }); if (isShiftDown && event.logicalKey == LogicalKeyboardKey.keyN) { _createNewItem(); return true; } return false; } ``` ### Visual Density ```dart double densityAmt = touchMode ? 0.0 : -1.0; VisualDensity density = VisualDensity( horizontal: densityAmt, vertical: densityAmt, ); return MaterialApp( theme: ThemeData(visualDensity: density), home: MainAppScaffold(), ); // 获取当前 density VisualDensity density = Theme.of(context).visualDensity; ``` --- ## Checkbox ### fillColor 行为更新 M3 中 `Checkbox.fillColor` 现在应用于未选中状态的背景色。 ```dart // M3 行为 (fillColor 应用于背景) Checkbox( fillColor: MaterialStateProperty.resolveWith((states) { if (!states.contains(MaterialState.selected)) { return Colors.transparent; } return null; }), side: const BorderSide(color: Colors.red, width: 2), value: _checked, onChanged: _enabled ? (bool? value) { setState(() { _checked = value!; }); } : null, ) // 通过主题配置 checkboxTheme: CheckboxThemeData( fillColor: MaterialStateProperty.resolveWith((states) { if (!states.contains(MaterialState.selected)) { return Colors.transparent; } return null; }), side: const BorderSide(color: Colors.red, width: 2), ) ``` --- ## Toggleable Widgets (Switch, Radio) ### toggleableActiveColor 废弃 `ThemeData.toggleableActiveColor` 已废弃，改用 `ColorScheme.secondary`。 ```dart // 迁移前 MaterialApp( theme: ThemeData(toggleableActiveColor: myColor), ) // 迁移后 final ThemeData theme = ThemeData(); MaterialApp( theme: theme.copyWith( switchTheme: SwitchThemeData( thumbColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.disabled)) return null; if (states.contains(MaterialState.selected)) return myColor; return null; }, ), trackColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.disabled)) return null; if (states.contains(MaterialState.selected)) return myColor; return null; }, ), ), radioTheme: RadioThemeData( fillColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.disabled)) return null; if (states.contains(MaterialState.selected)) return myColor; return null; }, ), ), checkboxTheme: CheckboxThemeData( fillColor: MaterialStateProperty.resolveWith( (Set states) { if (states.contains(MaterialState.disabled)) return null; if (states.contains(MaterialState.selected)) return myColor; return null; }, ), ), ), ) ``` FILE:references/dependency-injection.md # Flutter 依赖注入指南 > 来源：Flutter 官方生态 > URL: https://pub.dev/packages/get_it > 版本：Flutter 3.x > 抓取时间：2026-04-24 --- ## get_it（推荐） ```dart import 'package:get_it/get_it.dart'; final getIt = GetIt.instance; // 注册服务 void setupDependencies() { // 懒加载单例 getIt.registerLazySingleton(() => Dio()); // 工厂：每次获取新实例 getIt.registerFactory( () => UserRepository(dio: getIt()), ); // 预注册实例 getIt.registerSingleton(prefs); } // 使用 final repo = getIt(); ``` ## Riverpod + get_it 结合 ```dart // Riverpod 声明依赖 get_it final dioProvider = Provider((ref) => getIt()); final userRepoProvider = Provider( (ref) => UserRepository(dio: ref.watch(dioProvider)), ); // 这样在 Provider 测试时可以单独 mock Dio 层 ``` ## injectable（代码生成） ```dart // pubspec: injectable, injectable_generator, build_runner // 声明式注入 @injectable class AuthRepository { final Dio dio; AuthRepository({required this.dio}); } // 注册（main.dart） configureInjection(); @injectableInit void main() { configureDependencies(); runApp(MyApp()); } ``` ## 常见 DI 陷阱 | 错误 | 正确 | |------|------| | ❌ 在 `build()` 中 `GetIt.instance()` | ✅ 顶层 `setupDependencies()` 中注册 | | ❌ 单例中引用非单例 | ✅ 确保生命周期一致 | | ❌ 直接 `Dio()` 硬编码 | ✅ 通过 `getIt()` 注入，便于测试时替换 mock | ## 来源 - [get_it | Pub](https://pub.dev/packages/get_it) - [injectable | Pub](https://pub.dev/packages/injectable) - [Riverpod DI 文档](https://riverpod.dev/docs/essentials/auto_dispose) FILE:references/display-components.md --- name: flutter-display-components description: Flutter 显示组件详解（对话框、卡片、FAB、 Snackbars、列表等）。 source: https://flutter.cn/docs --- # Display Components ## Dialog ### 默认 BorderRadius 变更 M3 中 Dialog 的默认圆角从 2.0 改为 4.0 像素。 ```dart // 恢复 M2 行为 AlertDialog( content: Text('Alert!'), shape: RoundedRectangleBorder( borderRadius: BorderRadius.all(Radius.circular(2)), ), ) // M3 新默认 (4.0 圆角) AlertDialog( content: Text('Alert!'), // 无需手动设置，使用新默认 ) ``` ### AlertDialog 自动滚动 `AlertDialog` 现在在内容溢出时自动滚动，确保按钮始终可见。 ```dart // 迁移后不需要手动包装 SingleChildScrollView AlertDialog( title: Text('Very, very large title', textScaleFactor: 5), content: Text('Very, very large content', textScaleFactor: 5), actions: [ TextButton(child: Text('Button 1'), onPressed: () {}), TextButton(child: Text('Button 2'), onPressed: () {}), ], ) // 迁移前需要手动处理 AlertDialog( title: SingleChildScrollView( // 不再需要 child: Text('Very, very large title', textScaleFactor: 5), ), content: SingleChildScrollView( child: Text('Scrollable content', textScaleFactor: 5), ), actions: [...], ) ``` --- ## FloatingActionButton (FAB) ### 废弃 accent 属性依赖 FAB 不再使用 `ThemeData.accentIconTheme`，改用 `FloatingActionButtonThemeData.foregroundColor`。 ```dart // 迁移前 MaterialApp( theme: ThemeData( accentIconTheme: IconThemeData(color: Colors.red), ), ) // 迁移后 MaterialApp( theme: ThemeData( floatingActionButtonTheme: FloatingActionButtonThemeData( foregroundColor: Colors.red, ), ), ) // FAB foregroundColor 优先级 final Color foregroundColor = this.foregroundColor ?? floatingActionButtonTheme.foregroundColor ?? theme.colorScheme.onSecondary; // 新默认值 ``` --- ## SnackBar ### 带 Action 的 SnackBar 不再自动消失 M3 中带 action 的 SnackBar 默认保持显示，直到用户手动交互。 ```dart // 默认行为 (M3): 带 action 的 SnackBar 不会自动消失 ScaffoldMessenger.of(context).showSnackBar( SnackBar( content: const Text('This is a snackbar with an action.'), action: SnackBarAction( label: 'Action', onPressed: () { /* 执行操作 */ }, ), ), ) // 恢复旧行为 (自动消失) ScaffoldMessenger.of(context).showSnackBar( SnackBar( content: const Text('This is a snackbar with an action.'), persist: false, // 添加此属性恢复自动消失 action: SnackBarAction( label: 'Action', onPressed: () { /* 执行操作 */ }, ), ), ) // persist 属性说明: // - true: 不自动消失，保持显示直到手动关闭 // - false: 自动消失 // - null: 默认行为 (带 action 时不自动消失) ``` --- ## ListTile ### 背景色警告当 `ListTile` 被包裹在有背景色的中间 widget 中时，框架会报告错误。 ```dart // 错误示例 Material( child: Container( color: Colors.pink, // 错误：遮蔽 ListTile 的 ink splashes child: ListTile( title: const Text('Title'), onTap: () {}, ), ), ) // 正确做法 1: 使用 Material 作为背景 Material( color: Colors.pink, child: Container( child: ListTile( title: const Text('Title'), onTap: () {}, ), ), ) // 正确做法 2: 包裹 ListTile 在自己的 Material 中 Container( color: Colors.blue, child: Material( type: MaterialType.transparency, child: ListTile( title: const Text('Title'), onTap: () {}, ), ), ) ``` --- ## Chip ### deleteButtonTooltipMessage 替换 useDeleteButtonTooltip `useDeleteButtonTooltip` 已废弃，改用 `deleteButtonTooltipMessage`。 ```dart // 禁用删除按钮 tooltip Chip( label: const Text('Disabled delete button tooltip'), onDeleted: _handleDeleteChip, deleteButtonTooltipMessage: '', // 空字符串禁用 ) // 启用删除按钮 tooltip (默认) RawChip( label: const Text('Enabled delete button tooltip'), onDeleted: _handleDeleteChip, // 不需要设置，默认启用 ) // 迁移前 Chip( label: const Text('Disabled delete button tooltip'), onDeleted: _handleDeleteChip, useDeleteButtonTooltip: false, ) ``` --- ## Container ### 颜色优化当只设置 `color` 而不使用 `decoration` 时，`Container` 现在使用更高效的 `ColoredBox`。 ```dart // 现在使用 ColoredBox 替代 BoxDecoration Container(color: Colors.red) // 测试适配 testWidgets('Container color', (WidgetTester tester) async { await tester.pumpWidget(Container(color: Colors.red)); final Container container = tester.widgetList().first; expect(container.color, Colors.red); // 直接访问 color 属性 expect(find.byType(BoxDecoration), findsNothing); expect(find.byType(ColoredBox), findsOneWidget); }) ``` --- ## Progress Indicators (M3 更新) ### LinearProgressIndicator ```dart // M3 新设计 (2024) LinearProgressIndicator( year2023: false, // 启用 M3 新设计 value: 0.5, ) // 新设计特点: // - active 和 inactive track 之间有间隙 // - 停止指示器 // - 圆角 // 全局应用 MaterialApp( theme: ThemeData( progressIndicatorTheme: const ProgressIndicatorThemeData(year2023: false), ), ) ``` ### CircularProgressIndicator ```dart // M3 新设计 (2024) CircularProgressIndicator( year2023: false, // 启用 M3 新设计 value: 0.5, ) // 新设计特点: // - track 间隙 // - 圆角 stroke cap // 全局应用 MaterialApp( theme: ThemeData( progressIndicatorTheme: const ProgressIndicatorThemeData(year2023: false), ), ) ``` --- ## Slider (M3 更新) ```dart // M3 新设计 (2024) Slider( year2023: false, // 启用 M3 新设计 value: _value, onChanged: (value) { setState(() { _value = value; }); }, ) // 新设计特点: // - 更新的高度 // - active 和 inactive track 之间的间隙 // - 停止指示器显示 inactive track 的结束值 // - 按下时 thumb 宽度调整 // - track 形状调整 // - 新的 value indicator 形状 (圆角矩形) // 全局应用 MaterialApp( theme: ThemeData( sliderTheme: const SliderThemeData(year2023: false), ), ) ``` FILE:references/hero-animations.md --- name: flutter-hero-animation description: Flutter Hero 动画实现参考。 source: https://flutter.cn/docs --- # Hero 动画 (Hero Animations) Hero 动画实现共享元素过渡（shared element transitions），让 widget 在两个页面之间"飞翔"。 ## 核心概念 ### 基本结构 Hero 动画需要两个 Hero widgets，分别位于源页面和目标页面，它们使用**相同的 tag**： ``` 源页面 Hero ──(tag)──> 目标页面 Hero ``` Flutter 会自动匹配相同 tag 的 Hero，并创建两者之间的过渡动画。 ### 关键原理 1. **Tag 匹配**：两个 Hero 必须有相同的 tag（通常是代表底层数据的对象） 2. **Navigator 触发**：push 或 pop Navigator 堆栈时触发动画 3. **Overlay 飞行**：飞行过程中，hero 被移到应用 overlay 中，显示在两个页面之上 4. **RectTween**：Flutter 使用 `RectTween` 计算 hero 从起点到终点的边界 ## 代码示例 ### 标准 Hero 动画 ```dart class PhotoHero extends StatelessWidget { const PhotoHero({ super.key, required this.photo, this.onTap, required this.width, }); final String photo; final VoidCallback? onTap; final double width; @override Widget build(BuildContext context) { return SizedBox( width: width, child: Hero( tag: photo, // 必须与目标页面的 Hero tag 相同 child: Material( color: Colors.transparent, child: InkWell( onTap: onTap, child: Image.asset( photo, fit: BoxFit.contain, ), ), ), ), ); } } // 源页面 class HeroAnimation extends StatelessWidget { const HeroAnimation({super.key}); @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text('Basic Hero Animation')), body: Center( child: PhotoHero( photo: 'images/flippers-alpha.png', width: 300.0, onTap: () { Navigator.of(context).push(MaterialPageRoute( builder: (context) { return Scaffold( appBar: AppBar(title: const Text('Flippers Page')), body: Container( color: Colors.lightBlueAccent, padding: const EdgeInsets.all(16), alignment: Alignment.topLeft, child: PhotoHero( photo: 'images/flippers-alpha.png', width: 100.0, // 目标大小 onTap: () { Navigator.of(context).pop(); }, ), ), ); }, )); }, ), ), ); } } ``` ### 自定义 flightShuttleBuilder `flightShuttleBuilder` 允许自定义 hero 在飞行过程中的外观： ```dart Hero( tag: 'hero-image', flightShuttleBuilder: ( BuildContext flightContext, Animation animation, HeroFlightDirection flightDirection, BuildContext fromHeroContext, BuildContext toHeroContext, ) { return AnimatedBuilder( animation: animation, builder: (context, child) { // 自定义飞行中的 widget return Material( color: Colors.transparent, child: ClipRRect( borderRadius: BorderRadius.circular( // 动画过程中从圆形变到方形 animation.value * 75, ), child: Image.asset( 'images/flippers-alpha.png', fit: BoxFit.contain, ), ), ); }, ); }, child: /* 源/目标 Hero 的 child */, ) ``` ### 径向 Hero 动画（圆形→方形）径向动画使用 `MaterialRectCenterArcTween` 沿弧线路径飞行，同时图像形状由圆变方： ```dart class RadialExpansion extends StatelessWidget { const RadialExpansion({ super.key, required this.maxRadius, this.child, }) : clipRectSize = 2.0 * (maxRadius / math.sqrt2); final double maxRadius; final double clipRectSize; final Widget? child; @override Widget build(BuildContext context) { return ClipOval( child: Center( child: SizedBox( width: clipRectSize, height: clipRectSize, child: ClipRect( child: child, ), ), ), ); } } // 自定义 createRectTween 实现弧形路径 static RectTween _createRectTween(Rect? begin, Rect? end) { return MaterialRectCenterArcTween(begin: begin, end: end); } Hero( tag: 'radial-hero', createRectTween: _createRectTween, child: RadialExpansion( maxRadius: 150.0, child: Image.asset('images/photo.png'), ), ) ``` ## Hero 与显式 Hero ### 隐式 Hero（默认）直接使用 `Hero` widget，Flutter 自动处理动画： ```dart Hero( tag: 'my-hero', child: Image.network('https://example.com/image.png'), ) ``` ### 显式 Hero 显式定义 `createRectTween` 以自定义飞行路径： ```dart Hero( tag: 'my-hero', createRectTween: (Rect? begin, Rect? end) { return MaterialRectCenterArcTween(begin: begin, end: end); }, child: /* ... */, ) ``` ## 关键 API | 属性 | 说明 | |------|------| | `tag` | 标识 Hero 的唯一标签，两页面间相同 tag 的 Hero 形成配对 | | `flightShuttleBuilder` | 自定义飞行过程中的 widget 外观 | | `createRectTween` | 自定义 RectTween 控制飞行路径 | | `child` | Hero 包含的内容 widget | ## 调试技巧使用 `timeDilation` 减慢动画便于调试： ```dart // 在 build 方法中 timeDilation = 5.0; // 1.0 为正常速度 // 或使用 debugPaintSizeEnabled 可视化布局 // Flutter Inspector 中启用 ``` FILE:references/large-screens.md --- name: flutter-large-screens description: Flutter 大屏支持、折叠屏设备与桌面布局模式完整参考。 source: https://flutter.cn/docs --- # Flutter 大屏设备支持本文档涵盖大屏设备布局策略、折叠屏适配、导航模式选择以及用户输入扩展支持。 ## 大屏设备定义 Flutter 将以下设备定义为"大屏"： - 平板电脑（Tablets） - 折叠屏设备（Foldables） - ChromeOS 设备 - Web 浏览器 - 桌面应用窗口 - iPad > 大屏支持不仅提升用户体验，还会改善 Play Store 评分设备分类展示，并满足 iPadOS 提审要求。 ## GridView 布局 `ListView` 在大屏上会浪费水平空间。改用 `GridView` 让内容宽度合理分布： ```dart // 从 ListView.builder 迁移到 GridView.builder GridView.builder( padding: const EdgeInsets.all(Insets.extraLarge), gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent( maxCrossAxisExtent: 400, // 最大条目宽度 childAspectRatio: 1, ), itemCount: itemCount, itemBuilder: (context, index) => _buildItem(index), ) ``` ### gridDelegate 选择 | 委托 | 适用场景 | |---|---| | `SliverGridDelegateWithFixedCrossAxisCount` | 需要固定列数 | | `SliverGridDelegateWithMaxCrossAxisExtent` | 需要最大条目宽度（响应式） | > **重要**：不要根据设备类型硬编码列数。列数应由**窗口实际宽度**决定。 ### ConstrainedBox 最大宽度限制 ```dart // 限制内容最大宽度，保持大屏上的可读性 ConstrainedBox( constraints: const BoxConstraints(maxWidth: 1200), child: GridView.builder(...), ) ``` Material 3 建议的最大宽度值参见 [Applying layout](https://m3.material.io/foundations/layout/applying-layout/window-size-classes) 指南。 --- ## 折叠屏设备（Foldables） ### 锁定方向导致的问题锁定屏幕方向（`setPreferredOrientations`）的 App 在折叠屏展开时可能出现**黑边（letterboxing）**——App 窗口锁定在屏幕中央，周围为黑色。`MediaQuery` 也不会收到更大的窗口尺寸。 ### 解决方案 **方案一**：支持所有方向（推荐） **方案二**：使用 `Display` API 获取**物理屏幕尺寸**（少数需要物理尺寸而非窗口尺寸的场景） ```dart /// 获取物理显示信息 ui.FlutterView? _view; @override void didChangeDependencies() { super.didChangeDependencies(); _view = View.maybeOf(context); } void didChangeMetrics() { final ui.Display? display = _view?.display; // display?.size 获取物理尺寸 // display?.pixelRatio 获取像素比 // display?.refreshRate 获取刷新率 } ``` > 折叠屏的**唯一**例外场景需要使用物理显示尺寸。其他所有场景均应使用 `MediaQuery.sizeOf` 的**窗口尺寸**。 --- ## 导航模式根据窗口宽度选择导航组件： ```dart Widget build(BuildContext context) { final width = MediaQuery.sizeOf(context).width; if (width < 600) { // Compact: 底部导航栏 return BottomNavigationBar(...); } else if (width < 840) { // Medium: 导航轨道 return NavigationRail( selectedIndex: _selectedIndex, onDestinationSelected: (index) => setState(() => _selectedIndex = index), destinations: _destinations .map((d) => NavigationRailDestination( icon: Icon(d.icon), label: Text(d.label), )) .toList(), ); } else { // Expanded: 永久侧边导航 return NavigationDrawer(...); } } ``` Material 3 导航规范： | 尺寸类 | 宽度 | 导航组件 | |---|---|---| | Compact | < 600 dp | `BottomNavigationBar` | | Medium | 600–839 dp | `NavigationRail` | | Expanded | ≥ 840 dp | 永久侧边导航（Drawer/NavigationRail extended） | --- ## 自适应输入支持 ### 三层大屏设备支持级别（Android 规范） | 层级 | 要求 | 说明 | |---|---|---| | Tier 3（最低） | 鼠标 + 手写笔支持 | Material 3 按钮和选择器内置支持 | | Tier 2 | 触控板 + 键盘 | 在 Tier 3 基础上扩展 | | Tier 1（最高） | 多种输入设备无缝协作 | 完整的多模态输入体验 | ### 触控板/鼠标滚动 `ScrollView` 和 `ListView` 默认支持滚轮滚动。使用 `Listener` 自定义滚动行为： ```dart return Listener( onPointerSignal: (event) { if (event is PointerScrollEvent) { print(event.scrollDelta.dy); // 垂直滚动量 } }, child: ListView(), ); ``` ### 鼠标悬停与焦点 ```dart return MouseRegion( cursor: SystemMouseCursors.click, onEnter: (_) => setState(() => _isHovered = true), onExit: (_) => setState(() => _isHovered = false), onHover: (e) => print(e.localPosition), child: GestureDetector( onTap: () { Focus.of(context).requestFocus(); _submit(); }, child: Logo(showBorder: _isHovered), ), ); ``` ### 键盘快捷键 ```dart class CreateNewItemIntent extends Intent { const CreateNewItemIntent(); } Widget build(BuildContext context) { return Shortcuts( shortcuts: const { SingleActivator(LogicalKeyboardKey.keyN, control: true): CreateNewItemIntent(), }, child: Actions( actions: >{ CreateNewItemIntent: CallbackAction( onInvoke: (intent) => _createNewItem(), ), }, child: Focus(autofocus: true, child: Container()), ), ); } ``` 全局快捷键使用 `HardwareKeyboard.instance.addHandler`。 ### 视觉密度 ```dart // 触摸设备：标准密度；桌面设备：紧凑 double densityAmt = touchMode ? 0.0 : -1.0; VisualDensity density = VisualDensity( horizontal: densityAmt, vertical: densityAmt, ); MaterialApp( theme: ThemeData(visualDensity: density), home: MainAppScaffold(), ); ``` --- ## 状态保存 ### 列表滚动位置方向改变时使用 `PageStorageKey` 保存和恢复滚动位置： ```dart // 保存 ListView.builder( key: PageStorageKey('my-list-key'), itemBuilder: (context, index) => ListTile(title: Text('Item $index')), ); // 如果列表布局在方向改变时也变化，可能需要额外计算滚动位置 ``` ### 配置变更时的状态应用应在设备旋转、窗口大小变化、折叠/展开时保持状态。如果状态丢失，检查插件和大屏支持情况。 --- ## 最佳实践速查 | 不要做 | 正确做法 | |---|---| | 锁定屏幕方向 | 支持所有方向 | | `MediaQuery.orientation` 判断布局 | `MediaQuery.sizeOf` 或 `LayoutBuilder` | | 根据设备类型判断尺寸 | 根据窗口实际宽度判断 | | `ListView` 填满水平空间 | `GridView` + `ConstrainedBox(maxWidth)` | | 触摸优先再考虑桌面 | 先构建触摸 UI，桌面作为加速层 | | 忽略辅助功能 | 键盘导航 + 焦点管理 + 语义标签 | ## 参考资源 - [Material 3 Window Size Classes](https://m3.material.io/foundations/layout/applying-layout/window-size-classes) - [Android Large Screen App Quality Guidelines](https://developer.android.com/docs/quality-guidelines/large-screen-app-quality) - [Apple Designing for iPadOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-ipados) - [Building an animated responsive app layout with Material 3]({{site.codelabs}}/codelabs/flutter-animated-responsive-layout) FILE:references/layout-constraints.md --- name: flutter-layout description: Flutter 布局约束与约束传递机制完整参考。 source: https://flutter.cn/docs/development/ui/layout/constraints --- # Flutter 布局约束 (Layout Constraints) ## 核心规则 > **约束向下传递，大小向上传递，父级决定位置** Flutter 布局遵循一个简单的规则： 1. **Widget 从父级获取约束** — 约束是 4 个浮点数的集合：min/max 宽度和 min/max 高度 2. **Widget 向下传递约束给子级** — 可为每个子级传递不同约束 3. **Widget 询问子级想要的大小** 4. **Widget 向上返回自身大小** 5. **父级决定子级的位置** ```dart // 布局协商示例 Widget: "嘿父级，我的约束是多少？" Parent: "你的宽度在 0-300px，高度在 0-85px。" Widget: "我需要 5px padding，所以子级最多 290x75。" Widget (对子级): "你的宽度在 0-290px，高度在 0-75px。" First Child: "那我想要 290x20。" Widget (对第二个子级): "由于第一个占用了高度，现在只剩 55px 给你。" Widget: "父级，我决定我的大小是 300x60。" ``` --- ## BoxConstraints — Tight vs Loose ### Tight Constraints（严格约束）约束的最大值等于最小值 — 只有一个可能的尺寸。 ```dart // Tight: 强制精确尺寸 BoxConstraints.tight(Size size) // 相当于: BoxConstraints(minWidth: size.width, maxWidth: size.width, minHeight: size.height, maxHeight: size.height) ``` **示例**: 屏幕 → `Container(width:100, height:100)` — Container 想设为 100x100，但被屏幕强制填充整个屏幕。 ### Loose Constraints（宽松约束）最小值为 0，最大值非零 — Widget 可以是任意大小（从 0 到最大值）。 ```dart // Loose: 允许任意尺寸（最小为0） BoxConstraints.loose(Size size) // 相当于: BoxConstraints(minWidth: 0, maxWidth: size.width, minHeight: 0, maxHeight: size.height) ``` **示例**: `Center` 的作用是将从屏幕获得的 tight 约束转换为 loose 约束传递给子级。 --- ## Unbounded Constraints（无界约束）当 `maxWidth` 或 `maxHeight` 为 `double.infinity` 时，约束是无界的。 ```dart // 无界约束会导致渲染错误 UnconstrainedBox( child: Container(width: double.infinity, height: 100) // 错误！ ) ``` ### 常见无界约束场景 1. **Flex 容器内** (`Row`/`Column`) 的主轴方向 2. **滚动区域内** (`ListView`, `ScrollView`) ### 处理无界约束的 Widget | Widget | 用途 | |--------|------| | `LimitedBox` | 当获得无限约束时添加限制；放入 `Center` 时限制失效 | | `OverflowBox` | 允许子级超出自身，不显示溢出警告 | | `UnconstrainedBox` | 允许子级任意大小（但仍可能溢出） | ```dart // LimitedBox: 仅在获得无限约束时生效 UnconstrainedBox( child: LimitedBox( maxWidth: 100, child: Container(width: double.infinity) // 被限制为100px ), ) // OverflowBox: 不警告溢出 OverflowBox( minWidth: 0, minHeight: 0, maxWidth: double.infinity, maxHeight: double.infinity, child: Container(width: 4000, height: 50) // 显示但不警告 ) ``` --- ## 关键布局 Widget ### SizedBox — 固定尺寸 ```dart SizedBox(width: 100, height: 50, child: child) // 常用变体: SizedBox.expand() // 强制填满父级 SizedBox.shrink() // 收缩到最小 SizedBox.fromSize() // 从 Size 创建 ``` ### ConstrainedBox — 添加额外约束 > **重要**: `ConstrainedBox` 只施加**额外**约束，不会替换父级约束。 ```dart // 错误理解: Container 会在 70-150px 之间 ConstrainedBox( constraints: BoxConstraints(minWidth:70, maxWidth:150, minHeight:70, maxHeight:150), child: Container(width: 10, height: 10) // ❌ 被忽略 ) // 正确理解: 需要配合 Center 等提供 loose 约束的父级 Center( child: ConstrainedBox( constraints: BoxConstraints(minWidth:70, maxWidth:150), child: Container(width: 10) // ✅ 实际为 70px ), ) ``` ### Padding — 内边距 ```dart Padding( padding: EdgeInsets.all(20), child: Container(color: red, child: ...) ) // Container 实际获得 40x40 的空间（减去 padding） ``` ### Flexible 与 Expanded — Flex 容器内的空间分配 | Widget | 行为 | |--------|------| | `Flexible` | 允许子级**小于等于** Flexible 的宽度 | | `Expanded` | 强制子级**等于** Expanded 的宽度 | ```dart Row([ Expanded( // 忽略子级原本大小，按比例分配 flex: 1, // 默认 flex=1 child: Container(color: red, width: 1000) // 被强制为可用空间的 1/3 ), Expanded( flex: 2, child: Container(color: green) // 被强制为可用空间的 2/3 ), ]) ``` > **注意**: `Expanded` 和 `Flexible` 会**忽略**子级想要的大小。无法按子级原始大小比例分配。 ### FittedBox — 缩放以填满空间 ```dart // Text 会缩放以填满可用宽度 FittedBox(child: Text('Some text')) // 配合 Center: 如果 Text 不超出屏幕则不缩放 Center(child: FittedBox(child: Text('Short text'))) // 无缩放 // Text 超出屏幕时缩放到屏幕大小 Center(child: FittedBox(child: Text('Very long text...'))) // 缩放 ``` > **限制**: `FittedBox` 只能缩放**有界**（非无限）的子级。 ### Stack — 层叠布局 ```dart Stack([ Container(width: 100, height: 100, color: red), Positioned( right: 10, top: 10, child: Container(width: 50, height: 50, color: green) ), ]) ``` ### Align 与 Center — 对齐 ```dart // Center 是 alignment: Alignment.center 的 Align Center(child: ...) ≈ Align(alignment: Alignment.center, child: ...) // 定位到右下角 Align( alignment: Alignment.bottomRight, child: Container(width: 100, height: 100) ) ``` --- ## Flex 布局规则 (Row/Column) Flex 容器根据**主轴方向**的约束是否有限来决定行为： | 约束类型 | 行为 | |----------|------| | **有限约束** | Flex 尝试撑满可用空间 | | **无限约束** | Flex 尝试适应子级大小（所有子级 `flex` 必须为 0） | ### 交叉方向必须有限 ```dart // ❌ 错误: Column 的宽度（交叉方向）不能无限 Column(children: [Expanded(child: Text('...'))]) // 抛出异常 // ✅ 正确: 需要在外层限制宽度 Center( child: Column(children: [Expanded(child: Text('...'))]) ) ``` --- ## 常见布局陷阱 ### 1. 设置了尺寸却不生效 ```dart // ❌ 错误: 屏幕强制 Container 填满屏幕 Container(width: 100, height: 100, color: red) // ✅ 正确: 用 Center 提供 loose 约束 Center(child: Container(width: 100, height: 100, color: red)) ``` ### 2. ConstrainedBox 不生效 ```dart // ❌ 错误: ConstrainedBox 被父级的 tight 约束"吃掉" ConstrainedBox( constraints: BoxConstraints(minWidth: 70, maxWidth: 150), child: Container(width: 10) // 被忽略 ) // ✅ 正确: 父级需提供 loose 约束 Center( child: ConstrainedBox( constraints: BoxConstraints(minWidth: 70, maxWidth: 150), child: Container(width: 10) // 实际 70px ), ) ``` ### 3. Row/Column 溢出 ```dart // ❌ 错误: 子级太大导致溢出 Row([ Container(color: red, child: Text('Very long text...'))) Container(color: green, child: Text('Goodbye!')) ]) // ✅ 正确: 用 Expanded 分配空间 Row([ Expanded(child: Container(color: red, child: Text('...'))) Container(color: green, child: Text('Goodbye!')) ]) ``` ### 4. 无限尺寸渲染错误 ```dart // ❌ 错误: Flutter 无法渲染无限尺寸 UnconstrainedBox( child: Container(width: double.infinity) // 抛出异常 ) // ✅ 正确: 用 LimitedBox 限制 UnconstrainedBox( child: LimitedBox(maxWidth: 100, child: Container(...)) ) ``` ### 5. Flex 内使用 Expanded 时 flex 为 0 ```dart // ❌ 错误: Flex 容器在无限约束下，所有 flex 必须为 0 // 但 Expanded 默认 flex=1，会抛出异常 // ✅ 正确: 如果需要扩展，确保 Flex 获得有限约束 ``` --- ## LayoutBuilder 与 MediaQuery > 文档原文件主要聚焦于约束传递机制。`LayoutBuilder` 和 `MediaQuery` 的详细说明请参考其他文档。 ### LayoutBuilder 在布局时获取可用约束： ```dart LayoutBuilder( builder: (context, constraints) { if (constraints.maxWidth > 600) { return WideLayout(); } else { return NarrowLayout(); } } ) ``` ### MediaQuery 获取媒体查询数据（屏幕大小、像素密度等）： ```dart MediaQuery.of(context).size // 屏幕尺寸 MediaQuery.of(context).padding // 系统 UI 边距 MediaQuery.of(context).orientation // 屏幕方向 ``` --- ## Widget 布局行为分类 | 类型 | 示例 | 行为 | |------|------|------| | **撑满型** | `Center`, `ListView`, `Container` | 尽可能撑满约束范围 | | **跟随子级型** | `Transform`, `Opacity` | 尽可能与子级保持一致 | | **固定尺寸型** | `Image`, `Text` | 尝试变为指定大小 | --- ## 调试布局的步骤 1. **向上追溯**: 从 leaf widget 开始，查看每个父级传递了什么约束 2. **检查约束类型**: 是 tight 还是 loose？是有限还是无限？ 3. **验证子级大小**: 子级想要的大小 vs 最终获得的大小 4. **使用 DevTools**: Flutter DevTools 的 Inspector 可视化布局边界 --- ## 关键参考 - **规则**: 约束向下传递 → 大小向上传递 → 父级决定位置 - **Tight**: maxWidth == minWidth, maxHeight == minHeight（唯一尺寸） - **Loose**: minWidth == 0, minHeight == 0（任意尺寸从 0 到 max） - **Unbounded**: maxWidth 或 maxHeight 为 `double.infinity` - **ConstrainedBox**: 只添加额外约束，不替换父级约束 - **Expanded/Flexible**: 忽略子级大小，按比例分配空间 FILE:references/material-3.md --- name: flutter-material-3 description: Flutter Material 3 迁移与主题系统完整参考。 source: https://flutter.cn/docs/release/breaking-changes/material-3-migration --- # Flutter Material 3 迁移与主题系统完整参考 ## 目录 1. [Material 3 迁移概述](#1-material-3-迁移概述) 2. [ColorScheme 变化](#2-colorscheme-变化) 3. [组件主题规范化](#3-组件主题规范化) 4. [Material 3 Token 更新](#4-material-3-token-更新) 5. [Material Color Utilities](#5-material-color-utilities) 6. [Material State → WidgetState](#6-material-state--widgetstate) 7. [Material Theme System 更新](#7-material-theme-system-更新) 8. [关键 breaking changes 汇总](#8-关键-breaking-changes-汇总) --- ## 1. Material 3 迁移概述 ### 1.1 useMaterial3 默认为 true **生效版本**: Flutter 3.16 (2023年11月) 从 Flutter 3.16 开始，`useMaterial3` 默认为 `true`。这是 Material Design 3 在 Flutter 中的里程碑变化。 ```dart // Flutter 3.16 之前 - 需要手动启用 MaterialApp( theme: ThemeData( useMaterial3: true, // 显式启用 ), ) // Flutter 3.16+ - 默认启用 MaterialApp( theme: ThemeData( // useMaterial3: true 已为默认值 ), ) ``` **注意**: 虽然可以设置 `useMaterial3: false` 临时回退到 Material 2，但这只是临时解决方案。`useMaterial3` 标志和 Material 2 实现将最终被移除。 ### 1.2 需要手动迁移的组件部分组件无法仅通过样式更新匹配 Material 3，需要使用新组件替代： | Material 2 组件 | Material 3 替代 | 特点 | |---|---|---| | `BottomNavigationBar` | `NavigationBar` | 更高度，pill-shaped 导航指示器，新颜色映射 | | `Drawer` | `NavigationDrawer` | pill-shaped 导航指示器，圆角，新颜色映射 | | `ToggleButtons` | `SegmentedButton` | 完全圆角，使用 Dart `Set` 确定选中项 | ### 1.3 BottomNavigationBar → NavigationBar 迁移 ```dart // 迁移前 (Material 2) BottomNavigationBar( items: const [ BottomNavigationBarItem( icon: Icon(Icons.home), label: 'Home', ), BottomNavigationBarItem( icon: Icon(Icons.business), label: 'Business', ), BottomNavigationBarItem( icon: Icon(Icons.school), label: 'School', ), ], ) // 迁移后 (Material 3) NavigationBar( destinations: const [ NavigationDestination( icon: Icon(Icons.home), label: 'Home', ), NavigationDestination( icon: Icon(Icons.business), label: 'Business', ), NavigationDestination( icon: Icon(Icons.school), label: 'School', ), ], ) ``` ### 1.4 Drawer → NavigationDrawer 迁移 ```dart // 迁移前 Drawer( child: ListView( children: [ DrawerHeader( child: Text('Drawer Header'), ), ListTile( leading: const Icon(Icons.message), title: const Text('Messages'), onTap: () { }, ), // ... ], ), ) // 迁移后 NavigationDrawer( children: [ DrawerHeader( child: Text('Drawer Header'), ), const NavigationDrawerDestination( icon: Icon(Icons.message), label: Text('Messages'), ), // ... ], ) ``` ### 1.5 ToggleButtons → SegmentedButton 迁移 ```dart // 迁移前 enum Weather { cloudy, rainy, sunny } ToggleButtons( isSelected: const [false, true, false], onPressed: (int newSelection) { }, children: const [ Icon(Icons.cloud_outlined), Icon(Icons.beach_access_sharp), Icon(Icons.brightness_5_sharp), ], ) // 迁移后 enum Weather { cloudy, rainy, sunny } SegmentedButton( selected: const {Weather.rainy}, onSelectionChanged: (Set newSelection) { }, segments: const >[ ButtonSegment( icon: Icon(Icons.cloud_outlined), value: Weather.cloudy, ), ButtonSegment( icon: Icon(Icons.beach_access_sharp), value: Weather.rainy, ), ButtonSegment( icon: Icon(Icons.brightness_5_sharp), value: Weather.sunny, ), ], ) ``` ### 1.6 新增组件 Material 3 引入的新组件： - **`MenuBar`** / **`MenuAnchor`**: 桌面风格菜单系统，支持鼠标和键盘完全遍历 - **`DropdownMenu`**: 结合文本框和菜单的组合框 - **`SearchBar`** / **`SearchAnchor`**: 搜索交互组件 - **`Badge`**: 装饰子组件的小标签 - **`FilledButton`** / **`FilledButton.tonal`**: 类似 ElevatedButton 但无海拔变化和投影 - **`FilterChip.elevated`** / **`ChoiceChip.elevated`** / **`ActionChip.elevated`**: 带投影和填充色的芯片变体 - **`Dialog.fullscreen`**: 全屏对话框 - **`SliverAppBar.medium`** / **`SliverAppBar.large`**: 中等和大型应用栏 ### 1.7 Medium App Bar 示例 ```dart CustomScrollView( slivers: [ const SliverAppBar.medium( title: Text('Title'), ), SliverToBoxAdapter( child: Card( child: SizedBox( height: 1200, child: Padding( padding: const EdgeInsets.fromLTRB(8, 100, 8, 100), child: Text( 'Here be scrolling content...', style: Theme.of(context).textTheme.headlineSmall, ), ), ), ), ), ], ) ``` ### 1.8 Typography 变化 Material 3 更新了 `TextTheme` 的默认值，包括字体大小、字重、字母间距和行高的变化。 ```dart // 如果必须保持之前的行为，调整文本样式 ConstrainedBox( constraints: const BoxConstraints(maxWidth: 200), child: Text( 'This is a very long text that should wrap to multiple lines.', style: Theme.of(context).textTheme.bodyMedium!.copyWith( letterSpacing: 0.0, ), ), ) ``` --- ## 2. ColorScheme 变化 ### 2.1 ColorScheme.fromSeed `ColorScheme.fromSeed` 是 Material 3 推荐的颜色生成方式： ```dart // 推荐方式 theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), ), // 深色主题 darkTheme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.deepPurple, brightness: Brightness.dark, ), ), ``` ### 2.2 动态颜色方案 (从图片生成) ```dart ColorScheme.fromImageProvider( provider: NetworkImage('https://example.com/image.jpg'), ) ``` ### 2.3 新的基于色调的 Surface 颜色 Material 3 引入了 7 个新的基于色调的 surface 颜色： | 属性 | 说明 | |---|---| | `surfaceBright` | 亮 surface | | `surfaceDim` | 暗 surface | | `surfaceContainer` | 基础容器 | | `surfaceContainerLow` | 低容器 | | `surfaceContainerLowest` | 最低容器 | | `surfaceContainerHigh` | 高容器 | | `surfaceContainerHighest` | 最高容器 | 这些颜色消除了 `surfaceTintColor` 的使用，替代了基于透明度的海拔叠加模型。 ### 2.4 被废弃的颜色角色 | 废弃 | 替代 | |---|---| | `background` | `surface` | | `onBackground` | `onSurface` | | `surfaceVariant` | `surfaceContainerHighest` | ```dart // 迁移前 colorScheme.copyWith( background: myColor1, onBackground: myColor2, surfaceVariant: myColor3, ) // 迁移后 colorScheme.copyWith( surface: myColor1, onSurface: myColor2, surfaceContainerHighest: myColor3, ) ``` ### 2.5 surfaceTint 变化 `ColorScheme.surfaceTint` 在 Material 3 中表示组件的海拔。某些组件（如 Card 和 ElevatedButton）同时使用 `surfaceTint` 和 `shadowColor`，而 AppBar 只使用 `surfaceTint`。 ```dart // 恢复之前的行为 theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple).copyWith( surfaceTint: Colors.transparent, ), appBarTheme: AppBarTheme( elevation: 4.0, shadowColor: Theme.of(context).colorScheme.shadow, ), ) ``` ### 2.6 恢复 Material 2 的 background 颜色 ```dart // 亮色主题 theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple).copyWith( surface: Colors.grey[50]!, ), ), // 暗色主题 darkTheme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.deepPurple, brightness: Brightness.dark, ).copyWith(surface: Colors.grey[850]!), ), ``` ### 2.7 DynamicSchemeVariant (3.22+) 当向 `ColorScheme.fromSeed` 提供亮色种子时，可能生成相对较暗的 `ColorScheme`。要强制输出保持亮色： ```dart ColorScheme.fromSeed( seedColor: Color(0xFF0000FF), // 亮蓝色 dynamicSchemeVariant: DynamicSchemeVariant.fidelity, ) ``` ### 2.8 ElevatedButton 样式变化 Material 3 中 `ElevatedButton` 使用新的颜色组合。如果需要保持之前的视觉效果： ```dart // 迁移前 ElevatedButton( onPressed: () {}, child: const Text('Button'), ) // 迁移后 - 保持之前的视觉效果 ElevatedButton( style: ElevatedButton.styleFrom( backgroundColor: Theme.of(context).colorScheme.primary, foregroundColor: Theme.of(context).colorScheme.onPrimary, ), onPressed: () {}, child: const Text('Button'), ) // 或使用新的 FilledButton FilledButton( onPressed: () {}, child: const Text('Button'), ) ``` --- ## 3. 组件主题规范化 Flutter 持续规范化组件主题，遵循一致的命名约定。 ### 3.1 组件主题命名约定 | ThemeData 属性 | 旧类型 | 新类型 | 生效版本 | |---|---|---|---| | `cardTheme` | `CardTheme` | `CardThemeData` | 3.27 | | `dialogTheme` | `DialogTheme` | `DialogThemeData` | 3.27 | | `tabBarTheme` | `TabBarTheme` | `TabBarThemeData` | 3.27 | | `appBarTheme` | `AppBarTheme` | `AppBarThemeData` | 3.35 | | `bottomAppBarTheme` | `BottomAppBarTheme` | `BottomAppBarThemeData` | 3.35 | | `inputDecorationTheme` | `InputDecorationTheme` | `InputDecorationThemeData` | 3.35 | ### 3.2 CardTheme / DialogTheme / TabBarTheme 迁移 (3.27) ```dart // 迁移前 final CardTheme cardTheme = Theme.of(context).cardTheme; final CardTheme cardTheme = CardTheme.of(context); final DialogTheme dialogTheme = Theme.of(context).dialogTheme; final DialogTheme dialogTheme = DialogTheme.of(context); final TabBarTheme tabBarTheme = Theme.of(context).tabBarTheme; final TabBarTheme tabBarTheme = TabBarTheme.of(context); // 在 ThemeData 中 final ThemeData theme = ThemeData( cardTheme: CardTheme(), dialogTheme: DialogTheme(), tabBarTheme: TabBarTheme(), ); final ThemeData theme = ThemeData().copyWith( cardTheme: CardTheme(), dialogTheme: DialogTheme(), tabBarTheme: TabBarTheme(), ); // 迁移后 final CardThemeData cardTheme = Theme.of(context).cardTheme; final CardThemeData cardTheme = CardTheme.of(context); final DialogThemeData dialogTheme = Theme.of(context).dialogTheme; final DialogThemeData dialogTheme = DialogTheme.of(context); final TabBarThemeData tabBarTheme = Theme.of(context).tabBarTheme; final TabBarThemeData tabBarTheme = TabBarTheme.of(context); // 在 ThemeData 中 final ThemeData theme = ThemeData( cardTheme: CardThemeData(), dialogTheme: DialogThemeData(), tabBarTheme: TabBarThemeData(), ); final ThemeData theme = ThemeData().copyWith( cardTheme: CardThemeData(), dialogTheme: DialogThemeData(), tabBarTheme: TabBarThemeData(), ); ``` ### 3.3 AppBarTheme / BottomAppBarTheme / InputDecorationTheme 迁移 (3.35) ```dart // 迁移前 final AppBarTheme appBarTheme = Theme.of(context).appBarTheme; final AppBarTheme appBarTheme = AppBarTheme.of(context); final BottomAppBarTheme bottomAppBarTheme = Theme.of(context).bottomAppBarTheme; final BottomAppBarTheme bottomAppBarTheme = BottomAppBarTheme.of(context); final InputDecorationTheme inputDecorationTheme = Theme.of(context).inputDecorationTheme; final InputDecorationTheme inputDecorationTheme = InputDecorationTheme.of(context); // 迁移后 final AppBarThemeData appBarTheme = Theme.of(context).appBarTheme; final AppBarThemeData appBarTheme = AppBarTheme.of(context); final BottomAppBarThemeData bottomAppBarTheme = Theme.of(context).bottomAppBarTheme; final BottomAppBarThemeData bottomAppBarTheme = BottomAppBarTheme.of(context); final InputDecorationThemeData inputDecorationTheme = Theme.of(context).inputDecorationTheme; final InputDecorationThemeData inputDecorationTheme = InputDecorationTheme.of(context); ``` ### 3.4 DatePickerTheme / TimePickerTheme 中的 InputDecorationTheme ```dart // 迁移前 const DatePickerThemeData datePickerTheme = DatePickerThemeData( inputDecorationTheme: InputDecorationTheme() ); const TimePickerThemeData timePickerTheme = TimePickerThemeData( inputDecorationTheme: InputDecorationTheme() ); // 迁移后 const DatePickerThemeData datePickerTheme = DatePickerThemeData( inputDecorationTheme: InputDecorationThemeData() ); const TimePickerThemeData timePickerTheme = TimePickerThemeData( inputDecorationTheme: InputDecorationThemeData() ); ``` --- ## 4. Material 3 Token 更新 ### 4.1 颜色角色映射更新 (v6.1) Material 3 tokens 更新了 4 个颜色角色在亮色模式下的映射： | 属性 | 旧值 | 新值 | |---|---|---| | `onPrimaryContainer` | Primary10 | Primary30 | | `onSecondaryContainer` | Secondary10 | Secondary30 | | `onTertiaryContainer` | Tertiary10 | Tertiary30 | | `onErrorContainer` | Error10 | Error30 | 这些变化使颜色更美观且保持可访问的对比度。 ### 4.2 恢复旧颜色 ```dart final ColorScheme colors = ThemeData().colorScheme.copyWith( onPrimaryContainer: const Color(0xFF21005D), onSecondaryContainer: const Color(0xFF1D192B), onTertiaryContainer: const Color(0xFF31111D), onErrorContainer: const Color(0xFF410E0B), ); ``` ### 4.3 Chip 边框颜色变化 Chip 组件的边框颜色从 `ColorScheme.outline` 变为 `ColorScheme.outlineVariant`。影响组件: `Chip`, `ActionChip`, `ChoiceChip`, `FilterChip`, `InputChip` ```dart // 恢复之前的边框颜色 final chip = ChipTheme( data: ChipThemeData( side: BorderSide( color: Theme.of(context).colorScheme.outline ), ), child: ActionChip( label: const Text('action chip'), onPressed: () {} ) ); ``` --- ## 5. Material Color Utilities ### 5.1 包更新 `package:material_color_utilities` 从 `v0.11.1` 更新到 `0.13.0`。 ### 5.2 受影响的属性算法更新影响以下属性的生成： - `onPrimaryContainer` - `onSecondaryContainer` - `onTertiaryContainer` - `onErrorContainer` ### 5.3 影响的 API - `ColorScheme.fromSeed` - `ColorScheme.fromImageProvider` - `ThemeData(colorScheme: ..)` ### 5.4 迁移说明新算法生成的颜色通常更易读、更美观。如果需要保持之前的颜色，需要在生成后手动设置： ```dart final colorScheme = ColorScheme.fromSeed( seedColor: seedColor, onPrimaryContainer: previousColor, onSecondaryContainer: previousColor, onTertiaryContainer: previousColor, onErrorContainer: previousColor, ); ``` --- ## 6. Material State → WidgetState ### 6.1 重命名原因 `MaterialState` 提供的功能（处理 widgets 可以拥有的多种状态，如"悬停"、"聚焦"、"禁用"）在 Material 库之外也很有用。为了让 Widgets 层和 Cupertino 也能使用，API 被移到了 widgets 库，并重命名为 `WidgetState`。 ### 6.2 API 对照表 | 旧 (MaterialState) | 新 (WidgetState) | |---|---| | `MaterialState` | `WidgetState` | | `MaterialStatePropertyResolver` | `WidgetStatePropertyResolver` | | `MaterialStateColor` | `WidgetStateColor` | | `MaterialStateMouseCursor` | `WidgetStateMouseCursor` | | `MaterialStateBorderSide` | `WidgetStateBorderSide` | | `MaterialStateOutlinedBorder` | `WidgetStateOutlinedBorder` | | `MaterialStateTextStyle` | `WidgetStateTextStyle` | | `MaterialStateProperty` | `WidgetStateProperty` | | `MaterialStatePropertyAll` | `WidgetStatePropertyAll` | | `MaterialStatesController` | `WidgetStatesController` | ### 6.3 迁移示例 ```dart // 迁移前 MaterialState selected = MaterialState.selected; final MaterialStateProperty backgroundColor; class _MouseCursor extends MaterialStateMouseCursor { const _MouseCursor(this.resolveCallback); final MaterialPropertyResolver resolveCallback; @override MouseCursor resolve(Set states) => resolveCallback(states) ?? MouseCursor.uncontrolled; } BorderSide side = MaterialStateBorderSide.resolveWith((Set states) { if (states.contains(MaterialState.selected)) { return const BorderSide(color: Colors.red); } return null; }); // 迁移后 WidgetState selected = WidgetState.selected; final WidgetStateProperty backgroundColor; class _MouseCursor extends WidgetStateMouseCursor { const _MouseCursor(this.resolveCallback); final WidgetPropertyResolver resolveCallback; @override MouseCursor resolve(Set states) => resolveCallback(states) ?? MouseCursor.uncontrolled; } BorderSide side = WidgetStateBorderSide.resolveWith((Set states) { if (states.contains(WidgetState.selected)) { return const BorderSide(color: Colors.red); } return null; }); ``` ### 6.4 保留在 Material 库的类以下类保留在 Material 库中，没有 `WidgetState` 等价物，因为它们特定于 Material 设计： - `MaterialStateOutlineInputBorder` - `MaterialStateUnderlineInputBorder` --- ## 7. Material Theme System 更新 ### 7.1 ThemeData 属性类型变更在 Flutter 3.32 中，`ThemeData` 的组件主题属性类型最终化为： | ThemeData 属性 | 类型 | |---|---| | `cardTheme` | `CardThemeData?` | | `dialogTheme` | `DialogThemeData?` | | `tabBarTheme` | `TabBarThemeData?` | | `appBarTheme` | `AppBarThemeData?` | | `bottomAppBarTheme` | `BottomAppBarThemeData?` | | `inputDecorationTheme` | `InputDecorationThemeData?` | ### 7.2 使用示例 ```dart final ThemeData theme = ThemeData( cardTheme: CardThemeData(), dialogTheme: DialogThemeData(), tabBarTheme: TabBarThemeData(), appBarTheme: AppBarThemeData(), bottomAppBarTheme: BottomAppBarThemeData(), inputDecorationTheme: InputDecorationThemeData(), ); ``` --- ## 8. 关键 Breaking Changes 汇总 | 变化 | 生效版本 | 严重程度 | |---|---|---| | `useMaterial3` 默认为 `true` | 3.16 | 高 | | BottomNavigationBar → NavigationBar | 3.16 | 中 (可选迁移) | | Drawer → NavigationDrawer | 3.16 | 中 (可选迁移) | | ToggleButtons → SegmentedButton | 3.16 | 中 (可选迁移) | | `background` → `surface` | 3.22 | 低 | | `onBackground` → `onSurface` | 3.22 | 低 | | `surfaceVariant` → `surfaceContainerHighest` | 3.22 | 低 | | `MaterialState` → `WidgetState` | 3.22 | 高 | | CardTheme → CardThemeData | 3.27 | 中 | | DialogTheme → DialogThemeData | 3.27 | 中 | | TabBarTheme → TabBarThemeData | 3.27 | 中 | | AppBarTheme → AppBarThemeData | 3.35 | 中 | | BottomAppBarTheme → BottomAppBarThemeData | 3.35 | 中 | | InputDecorationTheme → InputDecorationThemeData | 3.35 | 中 | | Token 更新 (onPrimaryContainer 等) | 3.27 | 低 | | Chip 边框颜色变化 | 3.27 | 低 | ### 8.1 ReorderableListView 本地化字符串迁移 (3.13) `ReorderableListView` 的本地化字符串从 Material 本地化移至 Widgets 本地化： ```dart // 迁移前 MaterialLocalizations.of(context).reorderItemToStart; // 迁移后 WidgetsLocalizations.of(context).reorderItemToStart; ``` 如果自定义 `MaterialLocalizations` 或 `WidgetsLocalizations`，需要将翻译从 `MaterialLocalizations` 子类移到 `WidgetsLocalizations` 子类。 --- ## 附录：完整迁移检查清单 ### 启用 Material 3 ```dart MaterialApp( theme: ThemeData( useMaterial3: true, // 默认值，但建议显式设置 colorScheme: ColorScheme.fromSeed(seedColor: yourBrandColor), ), ) ``` ### 颜色迁移 - [ ] 将 `ColorScheme.background` 替换为 `ColorScheme.surface` - [ ] 将 `ColorScheme.onBackground` 替换为 `ColorScheme.onSurface` - [ ] 将 `ColorScheme.surfaceVariant` 替换为 `ColorScheme.surfaceContainerHighest` - [ ] 考虑使用 `ColorScheme.fromSeed()` 生成颜色方案 ### 组件迁移 - [ ] `BottomNavigationBar` → `NavigationBar` - [ ] `Drawer` → `NavigationDrawer` - [ ] `ToggleButtons` → `SegmentedButton` - [ ] 考虑使用新的 M3 组件: FilledButton, Badge, SearchBar 等 ### 类型迁移 - [ ] `CardTheme` → `CardThemeData` - [ ] `DialogTheme` → `DialogThemeData` - [ ] `TabBarTheme` → `TabBarThemeData` - [ ] `AppBarTheme` → `AppBarThemeData` - [ ] `BottomAppBarTheme` → `BottomAppBarThemeData` - [ ] `InputDecorationTheme` → `InputDecorationThemeData` ### State API 迁移 - [ ] `MaterialState` → `WidgetState` - [ ] `MaterialStateProperty` → `WidgetStateProperty` - [ ] `MaterialStateColor` → `WidgetStateColor` - [ ] `MaterialStatesController` → `WidgetStatesController` --- ## 参考链接 - [Material Design for Flutter](https://flutter.cn/ui/design/material) - [Material 3 Gallery](https://github.com/flutter/samples/tree/main/material_3_demo) - [Material 3 Umbrella Issue](https://github.com/flutter/flutter/issues/91605) - [ThemeData API](https://api.flutter.dev/flutter/material/ThemeData-class.html) - [ColorScheme API](https://api.flutter.dev/flutter/material/ColorScheme-class.html) FILE:references/navigation-components.md --- name: flutter-navigation-components description: Flutter 导航组件详解（AppBar、NavigationBar、NavigationRail、Drawer）。 source: https://flutter.cn/docs --- # Navigation Components ## AppBar ### color 参数废弃 `AppBarTheme` 和 `AppBarThemeData` 中的 `color` 参数已废弃，改用 `backgroundColor`。 ```dart // 迁移前 (废弃) AppBarTheme( color: Colors.blue, elevation: 4.0, ) AppBarTheme( color: Colors.green, elevation: 4.0, ) theme.copyWith( color: Colors.red, // 废弃 ) // 迁移后 AppBarTheme( backgroundColor: Colors.blue, elevation: 4.0, ) AppBarThemeData( backgroundColor: Colors.green, elevation: 4.0, ) theme.copyWith( backgroundColor: Colors.red, ) ``` ### 使用限制同时使用 `color` 和 `backgroundColor` 会触发断言错误： ``` The color and backgroundColor parameters mean the same thing. Only specify one. ``` --- ## BottomNavigationBar ### title 废弃，改用 label `BottomNavigationBarItem.title` 已废弃，改用 `label` (String 类型)。此变更为了支持文本缩放和长按显示 tooltip 的无障碍功能。 ```dart // 迁移前 BottomNavigationBarItem( icon: Icons.add, title: Text('add'), // Widget 类型 ) // 迁移后 BottomNavigationBarItem( icon: Icons.add, label: 'add', // String 类型 ) ``` --- ## NavigationBar & NavigationRail (自适应布局) ### 响应式布局策略 Google 推荐的响应式布局策略： - **< 600dp**: 使用 `BottomNavigationBar` - **≥ 600dp**: 使用 `NavigationRail` ### 自适应布局实现 ```dart // 步骤 1: 抽象导航目标 class Destination { final IconData icon; final String label; const Destination({required this.icon, required this.label}); } const List destinations = [ Destination(icon: Icons.home, label: 'Home'), Destination(icon: Icons.search, label: 'Search'), Destination(icon: Icons.settings, label: 'Settings'), ]; // 步骤 2: 测量 // 使用 MediaQuery.sizeOf(context) 获取窗口大小 // 或使用 LayoutBuilder 获取约束 // 步骤 3: 分支 Widget build(BuildContext context) { final screenWidth = MediaQuery.sizeOf(context).width; final useNavigationRail = screenWidth >= 600; return useNavigationRail ? _buildNavigationRail() : _buildBottomNavigationBar(); } Widget _buildNavigationRail() { return Scaffold( body: Row( children: [ NavigationRail( selectedIndex: _selectedIndex, onDestinationSelected: (index) { setState(() { _selectedIndex = index; }); }, labelType: NavigationRailLabelType.all, destinations: destinations.map((d) { return NavigationRailDestination( icon: Icon(d.icon), label: Text(d.label), ); }).toList(), ), const VerticalDivider(thickness: 1, width: 1), Expanded(child: _buildContent()), ], ), ); } Widget _buildBottomNavigationBar() { return Scaffold( body: _buildContent(), bottomNavigationBar: NavigationBar( selectedIndex: _selectedIndex, onDestinationSelected: (index) { setState(() { _selectedIndex = index; }); }, destinations: destinations.map((d) { return NavigationDestination( icon: Icon(d.icon), label: d.label, ); }).toList(), ), ); } ``` ### MediaQuery vs LayoutBuilder ```dart // MediaQuery.sizeOf - 获取整个应用窗口大小 // 适用于需要基于整个窗口大小的决策 final size = MediaQuery.sizeOf(context); if (size.width >= 600) { // 使用 NavigationRail } // LayoutBuilder - 获取父 widget 的约束 // 适用于需要基于特定位置约束的决策 LayoutBuilder( builder: (context, constraints) { if (constraints.maxWidth >= 600) { return _buildExpandedLayout(); } return _buildCompactLayout(); }, ) ``` --- ## Drawer ### 基本用法 ```dart Scaffold( appBar: AppBar( title: Text('App'), ), drawer: Drawer( child: ListView( padding: EdgeInsets.zero, children: [ DrawerHeader( decoration: BoxDecoration( color: Theme.of(context).colorScheme.primary, ), child: Text('Drawer Header'), ), ListTile( leading: Icon(Icons.home), title: Text('Home'), onTap: () { Navigator.pop(context); }, ), ListTile( leading: Icon(Icons.settings), title: Text('Settings'), onTap: () { Navigator.pop(context); }, ), ], ), ), ) ``` --- ## NavigationBar (Material 3) ### NavigationBar 主题 ```dart NavigationBar( height: 80, // M3 默认高度 elevation: 3, backgroundColor: Colors.surface, indicatorColor: Colors.secondaryContainer, destinations: const [ NavigationDestination( icon: Icon(Icons.explore_outlined), selectedIcon: Icon(Icons.explore), label: 'Explore', ), NavigationDestination( icon: Icon(Icons.commute_outlined), selectedIcon: Icon(Icons.commute), label: 'Commute', ), NavigationDestination( icon: Icon(Icons.settings_outlined), selectedIcon: Icon(Icons.settings), label: 'Settings', ), ], ) // 全局主题 MaterialApp( theme: ThemeData( navigationBarTheme: NavigationBarThemeData( height: 80, indicatorColor: Colors.secondaryContainer, ), ), ) ``` --- ## NavigationRail (Material 3) ```dart NavigationRail( selectedIndex: _selectedIndex, onDestinationSelected: (index) { setState(() { _selectedIndex = index; }); }, labelType: NavigationRailLabelType.all, // 总是显示标签 // 或 NavigationRailLabelType.selected - 仅选中时显示 // 或 NavigationRailLabelType.none - 从不显示 leading: FloatingActionButton( elevation: 3, child: Icon(Icons.add), onPressed: () { }, ), destinations: const [ NavigationRailDestination( icon: Icon(Icons.explore_outlined), selectedIcon: Icon(Icons.explore), label: Text('Explore'), ), NavigationRailDestination( icon: Icon(Icons.commute_outlined), selectedIcon: Icon(Icons.commute), label: Text('Commute'), ), NavigationRailDestination( icon: Icon(Icons.settings_outlined), selectedIcon: Icon(Icons.settings), label: Text('Settings'), ), ], ) // 与扩展布局结合 Row( children: [ NavigationRail( selectedIndex: _selectedIndex, onDestinationSelected: (index) { setState(() { _selectedIndex = index; }); }, extended: MediaQuery.sizeOf(context).width > 1200, minExtendedWidth: 180, destinations: [...], ), VerticalDivider(thickness: 1, width: 1), Expanded(child: content), ], ) ``` --- ## 通用自适应布局模式 ### 完整示例 ```dart class AdaptiveScaffold extends StatelessWidget { const AdaptiveScaffold({super.key}); @override Widget build(BuildContext context) { return LayoutBuilder( builder: (context, constraints) { // 手机: BottomNavigationBar if (constraints.maxWidth < 600) { return _PhoneLayout(); } // 平板: NavigationRail if (constraints.maxWidth < 1200) { return _TabletLayout(); } // 桌面: 扩展的 NavigationRail return _DesktopLayout(); }, ); } } // 使用 Material Design 布局指南 // https://m3.material.io/foundations/layout/applying-layout/window-size-classes ``` FILE:references/overview-getting-started.md --- name: flutter-overview description: Flutter 开发入门与平台能力总览。 source: https://flutter.cn/docs --- # Flutter 平台能力总览 Flutter 的核心目标是提供一个框架，允许开发者从单一代码库开发出在任何平台上都看起来很棒的应用。这意味着应用可能出现在不同尺寸的屏幕上，从智能手表，到折叠屏双屏手机，再到高清显示器。输入设备可能是物理或虚拟键盘、鼠标、触摸屏或许多其他设备。 ## 1. Adaptive and Responsive Design（自适应与响应式设计） ### 什么是响应式 vs 自适应？简单来说： - **响应式设计**：让 UI **适应** 可用空间 - **自适应设计**：让 UI 在可用空间中**可用** 响应式应用调整设计元素的位置以**适应**可用空间。自适应应用选择适当的布局和输入设备以在可用空间中**可用**。例如，平板电脑 UI 应该使用底部导航还是侧边栏导航？ ### 自适应设计的关键方面 | 主题 | 说明 | |------|------| | [通用方法][general] | 抽象 → 测量 → 分支的三步法 | | [SafeArea & MediaQuery][safearea] | 安全区域和屏幕尺寸查询 | | [大屏幕 & 折叠屏][large-screens] | 适配平板和折叠设备 | | [用户输入 & 无障碍][input] | 触控、鼠标、键盘输入 | | [能力 & 策略][capabilities] | 平台能力检测和策略设计 | | [自适应应用最佳实践][best-practices] | 生产级自适应应用指南 | [general]: /ui/adaptive-responsive/general [safearea]: /ui/adaptive-responsive/safearea-mediaquery [large-screens]: /ui/adaptive-responsive/large-screens [input]: /ui/adaptive-responsive/input [capabilities]: /ui/adaptive-responsive/capabilities [best-practices]: /ui/adaptive-responsive/best-practices ### 自适应应用的三步法 #### Step 1: Abstract（抽象）首先，识别需要动态化的 widgets。分析这些 widgets 的构造函数，抽象出可以共享的数据。常见需要适应性的 widgets： - 对话框（全屏和模态） - 导航 UI（rail 和 bottom bar） - 自定义布局（如"UI 区域更高还是更宽？"） #### Step 2: Measure（测量）有两种方式确定显示区域的大小：`MediaQuery` 和 `LayoutBuilder`。 **MediaQuery**： - `MediaQuery.sizeOf(context)` 返回应用窗口的当前大小 - 返回以逻辑像素为单位的尺寸（密度无关像素） - 当尺寸属性改变时，build 方法会重建 **LayoutBuilder**： - 提供父 Widget 的布局约束 - 返回 `BoxConstraints` 而不是 `Size` 对象 - 提供有效宽度和高度范围（最小和最大） - 适用于需要基于特定 widget 空间而不是整个应用窗口的 sizing 场景 #### Step 3: Branch（分支）决定选择哪个版本 UI 的尺寸断点。例如，Material layout 指南建议： - 窗口宽度小于 600 逻辑像素：使用 bottom nav bar - 窗口宽度 600 像素或更大：使用 nav rail :::note 选择不应取决于设备的**类型**，而应取决于设备的**可用窗口大小**。 ::: --- ## 2. Animations API Overview（动画 API 概览） Flutter 中的动画系统基于 `Animation` 对象。Widgets 可以直接将这些动画合并到自己的 build 方法中来读取它们的当前值或者监听它们的状态变化，或者可以将其作为更复杂动画的基础传递给其他 widgets。 ### Animation 动画系统的首要组成部分是 `Animation` 类。一个动画表现为可在它的生命周期内发生变化的特定类型的值。 #### addListener 每当动画的状态值发生变化时，动画都会通知所有通过 `addListener` 添加的监听器。通常，一个正在监听动画的 `State` 对象会调用自身的 `setState` 方法来通知 widget 系统需要根据新状态值进行重新构建。这种模式非常常见，所以有两个 widgets 可以帮助其他 widgets 在动画改变值时进行重新构建： - `AnimatedWidget`：对于无状态动画 widgets 尤其有用 - `AnimatedBuilder`：对于希望将动画作为复杂 widgets 的 build 方法的其中一部分的情况非常有用 #### addStatusListener 动画还提供了一个 `AnimationStatus`，表示动画将如何随时间进行变化： - `dismissed`：处于变化区间的开始点（值为 0.0） - `forward`：正向运行（从 0.0 到 1.0） - `reverse`：反向运行（从 1.0 到 0.0） - `completed`：到达区间结束点（值为 1.0） ### AnimationController 要创建动画，首先要创建一个 `AnimationController`。除了作为动画本身，`AnimationController` 还可以用来控制动画： - `forward()` / `reverse()`：正向或反向播放 - `stop()`：停止动画 - `fling()`：使用物理模拟（如弹簧）驱动动画 - `repeat()`：重复播放 - `animateTo()`：动画到指定目标 ### Tweens（补间动画）如果想要在 0.0 到 1.0 的区间之外设置动画，可以使用 `Tween`，它可以在它的 `begin` 值和 `end` 值之间进行插值补间。常见 Tween 子类： - `ColorTween`：颜色间插值 - `RectTween`：矩形之间插值两种方法将补间动画与动画组合： 1. 用 `evaluate()` 方法处理动画的当前值 2. 用 `animate()` 方法处理一个动画，返回包含补间动画插值的新 `Animation` ### 动画架构 #### Scheduler（调度器） `SchedulerBinding` 是一个暴露出 Flutter 调度原语的单例类。关键原语是帧回调，每当一帧需要在屏幕上显示时，Flutter 的引擎会触发一个"开始帧"回调。 #### Tickers（运行器） `Ticker` 类挂载在调度器的 `scheduleFrameCallback()` 的机制上来达到每次运行都会触发回调的效果。一个 `Ticker` 可以被启动和停止，启动时返回一个 `Future`。 #### Simulations（模拟器） `Simulation` 抽象类将相对时间值（运行时间）映射为双精度值，并且有完成的概念。不同效果有不同具体实现，如 `BouncingScrollSimulation`、`ClampingScrollSimulation`。 #### Animatables `Animatable` 抽象类将双精度值映射为特定类型的值。`Animatable` 类是无状态和不可变的。 #### Curves（曲线） `Curve` 抽象类将名义范围为 0.0-1.0 的双精度值映射到名义范围为 0.0-1.0 的双精度值。`Curve` 类是无状态和不可变的。 ### 可组合动画 - `CurvedAnimation`：接收父级 `Animation` 和曲线类作为输入 - `ReverseAnimation`：反转动画所有值 - `ProxyAnimation`：仅转发父级的当前状态 - `TrainHoppingAnimation`：在两个父类的值交叉时切换 --- ## 3. Widget, Layout, and Rendering Basics（Widget、布局和渲染基础） ### Flutter 的布局方法在 Flutter 中，一切皆为 widget。布局的基本原则： 1. **识别行和列**：大多数布局是基于 Row 和 Column 2. **识别网格**：使用 GridView 3. **检查重叠元素**：使用 Stack 4. **确定对齐、填充和边框需求** ### 核心布局 Widgets ```dart // Row：水平布局 Row( mainAxisAlignment: MainAxisAlignment.spaceEvenly, children: [/* 子 widgets */], ) // Column：垂直布局 Column( crossAxisAlignment: CrossAxisAlignment.start, children: [/* 子 widgets */], ) // Expanded：填充剩余空间 Expanded( child: Column(/* ... */), ) // Padding：添加间距 Padding( padding: const EdgeInsets.all(32), child: /* content */, ) // 滚动视图 SingleChildScrollView( child: Column( children: [/* 子 widgets */], ), ) ``` ### 构建步骤 1. **创建基础应用**： ```dart void main() => runApp(const MyApp()); class MyApp extends StatelessWidget { const MyApp({super.key}); @override Widget build(BuildContext context) { return MaterialApp( title: 'Flutter layout demo', home: Scaffold( appBar: AppBar(title: const Text(appTitle)), body: const Center(child: Text('Hello World')), ), ); } } ``` 2. **构建可复用 Widgets**： ```dart class TitleSection extends StatelessWidget { const TitleSection({super.key, required this.name, required this.location}); final String name; final String location; @override Widget build(BuildContext context) { return Padding( padding: const EdgeInsets.all(32), child: Row( children: [ Expanded( child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Padding( padding: const EdgeInsets.only(bottom: 8), child: Text(name, style: const TextStyle(fontWeight: FontWeight.bold)), ), Text(location, style: TextStyle(color: Colors.grey[500])), ], ), ), Icon(Icons.star, color: Colors.red[500]), const Text('41'), ], ), ); } } ``` 3. **配置资源**（pubspec.yaml）： ```yaml flutter: uses-material-design: true assets: - images/lake.jpg ``` ### 布局约束传递 Flutter 布局使用约束传递机制： 1. 父 widget 将约束传递给子 widget 2. 子 widget 根据约束决定自己的大小 3. 父 widget 根据子 widget 的大小决定位置 --- ## 4. Platform-Specific Considerations（平台特定注意事项） Flutter 为 Android 和 iOS 提供自动平台适配。 ### 页面导航 | 平台 | 转场动画 | |------|----------| | **Android** | ZoomPageTransitionsBuilder，从下到上的缩放动画 | | **iOS** | Push 转场（end-to-start）和 Present 转场（bottom-up） | **返回导航**： - Android：OS 返回按钮弹出 Navigator 顶部路由 - iOS：边缘滑动手势弹出顶部路由 ### 滚动 | 特性 | Android | iOS | |------|---------|-----| | 物理仿真 | 更多静态摩擦力，快速达到速度，停止突然 | 更多动态摩擦力，逐渐达到高速，停止平滑 | | Overscroll 行为 | 显示 GlowingOverscrollIndicator | 弹簧回弹效果 | | 动量 | 无动量叠加 | 连续滚动速度叠加 | | 返回顶部 | 无 | 点击状态栏滚动到顶 | ### 排版 - Material 包自动根据平台使用对应字体：Android 用 Roboto，iOS 用 San Francisco - Cupertino 包默认使用 San Francisco 字体 ### 图标 - 更多按钮图标：Android 竖直三个点，iOS 横排三个点 - 返回按钮：iOS 简单 V 型，Android V 型加短横线 - 通过 `Icons.adaptive` 提供平台自适应图标 ### 触摸反馈 Material 和 Cupertino 包在特定场景下自动触发符合平台特点的触摸反馈： - Android 长按选中单词触发震动，iOS 不触发 - iOS 滚动选择器触发轻敲音效，Android 不触发 ### 文本编辑 | 行为 | Android (Material) | iOS (Material/Cupertino) | |------|-------------------|--------------------------| | 点击文本框 | 光标移动到点击位置 | 光标移动到点击处最近的单词末尾 | | 长按 | 选中单词，释放显示工具栏 | 光标定位，释放显示工具栏 | | 键盘手势 | 空格键左右滑动移动光标 | 3D Touch 任意方向移动光标 | | 工具栏样式 | Android 风格 | iOS 风格 | --- ## 5. Capabilities & Policies（能力与策略） ### 设计原则根据不同设备的优势和劣势进行设计。Flutter 推荐的模式是创建一组 `Capability` 和 `Policy` 类。 ### Capabilities（能力）定义代码或设备**能**做什么： - API 的存在性 - OS 强制的限制 - 物理硬件要求（如相机） ### Policies（策略）定义代码**应该**做什么： - 应用商店指南 - 设计偏好 - 需要引用主机设备的资源或文案 - 服务器端启用的功能 ### 最佳实践 **避免使用 `Platform.isAndroid` 等函数来做布局决策**，而是描述你想要分支的内容： ```dart // 推荐：基于行为的抽象 class Policy { bool shouldAllowPurchaseClick() { // 被 Apple App Store 指南禁止 return !Platform.isIOS; } } // 使用 TextSpan( text: 'Buy in browser', recognizer: shouldAllowPurchaseClick ? TapGestureRecognizer()..onTap = () { launch(''); } : null, ) ``` 这样做的优势： - 代码更清晰地表达分支原因 - 便于测试（可以 mock Policy 类） - 当需求变化时，不需要修改使用处的代码 ### 策略实现方式 | 类型 | 适用场景 | |------|----------| | 编译时检查 | 偏好不太可能改变，错误更改后果严重 | | 运行时检查 | 确定是否有触屏等运行时特性 | | RPC 后端检查 | 增量功能发布或可能改变的决策 | FILE:references/platform-idioms.md --- name: flutter-platform-idioms description: Flutter 设备 idiom 检测与平台特定 UI 模式完整参考。 source: https://flutter.cn/docs --- # Flutter 设备形态与平台特定模式本文档涵盖设备形态（idiom）检测策略、平台特定 UI 模式、输入设备适配以及跨平台最佳实践。 ## 核心原则：按窗口尺寸，而非设备类型 ```dart // 错误：根据设备类型判断 if (device == 'tablet') { ... } // 正确：根据窗口可用空间判断 if (MediaQuery.sizeOf(context).width >= 600) { ... } ``` Flutter 应用可能在以下环境中运行：桌面可调整窗口、平板多窗口模式、画中画等。窗口尺寸与设备类型并非强关联。 ## 平台倡导者（Platform Advocate）每个目标平台应指定一名**倡导者**（不一定是开发者，可以是设计师、测试人员）： - 日常使用该平台，能发现平台特定的不一致 - 及时反馈 UI/UX 问题 - 例：macOS+iOS 一个倡导者，Windows+Android 一个倡导者 ## 滚动条样式桌面用户期望滚动条始终可见、可点击拖动；移动用户期望滚动条仅在滚动时短暂出现。 ```dart // 平台自适应滚动条 return Scrollbar( thumbVisibility: DeviceType.isDesktop, // 仅桌面始终显示 controller: _scrollController, child: GridView.count( controller: _scrollController, padding: const EdgeInsets.all(Insets.extraLarge), childAspectRatio: 1, crossAxisCount: colCount, children: listChildren, ), ); ``` ## 多选交互 ### 平台感知多选修饰键 ```dart static bool get isMultiSelectModifierDown { bool isDown = false; if (Platform.isMacOS) { isDown = isKeyDown({ LogicalKeyboardKey.metaLeft, LogicalKeyboardKey.metaRight, }); } else { isDown = isKeyDown({ LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.controlRight, }); } return isDown; } // 范围选择（Shift+点击） static bool get isSpanSelectModifierDown => isKeyDown({LogicalKeyboardKey.shiftLeft, LogicalKeyboardKey.shiftRight}); ``` ### 触摸设备多选触摸设备多选通常简化为单次点击选择/取消选择，配合 "Select All" / "Clear" 按钮。 ### 全选快捷键桌面列表应支持 `Control+A` 全选。 ## 文本选择桌面和 Web 用户期望大多数文本可鼠标选中。使用 [`SelectableText`][] 组件： ```dart // 普通文本 return const SelectableText('Select me!'); // 富文本 return const SelectableText.rich( TextSpan( children: [ TextSpan(text: 'Hello'), TextSpan( text: 'Bold', style: TextStyle(fontWeight: FontWeight.bold), ), ], ), ); ``` [`SelectableText`]: {{site.api}}/flutter/material/SelectableText-class.html ## 标题栏（Title Bar）桌面应用可自定义标题栏以增强品牌或节省垂直空间。使用 [`bits_dojo`][] 包替换原生标题栏： ```dart // bits_dojo 允许用纯 Flutter widget 构建标题栏 import 'package:bitsdojo_window/bitsdojo_window.dart'; @override Widget build(BuildContext context) { return WindowTitleBarBox( child: Row( children: [ Expanded(child: MoveWindow(child: myTitleBarContent)), WindowButtons(), ], ), ); } ``` [`bits_dojo`]: {{site.github}}/bitsdojo/bitsdojo_window > 注意：Windows 和 Linux 上自定义标题栏会替换原生标题栏，导致集成菜单栏丢失。可在 Flutter 内实现自定义菜单栏作为替代。 ## 上下文菜单、工具提示、弹出面板 | 类型 | 触发方式 | 定位锚点 | 消失方式 | |---|---|---|---| | **上下文菜单** | 右键点击 | 鼠标位置 | 点击外部/选择菜单项 | | **工具提示** | 悬停 200-400ms | widget | 鼠标离开 widget | | **弹出面板 (Flyout)** | 点击 | widget | 点击外部/关闭按钮 | ```dart // 工具提示 return const Tooltip( message: 'I am a Tooltip', child: Text('Hover over the text to show a tooltip.'), ); ``` 第三方包推荐：`context_menus`、`anchored_popups`、`flutter_portal`、`super_tooltip`、`custom_pop_up_menu`。 ## 按钮水平顺序 Windows：确认按钮在左；其他平台：确认按钮在右。 ```dart TextDirection btnDirection = DeviceType.isWindows ? TextDirection.rtl : TextDirection.ltr; Row( children: [ const Spacer(), Row( textDirection: btnDirection, children: [ DialogButton( label: 'Cancel', onPressed: () => Navigator.pop(context, false), ), DialogButton( label: 'Ok', onPressed: () => Navigator.pop(context, true), ), ], ), ], ); ``` ## 拖放交互 | 输入类型 | 期望行为 | |---|---| | 触摸 | 需要可见拖动手柄，或通过长按启动拖动（滚动和拖动共用同一手指） | | 鼠标 | 无需手柄，选中即可拖动（滚轮/滚动条负责滚动） | Flutter 实现方式： - [`Draggable`][] + [`DragTarget`][] API - `onPan` 手势事件自行处理 - pub.dev 上的预制列表包 [`Draggable`]: {{site.api}}/flutter/widgets/Draggable-class.html [`DragTarget`]: {{site.api}}/flutter/widgets/DragTarget-class.html --- ## 键盘导航与快捷键 ### FocusableActionDetector 组合 focus、鼠标输入、快捷键的 widget： ```dart class _BasicActionDetectorState extends State { bool _hasFocus = false; @override Widget build(BuildContext context) { return FocusableActionDetector( onFocusChange: (value) => setState(() => _hasFocus = value), actions: >{ ActivateIntent: CallbackAction( onInvoke: (intent) { print('Enter or Space was pressed!'); return null; }, ), }, child: Stack( clipBehavior: Clip.none, children: [ const FlutterLogo(size: 100), if (_hasFocus) Positioned( left: -4, top: -4, bottom: -4, right: -4, child: _roundedBorder(), ), ], ), ); } } ``` ### 遍历顺序控制使用 `FocusTraversalGroup` 控制 Tab 焦点顺序： ```dart Column( children: [ FocusTraversalGroup(child: MyFormWithMultipleColumnsAndRows()), SubmitButton(), ], ); ``` ### 全局键盘快捷键 ```dart // 定义 Intent 和 Action class CreateNewItemIntent extends Intent { const CreateNewItemIntent(); } @override void initState() { super.initState(); HardwareKeyboard.instance.addHandler(_handleKey); } @override void dispose() { HardwareKeyboard.instance.removeHandler(_handleKey); super.dispose(); } bool _handleKey(KeyEvent event) { bool isShiftDown = isKeyDown({ LogicalKeyboardKey.shiftLeft, LogicalKeyboardKey.shiftRight, }); if (isShiftDown && event.logicalKey == LogicalKeyboardKey.keyN) { _createNewItem(); return true; } return false; } ``` ```dart // Shortcuts widget（局部快捷键） Widget build(BuildContext context) { return Shortcuts( shortcuts: const { SingleActivator(LogicalKeyboardKey.keyN, control: true): CreateNewItemIntent(), }, child: Actions( actions: >{ CreateNewItemIntent: CallbackAction( onInvoke: (intent) => _createNewItem(), ), }, child: Focus(autofocus: true, child: Container()), ), ); } ``` ## 鼠标交互 ### 自定义光标 ```dart return MouseRegion( cursor: SystemMouseCursors.click, onTap: () { Focus.of(context).requestFocus(); _submit(); }, child: Logo(showBorder: hasFocus), ); ``` ### 悬停效果 ```dart return MouseRegion( onEnter: (_) => setState(() => _isMouseOver = true), onExit: (_) => setState(() => _isMouseOver = false), onHover: (e) => print(e.localPosition), child: Container( height: 500, color: _isMouseOver ? Colors.blue : Colors.black, ), ); ``` ## 视觉密度（Visual Density） `VisualDensity` 调整整个应用的交互密度——触摸设备需要更大点击区域，桌面可以更紧凑。 ```dart double densityAmt = touchMode ? 0.0 : -1.0; // 触摸:标准密度，桌面:紧凑 VisualDensity density = VisualDensity( horizontal: densityAmt, vertical: densityAmt, ); return MaterialApp( theme: ThemeData(visualDensity: density), home: MainAppScaffold(), ); // 1 density unit ≈ 6 logical pixels ``` ## 设计注意事项 | 建议 | 说明 | |---|---| | 优先触摸体验 | 先构建出色的触摸 UI，再为鼠标用户优化密度 | | 不要锁定屏幕方向 | 应用应能适应不同大小和形状的窗口 | | 不要根据设备类型判断布局 | 根据窗口可用空间决定 | | 不要占用全部水平空间 | 使用 `GridView` 或 `ConstrainedBox` 限制最大宽度 | | 保持列表滚动状态 | 方向改变时使用 `PageStorageKey` 恢复滚动位置 | | 支持多种输入设备 | 鼠标、触控板、键盘快捷键、辅助功能 | FILE:references/staggered-animations.md --- name: flutter-staggered-animation description: Flutter 交织动画实现参考。 source: https://flutter.cn/docs --- # 交织动画 (Staggered Animations) 交织动画由一系列顺序执行或重叠执行的动画组成，每个动画控制不同的属性。 ## 核心概念 ### 什么是交织动画 - **顺序动画**：一个动画完成后另一个开始 - **重叠动画**：多个动画同时进行 - **间隔**：动画可能在时间轴上有间隙 ### 关键组件 1. **`AnimationController`**：一个控制器管理所有动画 2. **`Interval`**：定义每个动画在时间轴上的起止点（0.0-1.0） 3. **`Tween`**：定义每个属性的起始和结束值 4. **`CurvedAnimation`**：为动画添加缓动曲线 ## 代码示例 ### 完整交织动画结构 ```dart import 'package:flutter/material.dart'; void main() => runApp(const MyApp()); class MyApp extends StatelessWidget { const MyApp({super.key}); @override Widget build(BuildContext context) { return MaterialApp( title: 'Staggered Animation', home: const StaggerDemo(), ); } } /// 有状态 widget：创建 AnimationController class StaggerDemo extends StatefulWidget { const StaggerDemo({super.key}); @override State createState() => _StaggerDemoState(); } class _StaggerDemoState extends State with TickerProviderStateMixin { late AnimationController _controller; @override void initState() { super.initState(); _controller = AnimationController( duration: const Duration(milliseconds: 2000), vsync: this, ); } @override void dispose() { _controller.dispose(); super.dispose(); } Future _playAnimation() async { try { await _controller.forward().orCancel; await _controller.reverse().orCancel; } on TickerCanceled { // 动画被取消，可能是因为 widget 被 dispose 了 } } @override Widget build(BuildContext context) { timeDilation = 10.0; // 减慢动画便于观察 return Scaffold( appBar: AppBar(title: const Text('Staggered Animation')), body: GestureDetector( behavior: HitTestBehavior.opaque, onTap: _playAnimation, child: Center( child: Container( width: 300, height: 300, decoration: BoxDecoration( color: Colors.black.withAlpha(25), border: Border.all(color: Colors.black.withAlpha(128)), ), child: StaggerAnimation(controller: _controller.view), ), ), ), ); } } /// 无状态 widget：定义 Tween 和 Animation 对象 class StaggerAnimation extends StatelessWidget { const StaggerAnimation({ super.key, required this.controller, }) : opacity = Tween( begin: 0.0, end: 1.0, ).animate( CurvedAnimation( parent: controller, curve: const Interval(0.0, 0.100, curve: Curves.ease), ), ), width = Tween( begin: 50.0, end: 150.0, ).animate( CurvedAnimation( parent: controller, curve: const Interval(0.125, 0.250, curve: Curves.ease), ), ), height = Tween( begin: 50.0, end: 150.0, ).animate( CurvedAnimation( parent: controller, curve: const Interval(0.250, 0.375, curve: Curves.ease), ), ), padding = Tween( begin: const EdgeInsets.only(bottom: 0), end: const EdgeInsets.only(bottom: 100), ).animate( CurvedAnimation( parent: controller, curve: const Interval(0.250, 0.375, curve: Curves.ease), ), ), borderRadius = BorderRadiusTween( begin: BorderRadius.circular(4), end: BorderRadius.circular(75), ).animate( CurvedAnimation( parent: controller, curve: const Interval(0.375, 0.500, curve: Curves.ease), ), ), color = ColorTween( begin: Colors.blue, end: Colors.orange, ).animate( CurvedAnimation( parent: controller, curve: const Interval(0.500, 0.750, curve: Curves.ease), ), ); final AnimationController controller; final Animation opacity; final Animation width; final Animation height; final Animation padding; final Animation borderRadius; final Animation color; @override Widget build(BuildContext context) { return AnimatedBuilder( builder: _buildAnimation, animation: controller, ); } Widget _buildAnimation(BuildContext context, Widget? child) { return Container( padding: padding.value, alignment: Alignment.bottomCenter, child: Opacity( opacity: opacity.value, child: Container( width: width.value, height: height.value, decoration: BoxDecoration( color: color.value, border: Border.all(color: Colors.indigo[300]!, width: 3), borderRadius: borderRadius.value, ), ), ), ); } } ``` ### 动画时序图 ``` 时间轴: 0.0 0.1 0.2 0.3 0.4 0.5 0.7 1.0 |------|------|------|------|------|------|------| 不透明度 ████████ 宽度 ████████████ 高度 ████████████ 填充 ████████████ 圆角 ████████████ 颜色 ████████████████ ``` ### 使用 Interval 控制动画时段 ```dart // 基础 Interval 用法 CurvedAnimation( parent: controller, curve: const Interval(0.0, 0.5), // 0% - 50% 的时间段 ) // 带 curve 的 Interval CurvedAnimation( parent: controller, curve: const Interval(0.25, 0.75, curve: Curves.easeInOut), ) // 常用 Curves Curves.linear // 匀速 Curves.ease // 开始慢，结束慢 Curves.easeIn // 开始慢 Curves.easeOut // 结束慢 Curves.easeInOut // 开始和结束都慢 Curves.bounceOut // 弹跳效果 Curves.elasticOut // 弹性效果 ``` ## 关键模式 ### 分离有状态和无状态 widget ```dart // 有状态 widget：管理 AnimationController class MyStatefulWidget extends StatefulWidget { @override State createState() => _MyStatefulWidgetState(); } class _MyStatefulWidgetState extends State with TickerProviderStateMixin { late AnimationController _controller; @override void initState() { super.initState(); _controller = AnimationController( duration: Duration, vsync: this, ); } // 播放动画 Future _play() async { await _controller.forward(); // 或反向播放 // await _controller.reverse(); // 或重复 // _controller.repeat(); } @override Widget build(BuildContext context) { return MyAnimationWidget(controller: _controller); } } // 无状态 widget：定义 Tween 和 build 方法 class MyAnimationWidget extends StatelessWidget { const MyAnimationWidget({super.key, required this.controller}); final AnimationController controller; // 在这里定义所有 Tween late final Animation _myAnimation = Tween( begin: 0, end: 100, ).animate(CurvedAnimation( parent: controller, curve: const Interval(0.0, 0.5), )); @override Widget build(BuildContext context) { return AnimatedBuilder( animation: controller, builder: (context, child) { return Container( width: _myAnimation.value, height: _myAnimation.value, // ... ); }, ); } } ``` ## 常见用法 ### 同时播放多个动画 ```dart // 多个 Tween 共享同一个 Interval width: Tween(begin: 50.0, end: 150.0).animate( CurvedAnimation(parent: controller, curve: Interval(0.0, 0.5)), ), height: Tween(begin: 50.0, end: 150.0).animate( CurvedAnimation(parent: controller, curve: Interval(0.0, 0.5)), // 重叠 ), ``` ### 错开开始时间 ```dart // width 从 25% 开始 width: Tween(begin: 50.0, end: 150.0).animate( CurvedAnimation(parent: controller, curve: Interval(0.25, 0.5)), ), // height 从 50% 开始 height: Tween(begin: 50.0, end: 150.0).animate( CurvedAnimation(parent: controller, curve: Interval(0.5, 0.75)), ), ``` ### 反向播放动画 ```dart await _controller.forward().orCancel; // 正向 await _controller.reverse().orCancel; // 反向 // 或设置状态自动反向 controller.addStatusListener((status) { if (status == AnimationStatus.completed) { controller.reverse(); } else if (status == AnimationStatus.dismissed) { controller.forward(); } }); ``` FILE:references/testing.md # Flutter 测试指南 > 来源：Flutter 官方文档 — Testing Flutter apps > URL: https://flutter.cn/docs/testing > 版本：Flutter 3.x > 抓取时间：2026-04-24 --- ## 单元测试（flutter_test） ```dart // 待测试的业务代码 class CounterModel extends ChangeNotifier { int _count = 0; int get count => _count; void increment() { _count++; notifyListeners(); } } // 测试 test('CounterModel increments correctly', () { final model = CounterModel(); expect(model.count, 0); model.increment(); expect(model.count, 1); model.increment(); expect(model.count, 2); }); ``` ## Widget 测试 ```dart // 测试 StatefulWidget testWidgets('CounterWidget displays count and increments', (tester) async { await tester.pumpWidget( MaterialApp( home: CounterWidget(), // 使用 CounterModel 的 Widget ), ); expect(find.text('0'), findsOneWidget); expect(find.text('1'), findsNothing); await tester.tap(find.byIcon(Icons.add)); await tester.pump(); expect(find.text('1'), findsOneWidget); }); ``` ## Riverpod Provider 测试 ```dart // 使用 ProviderScope 隔离测试 testProvider('counterProvider increments', (override) async { await runProviderScope((ref) async { final counter = ref.watch(counterProvider); expect(counter, 0); ref.read(counterProvider.notifier).increment(); final newCounter = ref.watch(counterProvider); expect(newCounter, 1); }, overrides: []); }); ``` ## 集成测试（flutter_driver） ```dart // pubspec.yaml 添加 flutter_driver 依赖 // 测试文件 setUpAll(() async { await FlutterDriver.connect(); }); test('app loads and shows home', () async { final driver = await FlutterDriver.connect(); await driver.waitFor(find.byType('MyHomePage')); expect(find.text('Home'), findsOneWidget); }); ``` ## Mock 与依赖注入 ```dart // 使用 mockito 生成 mock @GenerateMocks([UserRepository]) void main() { late MockUserRepository mockRepo; setUp(() { mockRepo = MockUserRepository(); }); test('loads user data', () async { when(mockRepo.getUser('123')) .thenAnswer((_) async => User(id: '123', name: 'Alice')); final user = await mockRepo.getUser('123'); expect(user.name, 'Alice'); verify(mockRepo.getUser('123')).called(1); }); } ``` ## 测试金字塔 | 层级 | 工具 | 覆盖内容 | |------|------|---------| | 单元测试 | `flutter_test` | 纯 Dart 类、业务逻辑 | | Widget 测试 | `flutter_test` | 单个 Widget 渲染和交互 | | 集成测试 | `flutter_driver` / `integration_test` | 多 Widget 协作、真实环境 | ## 来源 - [Flutter 测试官方文档](https://flutter.cn/docs/testing) - [Widget 测试指南](https://flutter.cn/docs/testing/widget-testing) - [Riverpod 测试](https://riverpod.dev/docs/essentials/testing)

Flutter Dev Skill

Comments (0)