v1.22 后移除的已弃用 API

根据 Flutter 的弃用策略，在 1.22 稳定版发布后达到生命周期结束的已弃用 API 已被移除。这是 Flutter 首次移除已弃用的 API，其中一些弃用甚至早于我们的迁移指南策略。

所有受影响的 API 已编译到此主要来源，以帮助迁移。还提供了一个快速参考表。

设计文档和文章 提供了有关 Flutter 弃用策略的更多上下文信息。

本节列出了按受影响类列出的弃用项。

修复工具支持：仅 IDE 修复。

CupertinoDialog 在 v0.2.3 中已弃用。请改用 CupertinoAlertDialog 或 CupertinoPopupSurface。

迁移指南

CupertinoAlertDialog

迁移前的代码：

CupertinoDialog(child: myWidget);

迁移后的代码：

CupertinoAlertDialog(content: myWidget);

CupertinoPopupSurface

迁移前的代码：

CupertinoDialog(child: myWidget);

迁移后的代码：

CupertinoPopupSurface(child: myWidget);

参考

API 文档：

• CupertinoAlertDialog
• CupertinoPopupSurface

相关问题：

• 弃用 CupertinoDialog 类

相关 PR：

• 在 #20649 中弃用
• 在 #73604 中移除

修复工具支持：否

CupertinoNavigationBar.actionsForegroundColor 和 CupertinoSliverNavigationBar.actionsForegroundColor 在 v1.1.2 中已弃用。设置 CupertinoTheme 中的 primaryColor 会替代此设置。要访问 primaryColor，请调用 CupertinoTheme.of(context).primaryColor。

迁移指南

迁移前的代码：

CupertinoNavigationBar(
  actionsForegroundColor: CupertinoColors.systemBlue,
);
CupertinoSliverNavigationBar(
  actionsForegroundColor: CupertinoColors.systemBlue,
);

迁移后的代码：

CupertinoTheme(
  data: CupertinoThemeData(
    primaryColor: CupertinoColors.systemBlue
  ),
  child: ...
);

// 从 `CupertinoTheme` 访问颜色
CupertinoTheme.of(context).primaryColor;

参考

API 文档：

• CupertinoNavigationBar
• CupertinoSliverNavigationBar
• CupertinoTheme
• CupertinoThemeData

相关问题：

• 创建 CupertinoApp 和 CupertinoTheme

相关 PR：

• 在 #23759 中弃用
• 在 #73745 中移除

修复工具支持：是

CupertinoTextThemeData.brightness 在 v1.10.14 中已弃用。此字段成员在弃用时已失效。此参数没有替代项，应移除引用。

迁移指南

迁移前的代码：

const CupertinoTextThemeData themeData = CupertinoTextThemeData(brightness: Brightness.dark);
themeData.copyWith(brightness: Brightness.light);

迁移后的代码：

const CupertinoTextThemeData themeData = CupertinoTextThemeData();
themeData.copyWith();

参考

API 文档：

• CupertinoTextThemeData

相关问题：

• 修改 CupertinoColors 和 CupertinoTheme 以使用动态颜色

相关 PR：

• 在 #41859 中弃用
• 在 #72017 中移除

修复工具支持：是

PointerEnterEvent 和 PointerExitEvent 的 fromHoverEvent 构造函数在 v1.4.3 中已弃用。应改用 fromMouseEvent 构造函数。

迁移指南

迁移前的代码：

final PointerEnterEvent enterEvent = PointerEnterEvent.fromHoverEvent(PointerHoverEvent());
final PointerExitEvent exitEvent = PointerExitEvent.fromHoverEvent(PointerHoverEvent());

迁移后的代码：

final PointerEnterEvent enterEvent = PointerEnterEvent.fromMouseEvent(PointerHoverEvent());
final PointerExitEvent exitEvent = PointerExitEvent.fromMouseEvent(PointerHoverEvent());

参考

API 文档：

• PointerEnterEvent
• PointerExitEvent

相关问题：

• PointerEnterEvent 和 PointerExitEvent 只能从悬停事件创建

相关 PR：

• 在 #28602 中弃用
• 在 #72395 中移除

修复工具支持：是

showDialog 的 child 参数在 v0.2.3 中已弃用。应改用 builder 参数。

迁移指南

迁移前的代码：

showDialog(child: myWidget);

迁移后的代码：

showDialog(builder: (context) => myWidget);

参考

API 文档：

• showDialog

相关问题：

• showDialog 应使用构建器而不是子项

相关 PR：

• 在 #15303 中弃用
• 在 #72532 中移除

修复工具支持：是

Scaffold 的 resizeToAvoidBottomPadding 参数在 v1.1.9 中已弃用。应改用 resizeToAvoidBottomInset 参数。

迁移指南

迁移前的代码：

Scaffold(resizeToAvoidBottomPadding: true);

迁移后的代码：

Scaffold(resizeToAvoidBottomInset: true);

参考

API 文档：

• Scaffold

相关问题：

• 嵌套 Scaffold 时显示警告
• 带键盘的 SafeArea
• 双层堆叠的 Material Scaffold 不应双重调整大小以避免底部填充
• Window 和 MediaQueryData 上的 viewInsets 和 padding 应定义它们如何交互
• 在 TabBarView 内使用文本字段时出现底部溢出问题

相关 PR：

• 在 #26259 中弃用
• 在 #72890 中移除

修复工具支持：否

ButtonTheme 的 bar 构造函数在 v1.9.1 中已弃用。对于 ButtonBar，可以使用 ButtonBarTheme，如果使用不特定于 ButtonBar，则可以使用 ButtonTheme 的其他构造函数。

按钮特定的主题设置也可通过 TextButtonTheme、ElevatedButtonTheme 和 OutlinedButtonTheme 类实现，每个类分别对应相应的按钮类 TextButton、ElevatedButton 和 OutlinedButton。

迁移指南

迁移前的代码：

ButtonTheme.bar(
  minWidth: 10.0,
  alignedDropdown: true,
  height: 40.0,
);

迁移后的代码（使用 ButtonTheme）：

ButtonTheme(
  minWidth: 10.0,
  alignedDropdown: true,
  height: 40.0,
);

迁移后的代码（使用 ButtonBarTheme）：

ButtonBarTheme(
  data: ButtonBarThemeData(
    buttonMinWidth: 10.0,
    buttonAlignedDropdown: true,
    buttonHeight: 40.0,
  )
);

参考

API 文档：

• ButtonTheme
• ButtonBarTheme
• ButtonBar
• TextButtonTheme
• TextButton
• ElevatedButtonTheme
• ElevatedButton
• OutlinedButtonTheme
• OutlinedButton

相关问题：

• ButtonTheme.bar 使用强调色而不是主色
• ThemeData.accentColor 对文本的对比度不足
• 由于对 materialTapTargetSize 的更改导致 AlertDialog/ButtonBar 高度增加

相关 PR：

• 在 #37544 中弃用
• 在 #73746 中移除

修复工具支持：否

为了能够将小部件内嵌到段落中（如图像），InlineSpan、TextSpan 和 PlaceholderSpan 中的以下方法已弃用。

迁移指南

参考

API 文档：

• InlineSpan
• TextSpan
• PlaceholderSpan
• WidgetSpan

相关问题：

• 文本：支持内嵌图像

相关 PR：

• 开发历史：
  • #30069
  • #33946
  • #33794
• 在 #34051 中弃用
• 在 #73747 中移除

修复工具支持：否

为了防止启动画面过早关闭而导致黑屏，RenderView.scheduleInitialFrame 方法已弃用并移除。当调用 WidgetsFlutterBinding.ensureInitialized 时，就会发生这种情况。相反，请将对该方法的调用替换为 RenderView.prepareInitialFrame，然后是 RenderView.owner.requestVisualUpdate。

迁移指南

迁移前的代码：

scheduleInitialFrame();

迁移后的代码：

prepareInitialFrame();
owner.requestVisualUpdate();

参考

API 文档：

• RenderView
• WidgetsFlutterBinding

相关问题：

• WidgetsFlutterBinding.ensureInitialized() 过早关闭启动画面

相关 PR：

• 在 #39535 中弃用
• 在 #73748 中移除

修复工具支持：否

为了统一 find 和 findAll 的实现，Layer.findAll 方法已弃用，并引入了 Layer.findAnnotations。要迁移受影响的代码，请改用 findAllAnnotations。此方法返回一个 AnnotationResult，其中包含 AnnotationResult.annotations 中 findAll 的先前返回值。

迁移指南

迁移前的代码：

findAll(offset);

迁移后的代码：

findAllAnnotations(offset).annotations;

参考

API 文档：

• Layer
• MouseRegion
• RenderMouseRegion
• AnnotatedRegionLayer
• AnnotationResult

相关问题：

• 破坏性提案：MouseRegion 默认不透明；图层需要实现 findAnnotations

相关 PR：

• 在 #37896 中首次更改
• 在 #42953 中弃用
• 在 #73749 中移除

修复工具支持：否

BinaryMessages 类、其关联的静态方法和 defaultBinaryMessenger getter 已弃用并移除。defaultBinaryMessenger 实例已移至 ServicesBinding。这使得可以通过为测试创建 ServicesBinding 子类，在测试环境下注册不同的默认 BinaryMessenger。这样做允许您跟踪挂起的平台消息的数量，以用于同步目的。

迁移指南

参考

API 文档：

• ServicesBinding
• BinaryMessenger

相关问题：

• Flutter 对 Espresso/EarlGrey 的同步支持

相关 PR：

• 在 #37489 中首次更改
• 在 #38464 中弃用
• 在 #73750 中移除

修复工具支持：是

BuildContext 中的几种方法使用 Type 来搜索祖先。大多数这些方法在调用站点隐含强制类型转换，因为它们的返回类型是父类型。此外，即使类型实际上受到约束，在分析时也不会检查提供的类型。将这些方法设为泛型可以提高类型安全性并减少代码量。

这些方法更改会影响 BuildContext、Element 和 StatefulElement 类。TypeMatcher 类也已移除。

迁移指南

迁移前的代码：

ComplexLayoutState state = context.ancestorStateOfType(const TypeMatcher<ComplexLayoutState>()) as ComplexLayoutState;

迁移后的代码：

ComplexLayoutState state = context.ancestorStateOfType<ComplexLayoutState>();

BuildContext

Element

StatefulElement

参考

API 文档：

• Type
• BuildContext
• Element
• StatefulElement

相关 PR：

• 在 #44189 中弃用
• 在以下位置移除：
  • #69620
  • #72903
  • #72901
  • #73751

修复工具支持：是

deferFirstFrameReport 和 allowFirstFrameReport 方法

为了提供延迟渲染第一帧的选项，WidgetsBinding 的 deferFirstFrameReport 和 allowFirstFrameReport 方法已被弃用并移除。这对于需要异步获取初始化信息的部件非常有用，并且在它们等待这些信息时，不应渲染任何帧，因为这会过早地关闭启动画面。应分别改用 deferFirstFrame 和 allowFirstFrame 方法。

迁移指南

迁移前的代码：

final WidgetsBinding binding = WidgetsBinding.instance;
binding.deferFirstFrameReport();
binding.allowFirstFrameReport();

迁移后的代码：

final WidgetsBinding binding = WidgetsBinding.instance;
binding.deferFirstFrame();
binding.allowFirstFrame();

参考

API 文档：

• WidgetsBinding

相关 PR：

• 在以下位置首次更改：
  • #45135
  • #45588
• 在 #45941 中弃用
• 在 #72893 中移除

修复工具支持：否

flutter_driver 包中的 WaitUntilNoTransientCallbacks、WaitUntilNoPendingFrame 和 WaitUntilFirstFrameRasterized 方法已被弃用并移除，以便提供更易组合的 waitForCondition API，该 API 可用于组合客户端想要等待的条件。

迁移指南

参考

API 文档：

• WaitForCondition

相关问题：

• Flutter 对 Espresso/EarlGrey 的同步支持

相关 PR：

• 在 #37736 中首次更改
• 在 #38836 中弃用
• 在 #73754 中移除

稳定版：2.0.0

除非另有说明，否则本网站上的文档反映的是 Flutter 的最新稳定版本。页面最后更新于 2025-01-30。 查看源代码 或 报告问题。