flutter-sdk-changelog

Flutter SDK 变更日志与 Widget 迁移指南（Flutter 1.0 至现代 Flutter）

本技能为 Flutter 框架版本、Widget 弃用、API 替换、Material 3 设计迁移、独立的 material_ui 和 cupertino_ui 包的解耦，以及旧版 Flutter 代码库的修复手册，提供权威且结构化的参考资料。

---

🎯 Flutter Widget 与 API 快速替换一览

已弃用／过时的 API	引入／弃用版本	现代替代方案	参考资料
Color.withOpacity(o)	在 Flutter 3.22 中弃用	Color.withValues(alpha: o)	Widget 弃用项
MaterialState / MaterialStateProperty	在 Flutter 3.22 中弃用	WidgetState / WidgetStateProperty	Widget 弃用项
WillPopScope	在 Flutter 3.12+ 中弃用	PopScope(canPop: ..., onPopInvokedWithResult: ...)	Widget 弃用项
FlatButton、RaisedButton、OutlineButton	在 Flutter 2.0 中弃用	TextButton、ElevatedButton、OutlinedButton	Widget 弃用项
TextTheme.headline1...6、bodyText1/2	在 Flutter 3.7+ 中弃用	displayLarge...small、bodyLarge/Medium	Widget 弃用项
ThemeData.accentColor	在 Flutter 2.5+ 中弃用	ColorScheme.secondary	Widget 弃用项
Scaffold.of(context).showSnackBar()	在 Flutter 2.0 中弃用	ScaffoldMessenger.of(context).showSnackBar()	Widget 弃用项
package:flutter/material.dart	单体式 Flutter SDK	package:material_ui/material_ui.dart	Material 与 Cupertino 迁移
package:flutter/cupertino.dart	单体式 Flutter SDK	package:cupertino_ui/cupertino_ui.dart	Material 与 Cupertino 迁移
BottomNavigationBar	旧版 M2 导航	NavigationBar（Material 3）	Material 3 指南
ToggleButtons	旧版 M2 切换控件	SegmentedButton<T>（Material 3）	Material 3 指南
describeEnum(e)	在 Flutter 3.47 中移除	e.name（Dart 2.15+ 原生属性）	Widget 弃用项
ReorderableListView.onReorder	在 Flutter 3.44 中弃用	onReorderWithOldAndNewIndex	Widget 弃用项
PopupMenuButton	旧版弹出菜单	MenuAnchor / SubmenuButton	Material 3 指南

---

⚡ 子技能速览

子技能：独立 material_ui 与 cupertino_ui 包迁移

• 解耦架构：从单体式框架设计库迁移到独立发布节奏的独立 pub 包。
• 自动修复：运行 dart fix --apply --code=migrate_design_widgets，自动更新导入项和依赖项。
• 无头核心支持：直接基于 package:flutter/widgets.dart 构建完全自定义的设计系统。 👉 阅读完整的Material 与 Cupertino UI 迁移指南。

子技能：组件弃用与现代化

• 预测性返回导航：将 WillPopScope 替换为 PopScope，让 Android 14+ 和 iOS 上的预测性返回手势流畅无卡顿。
• 广色域颜色：将 withOpacity 替换为 withValues(alpha: ...)，避免 8 位精度损失和颜色裁切。
• 统一状态管理：将 MaterialState 替换为通用的 WidgetState。 👉 阅读完整的 组件弃用与替换指南。

子技能：从 Material 2 迁移到 Material 3

• 基于种子的主题配置：使用 ColorScheme.fromSeed(seedColor: ...) 生成色调调色板。
• 组件现代化：将 BottomNavigationBar 迁移为 NavigationBar，将 ToggleButtons 迁移为 SegmentedButton，并将 M2 按钮迁移为 FilledButton。 👉 阅读完整的 Material 2 到 Material 3 指南。

子技能：拯救旧版 Flutter 应用（Flutter 1.x / 2.x 升级到现代 3.x）

• 5 阶段升级流程：基线工具链检查 → 空安全过渡 → 组件弃用修复 → Material 3 更新 → 现代状态管理与路由。 👉 阅读完整的 旧版 Flutter 应用拯救操作手册。

---

📚 目录与参考资料归档

文档	重点领域	描述
material-ui-and-cupertino-ui-migration.md	包解耦	从 SDK 内置的 material/cupertino 迁移到独立的 material_ui 和 cupertino_ui 的完整操作手册。
flutter-to-dart-version-matrix.md	版本映射	Flutter 1.0–3.49+ 与捆绑的 Dart SDK 及引擎里程碑的完整映射。
widget-deprecations-and-replacements.md	组件词典	所有已弃用 Flutter 组件和属性的变更前后代码示例。
material-2-to-material-3-guide.md	UI 与主题配置	全面的 Material 3 迁移指南、动态配色方案和新组件。
rescuing-legacy-flutter-apps.md	升级操作手册	通过 5 阶段结构化操作手册，将旧版 Flutter 应用逐步升级到现代 Flutter。

---

🛠️ 推荐操作手册

1. 迁移到独立的 material_ui 和 cupertino_ui

1. 执行 dart fix --apply --code=migrate_design_widgets 以重写导入语句。
2. 确认 pubspec.yaml 依赖项包含 material_ui 和 cupertino_ui。
3. 查阅 Material 与 Cupertino UI 迁移指南，了解本地化更新和无头架构。

2. 迁移已弃用的组件和属性

1. 找出已弃用的组件或属性（例如 WillPopScope、Color.withOpacity、MaterialStateProperty）。
2. 查阅 组件弃用指南。
3. 将其替换为现代声明式对应项（例如 PopScope、Color.withValues(alpha: ...)、WidgetStateProperty）。

3. 迁移到 Material 3

1. 阅读 Material 2 到 Material 3 指南。
2. 使用 ColorScheme.fromSeed(seedColor: ...) 配置 ThemeData。
3. 替换旧版导航栏（BottomNavigationBar → NavigationBar）和控件（ToggleButtons → SegmentedButton）。

4. 升级 / 拯救旧版 Flutter 应用

1. 从 pubspec.yaml 的 environment 部分确定当前 Flutter 和 Dart 版本。
2. 按照 旧版 Flutter 应用拯救操作手册中的 5 阶段流程操作：
   • 检查工具链 → Sound Null Safety 过渡 → 组件弃用处理 → Material 3 主题 → 现代路由与响应式状态。

5. 回答“Flutter X.Y 有哪些新变化”

1. 在 Flutter 与 Dart 版本对照表 中匹配 Flutter 版本。
2. 说明随附的 Dart SDK 版本、框架的重要里程碑和引擎更新。