在Flutter中如何实现材料组件与Cupertino设计风格的解耦[完整指南]

唯一不同的地方就是代码顶部的导入语句。这是有意为之的。Flutter团队的目标就是确保这次迁移仅仅涉及导入语句的修改，而不会对任何组件API造成任何影响。

使用Cupertino样式构建的界面

修改前的代码
import 'package:flutter Cupertino.dart';

class SettingsScreen extends StatelessWidget {
  const SettingsScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return CupertinoPageScaffold(
      navigationBar: const CupertinoNavigationBar(
        middle: Text('设置'),
      ),
      child: SafeArea(
        child: CupertinoListSection.insetGrouped(
          children: [
            CupertinoListTile(
              title: const Text('通知'),
              leading: const Icon(CupertinoIcons.bell),
              trailing: CupertinoSwitch(
                value: true,
                onChanged: (value) {},
              ),
            ),
          ],
        ),
      ),
    );
  }
}

// 修改前的代码
import 'package:cupertino_ui Cupertino_ui.dart';

class SettingsScreen extends StatelessWidget {
  const SettingsScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return CupertinoPageScaffold(
      navigationBar: const CupertinoNavigationBar(
        middle: Text('设置'),
      ),
      child: SafeArea(
        child: CupertinoListSection.insetGrouped(
          children: [
            CupertinoListTile(
              title: const Text('通知'),
              leading: const Icon(CupertinoIcons.bell),
              trailing: CupertinoSwitch(
                value: true,
                onChanged: (value) {},
              ),
            ),
          ],
        ),
      ),
    );
  }
}

情况还是一样的。CupertinoPageScaffold、CupertinoNavigationBar、CupertinoListSection、CupertinoListTile、CupertinoSwitch以及CupertinoIcons这些组件都可以从package:cupertino_ui Cupertino_ui.dart中导入，和使用方式与从package:flutter/cupertino.dart中导入时完全相同。只需要修改一行导入语句，其他代码部分根本不需要进行任何更改。

同时使用Material和Cupertino设计风格的应用程序

有些应用程序会混合使用不同的设计风格。一种常见的做法是在主要以Material风格设计的应用程序中，使用Cupertino提供的对话框和选择器组件。这两个库可以同时被导入到同一个项目中，而且不会导致任何冲突：

// 修改前的代码
import 'package:flutter/material.dart';
import 'packageflutter Cupertino.dart';

class DatePickerButton extends StatelessWidget {
  const DatePickerButton({super.key});

  void _showDatePicker(BuildContext context) {
    showCupertinoModalPopup(
      context: context,
      builder: (context) => Container(
        height: 216,
        color: CupertinoColors.systemBackground,
        child: CupertinoDatePicker(
          mode: CupertinoDatePickerMode.date,
          onDateTimeChanged: (DateTime newDate) {},
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => _showDatePicker(context),
      child: const Text('选择日期'),
    );
  }
}

// 修改后的代码：同时导入了两个包
import 'package:material_ui/material-ui.dart';
import 'package:cupertino/ui Cupertino_ui.dart';

class DatePickerButton extends StatelessWidget {
  const DatePickerButton({super.key});

  void _showDatePicker(BuildContext context) {
    showCupertinoModalPopup(
      context: context,
      builder: (context) => Container(
        height: 216,
        color: CupertinoColors.systemBackground,
        child: CupertinoDatePicker(
          mode: CupertinoPickerMode.date,
          onDateTimeChanged: (DateTime newDate) {},
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => _showDatePicker(context),
      child: const Text('选择日期'),
    );
  }
}

material-ui和cupertino_ui都可以在同一文件中被导入，而不会引发任何命名空间冲突。需要注意的是，material-ui在内部就已经依赖于cupertino_ui，因此在实际使用中，你可能会发现大多数文件并不需要显式导入cupertino_ui——因为通过导入material-ui，就可以使用Cupertino相关的组件。不过，如果同时显式导入这两个库，会更清楚地体现你的意图，对于那些需要同时使用这两种系统中的组件的文件来说，这也是推荐的做法。

迁移包的作者信息

如果你维护的是一个Flutter包（而不仅仅是一个Flutter应用程序），那么在进行迁移时还需要考虑一些额外的因素。Flutter团队明确指出：将包转换为独立发布的形式应被视为该包的一次重大版本更新。

作为包的作者应该怎么做

# 迁移之前的包的pubspec.yaml文件
name: myflutter_package
version: 1.5.0
dependencies:
  flutter:
    sdk: flutter

# 迁移之后的包的pubspec.yaml文件
name: myflutter_package
version: 2.0.0
dependencies:
  flutter:
    sdk: flutter
  material_ui: ^1.0.0

将版本号升级到2.0.0是必要的，因为这一变更会对使用你的包的用户产生影响。在之前的版本中，用户在使用你的包时并不需要单独导入material-ui（因为它已经包含在了你的包中）；而迁移后的版本中，你的包明确声明了对material_ui的依赖，这就改变了你的包的依赖关系结构。因此，那些将包升级到2.0.0的用户也需要确保他们的系统中已经安装了material-ui，而如果他们也在同时进行迁移的话，这个问题自然就会得到解决。通过将版本号中的主版本号提高，可以清晰地传达这一变更信息。

在过渡期间保持向后兼容性

如果你希望在过渡期（2026年11月之前）同时支持旧版本的Flutter环境和新版本的Flutter环境，你可以使用Dart中的条件导入功能：

// lib/src/widgets.dart文件
// 这是一个用于处理条件导入的内部文件
export 'package:material_ui/material_ui.dart'
    if (dart.library.nonexistent) 'packageflutter/material.dart';

不过，这种做法比较复杂，而且很少有必要。Flutter团队的建议更为简单：将你的包升级到material-ui，然后提高主版本号，让用户们按照自己的节奏进行升级。在material-ui中提供的兼容性机制，可以帮助那些正在迁移自己应用程序的用户顺利实现新旧环境的共存。

查看你的pub.dev评分

在将你的包升级到material-ui之后，用于计算pub.dev评分的静态分析工具会识别出这一变更，并相应地给予奖励。现在，那些还没有进行迁移的包会在pub.dev评分中得到较低的分数。这种设计是故意设置的，目的是为了鼓励更多人采用这些新的开发标准。

Flutter 3.47中还发生了哪些变化

解耦是 Flutter 3.47最显著的特点，但该版本还带来了其他几项会对实际项目产生影响的重大变更。

Impeller现已成为桌面平台的默认渲染引擎

Flutter的下一代渲染引擎Impeller，在iOS和Android平台上早已被设置为默认选项，现在它也成为了macOS、Windows和Linux平台的默认渲染引擎。Impeller通过在构建时而不是运行时来编译着色器，从而避免了动画首次播放时出现的卡顿现象。

对于大多数项目来说，这一变更几乎不会产生任何明显的影响——你的动画从第一帧开始就会显得更加流畅。如果你遇到了渲染方面的问题，需要暂时禁用Impeller，可以参考以下代码进行设置：

<!-- macOS: ios/Runner/Info.plist -->
<key>>FLTEnableImpeller<>/key>>
<false/>

// Windows: windows/runner/main.cpp
project.set_impeller_switch(flutter::ImpellerSwitch::Disabled);

// Linux: linux/my_application.cc
fl_dart_project_set_enable_impeller(project, FALSE);

这些机制是为那些在新默认设置中遇到问题的项目提供的。未来版本会移除对Skia的回退选项，因此如果你必须选择禁用Impeller，请向Flutter团队提交错误报告，以便他们能够修复相关问题。

最低支持的iOS和macOS版本已提高

由于新增了对Xcode 27的支持，最低支持的操作系统版本也发生了变化：

平台          之前的最低版本      新的最低版本（Flutter 3.47及以上）
iOS            13                  15
macOS         10.15 (Catalina)    12 (Monterey)

如果你的应用的ios/Runner.xcodeproj或macos/Runner.xcodeproj文件中指定的部署目标低于这些新规定的最低版本，那么构建过程将会失败。请在Xcode中更新这些部署目标，或者运行flutter build ios让Flutter CLI自动处理这一设置——该命令会提示你是否存在不匹配的情况。

iOS的UIScene生命周期要求

使用Xcode 27构建的应用程序，如果仍然采用旧的UIApplication委托生命周期模型（而非新的UIScene生命周期模型），那么在iOS 27系统上将无法正常启动。对于大多数Flutter应用程序来说，CLI会在构建过程中自动完成这一迁移工作。

但如果你的应用中包含自定义的本地代码（位于AppDelegate.swift或AppDelegate.m文件中），或者使用了依赖于旧生命周期模型的插件，那么你需要按照Flutter文档中的指南手动进行迁移操作。

Widget预览功能已正式稳定发布

以前需要先构建整个应用程序才能查看单个组件的预览效果的功能，现在已经正式稳定发布了。在项目根目录下创建一个.widget_preview/文件夹，可以缓存预览状态，从而加快应用程序的启动速度。如果你们的团队经常对组件界面进行反复修改，那么启用这一功能会非常有用。

WebAssembly正逐渐成为默认选择

虽然Wasm目前还不是Flutter Web的默认开发方案，但这一趋势正在逐步显现。你现在就可以选择使用它：

flutter build web --release --wasm

--wasm选项会让你构建针对WebAssembly而非JavaScript的Flutter Web应用。对于那些需要大量计算资源的UI界面来说，这种设置带来的性能提升非常显著。不过，你的代码及依赖库必须使用package:web而不是dart:html，因为Wasm不支持传统的HTML库。目前大多数流行的开发包都已经完成了迁移。

弃用时间表：旧导入方式何时将不再可用

了解这一时间表对于规划你的迁移计划至关重要。

这个时间表清楚地展示了 Flutter逐渐淘汰旧版material_ui和cupertino-ui包的进程。

2026年8月，Flutter 3.47版本：新的material_ui和cupertino/ui包升级到1.0版本，dart fix迁移工具也已可用。此时使用旧导入方式仍然可以正常编译，且不会产生任何警告，整个开发生态系统也开始逐渐采用这些新包。

2026年11月，Flutter Fall Stable版本：旧的package:flutter/material.dart和packageflutter Cupertino.dart导入方式被正式弃用。使用这些方式的开发者会在分析工具中看到警告信息，但现有应用程序在此阶段仍然可以正常编译和运行。

2027年的某个版本：这些旧导入方式将从Flutter SDK中完全移除，未完成迁移的项目将无法再使用它们进行编译。

最安全的迁移时机就是现在，在2026年11月之前，因为此时使用旧导入方式仍然可以顺利编译通过。如果在弃用警告期（2026年11月至正式移除期间）进行迁移，虽然仍能完成迁移，但分析工具会发出警告信息；而如果在这些旧导入方式被完全移除之后再进行迁移，则需要采取紧急措施才能解决问题，因此最好提前做好规划。

最佳实践

尽早迁移，一次完成迁移

自动迁移工具已经可以用于生产环境。现在就使用它，你可以立即享受到更快的material_ui和cupertino-ui包更新带来的好处，完全避免进入弃用警告期，从而让你的开发进度领先于整个生态系统。

那些较早进行迁移的团队也可以避免这样一种情况：在他们仍在使用旧版本的时候，依赖关系的升级会不小心引入新版本包中存在的错误修改。

迁移后删除flutter_localizations包

在迁移到material_ui之后，你在pubspec.yaml文件中指定的flutter_localizations包就变得多余了。因为material-ui已经包含了该包所提供的本地化功能，所以不需要再保留这个包了。请按照以下步骤将其删除：

# 迁移完成后，请从pubspec.yaml文件中删除以下内容
# flutter_localizations:
#   sdk: flutter

同时，还需要在所有Dart文件中删除对flutter_localizations的导入语句，例如：

# 从所有Dart文件中删除以下导入语句
# Remove: import 'package:flutter_localizations/flutter_localizations.dart';

虽然在项目中保留flutter_localizations包不会导致任何错误，但它属于多余的组件，而且会在查看项目依赖关系时造成混淆。

暂时使用兼容性桥接工具，但不要永久依赖它

MaterialUiCompatibilityBridge只是一个过渡性的工具。在设计系统架构时，不应该以它的存在为依据。在迁移过程中添加这个工具，等所有依赖关系都迁移到material_ui之后，再及时将其删除。你可以定期使用以下命令检查依赖关系的迁移状态：

flutter pub outdated

在持续集成环境中固定Material和Cupertino包的版本

由于material_ui和cupertino_ui都会每周发布更新版本，因此你可能需要在持续集成环境中固定这些包的具体版本，以确保构建过程的可重复性。具体操作方法如下：

# 为确保生产环境的稳定性，请在pubspec.yaml文件中指定以下版本
dependencies:
  material_ui: 1.2.0   # 为持续集成环境固定特定版本
  cupertino_ui: 1.1.0

在开发环境中，使用^这种版本约束即可确保代码始终使用最新版本。而对于持续集成和生产环境的构建来说，固定具体版本并有意识地控制版本的更新顺序，可以帮助你更好地管理不同构建版本之间的差异。

常见的错误

在同一文件中混合使用旧版和新版的导入语句

// 错误做法：在同一文件中同时使用旧版和新版的导入语句
import 'packageflutter/material.dart';
import 'package:material_ui/material_ui.dart'; // 这是重复导入

在同一文件中同时使用这两种导入语句是多余的，而且可能会导致分析工具提示类型定义重复的错误。迁移完成后，每个文件都应该只包含一个针对material-ui的导入语句，即新的package:material_ui/material_ui.dart。你可以运行flutter analyze命令来检查是否存在这样的问题。

在需要时忘记使用兼容性桥接工具

如果你迁移了应用程序中的导入依赖项，但没有添加 `MaterialUiCompatibilityBridge`，而你的某些依赖项仍然使用旧版本的 Material 库，那么在运行时你可能会遇到错误——这些组件会因为查找位置不正确而找不到继承的主题数据。出现这种问题的症状通常是“主题值为 null”，或者出现“无法找到类型为 `MaterialLocalizations` 的祖先”这样的错误。解决这个问题的方法就是一定要添加 `MaterialUiCompatibilityBridge`。

在修复代码问题后直接运行 `pub get`，而无需先添加相应的包

# 错误的顺序
dart fix --apply --code=migrate_design_widgets
# 如果 `pubspec.yaml` 没有更新，分析错误仍然会存在

# 如果工具无法更新 `pubspec.yaml`，正确的顺序应该是这样
flutter pub add material_ui
flutter pub add cupertino_ui
dart fix --apply

在执行 `dart fix` 命令时，确保项目中的这些依赖包已经可以被正确解析，这样才能使导入关系的更新生效。如果你在这些包还没有被添加到 `pubspec.yaml` 中时就运行这个命令，虽然导入字符串可能会被更新，但那些无法被解析的依赖项仍然会存在，从而导致分析工具报错。

在迁移依赖包时不要提升其版本号

如果你维护着一个依赖包，并将其迁移到 `material_ui` 版本，但没有提升其版本号，那么那些还没有在 `pubspec.yaml` 中添加 `material-ui` 依赖的消费者，在更新你的依赖包时就会遇到解析失败的问题。

每当你的依赖包新增了外部依赖项时，都必须提升其版本号——因为从使用内置的 SDK 库转变为明确指定外部包作为依赖项，实际上就意味着版本号的变更。

迁移后组件的行为可能会发生变化

有些开发者认为，在将应用程序迁移到 Material 3 Expressive 或其他 Material Design 更新版本的过程中，组件的行为也会随之改变。但实际上并非如此。`material_ui` 1.0 版本实际上只是在代码冻结阶段对 `packageflutter/material.dart` 的简单复制而已；这些组件依然是相同的，它们的行为和视觉样式也没有任何变化。这种分离机制只是一种架构上的调整，并不是视觉设计上的重新设计。未来 Material 3 Expressive 中带来的视觉改进将会在 `material_ui` 1.0 之后的后续版本中逐步体现出来。

结论

将 Material 和 Cupertino 从 Flutter SDK 的核心部分分离出来，这是 Flutter 自诞生以来所进行的最为重要的架构调整之一。早在之前的文章 《在 Flutter 中分离 Material 和 Cupertino》 中就提出了这一设想，而现在这一目标已经完全实现，并且已经在 Flutter 3.47 版本中正式投入使用。

从这次发布开始，旧功能的弃用进程就已经正式启动了。到2026年11月，这些旧功能将正式被弃用。对于任何团队来说，这样的时间安排都足以完成迁移工作，但这并不是拖延迁移的借口——每推迟一周，就会错过一周的Material组件更新。

目前可以采取以下三个实际步骤：首先运行`flutter upgrade`命令来安装Flutter 3.47版本；接着运行`dart fix --apply --code=migrate_design_widgets`命令来迁移相关的导入依赖；最后运行`flutter analyze`命令来验证迁移结果。对于大多数项目来说，这三个命令就已经完成了所有的迁移工作。如果某些依赖库需要兼容性桥接方案，可以在迁移过程中添加该方案，完成后再将其移除。

Flutter 3.47是一个重要的里程碑。这次更新所带来的解耦机制、更快的迭代速度、更便捷的贡献流程、风格中立的核心架构，以及独立的组件版本管理系统，使得Flutter真正具备了模块化的设计特性。因此，现在就进行迁移是非常值得的。

参考资料

• Flutter 3.47的新功能：Flutter官方博客中发布的文章，介绍了此次更新中引入的独立UI组件包、桌面版Impeller引擎、稳定的组件预览功能以及其他各项变化。
• Flutter版本变更说明：详细列出了每个Flutter版本中的重大变更内容，包括解耦迁移的相关信息。
• material-ui库：由flutter.dev发布的官方独立Material Design组件库，替代了之前的`package:flutter/material.dart`。
• cupertino_ui库：官方独立的Cupertino设计组件库，同样替代了之前的`package/flutter Cupertino.dart`。
• material-ui的GitHub仓库：该独立组件的源代码、问题跟踪信息以及贡献指南。
• Flutter中Material与Cupertino组件的解耦机制：我在freeCodeCamp网站上发表的文章，解释了这一设计的背景、决策过程以及在Flutter 3.47版本发布之前的开发进展。
• 解耦项目的GitHub页面：公开的项目管理页面，记录了整个解耦工作的进展情况，包括已完成的任务和仍在进行中的工作。
• Impeller渲染引擎文档：关于Impeler渲染引擎的完整说明，包括如何在各种平台上临时禁用该引擎，以及如何报告渲染相关的问题。