freeCodeCamp.org ·

如何在Flutter中处理Material和Cupertino解耦[完整手册]

💡 原文英文，约6000词，阅读约需22分钟。

📝

内容提要

Flutter 3.47将Material和Cupertino设计库从SDK核心分离为独立包material_ui和cupertino_ui，提供自动迁移工具和兼容桥。旧导入将在2026年11月弃用，2027年移除。迁移仅需更改导入路径，API不变，本地化配置简化。建议尽早迁移，并注意依赖兼容和版本管理。

🔎

延伸解读

迁移本质：仅改导入路径，API不变

文章强调，从旧导入切换到material_ui和cupertino_ui，唯一变化是import语句，所有组件名称、参数和行为完全一致。这意味着迁移风险极低，只需确保依赖正确添加，即可通过自动化工具快速完成。

兼容桥：过渡期的关键工具

当第三方依赖尚未迁移时，MaterialUiCompatibilityBridge允许新旧Material组件共存，避免运行时错误。但它是临时方案，应在依赖全部迁移后移除。定期运行flutter pub outdated检查依赖状态，及时清理。

本地化配置简化

新方案中，GlobalMaterialLocalizations.delegates一个getter即可提供所有本地化委托，无需再单独导入flutter_localizations。迁移后应移除该依赖，减少冗余，但注意它本身并未废弃，只是不再需要。

时间线紧迫：2026年11月前迁移最佳

旧导入将在2026年11月正式弃用，2027年移除。尽早迁移可避免弃用警告和紧急修复，同时享受更快的更新节奏。建议在CI中固定版本，确保构建可复现。

❓

Q&A

Flutter 3.47 中 Material 和 Cupertino 解耦是什么意思？

Flutter 3.47 将 Material 和 Cupertino 设计库从 SDK 核心分离为独立的 pub.dev 包：material_ui 和 cupertino_ui。它们可以独立于 Flutter SDK 进行版本更新和发布，使得 Material 和 Cupertino 组件能够更快地迭代，同时让 Flutter 核心更加模块化。

为什么 Flutter 团队要将 Material 和 Cupertino 从 SDK 中解耦？

主要原因有三个：1) 加快 Material 和 Cupertino 的更新速度，不再受限于 SDK 的季度发布周期；2) 降低社区贡献者修改核心 SDK 代码的门槛，促进组件改进；3) 让使用自定义设计系统的团队不必再依赖 Material 和 Cupertino，使 Flutter 核心更加风格中立。

如何将现有的 Flutter 项目迁移到新的 material_ui 和 cupertino_ui 包？

迁移主要分为自动和手动两种方式。自动迁移：运行 `dart fix --apply --code=migrate_design_widgets`，该工具会自动更新导入语句和 pubspec.yaml。如果 pubspec.yaml 未更新，需手动运行 `flutter pub add material_ui` 和 `flutter pub add cupertino_ui`，然后再运行 `dart fix --apply`。最后用 `flutter analyze` 验证。手动迁移适用于自动工具无法处理的特殊情况，如混合导入、条件导入和生成文件。

迁移到 material_ui 后，本地化配置有什么变化？

迁移后，不再需要单独导入 flutter_localizations 包。只需使用 `GlobalMaterialLocalizations.delegates` 这个 getter，它会自动包含 Material、Cupertino 和 Widgets 三个本地化委托，简化了配置。

MaterialUiCompatibilityBridge 的作用是什么？什么时候需要使用它？

MaterialUiCompatibilityBridge 是一个兼容层，用于在应用同时使用新包 material_ui 和旧包 flutter/material.dart 时，避免运行时错误。当你的项目依赖中还有未迁移到 material_ui 的包时，就需要使用它。如果所有依赖都已迁移，则无需使用。

旧的 package:flutter/material.dart 导入什么时候会被弃用和移除？

旧的导入将在 2026 年 11 月的 Flutter 稳定版中正式弃用，届时会产生弃用警告。移除将在 2027 年的某个未来版本中进行，届时未迁移的项目将无法编译。

作为包作者，迁移到 material_ui 时需要注意什么？

包作者应将迁移视为重大版本更新，将包的主版本号提升（例如从 1.5.0 到 2.0.0），并在 pubspec.yaml 中添加对 material_ui 的依赖。同时，可以利用条件导出保持向后兼容，但 Flutter 团队建议直接迁移并让用户自行升级。

Flutter 3.47 除了解耦之外还有哪些重要变化？

其他变化包括：Impeller 渲染引擎在桌面端默认启用；最低支持的 iOS 版本提升到 15，macOS 提升到 12；iOS 强制要求使用 UIScene 生命周期；Widget Previews 转为稳定版；WebAssembly 支持更接近默认。

🏷️