跳到主内容

概述

#

根据 Flutter 的弃用政策，在 3.10 稳定版发布后达到生命周期结束的弃用 API 已被移除。

所有受影响的 API 已被整理到这份主要资料中，以帮助进行迁移。另提供一份快速参考表。

变更

#

本节列出了弃用项，按包和受影响的类进行分类。

ThemeData.fixTextFieldOutlineLabel

#

软件包：flutter Flutter Fix 支持：是

ThemeData.fixTextFieldOutlineLabel 已在 v2.5 中弃用。对此属性的引用可以被移除。

fixTextFieldOutlineLabel 是一个临时的迁移标志，允许用户平稳地迁移到新行为，而不是出现硬性中断。在弃用之前，此属性已从文本字段的标签修复过渡到新的默认行为。

迁移指南

迁移前的代码

dart
var themeData = ThemeData(
  fixTextFieldOutlineLabel: true,  
);

迁移后的代码

dart
var themeData = ThemeData(
);

参考资料

API 文档

相关 PR

OverscrollIndicatorNotification.disallowGlow

#

软件包：flutter Flutter Fix 支持：是

OverscrollIndicatorNotification.disallowGlow 已在 v2.5 中弃用。替代方法是 disallowIndicator。

引入 StretchingOverscrollIndicator 后，disallowIndicator 被创建为原始方法的替代品。此前，GlowingOverscrollIndicator 是唯一一种分发 OverscrollIndicatorNotification 的类型，因此该方法已更新，以更好地反映多种类型的指示器。

迁移指南

迁移前的代码

dart
bool _handleOverscrollIndicatorNotification(OverscrollIndicatorNotification notification) {
  notification.disallowGlow();
  return false;
}

迁移后的代码

dart
bool _handleOverscrollIndicatorNotification(OverscrollIndicatorNotification notification) {
  notification.disallowIndicator();
  return false;
}

参考资料

API 文档

相关 PR

ColorScheme primaryVariant 和 secondaryVariant

#

软件包：flutter Flutter Fix 支持：是

ColorScheme.primaryVariant 和 ColorScheme.secondaryVariant 已在 v2.6 中弃用。替代项分别是 ColorScheme.primaryContainer 和 ColorScheme.secondaryContainer。

这些更改旨在与 ColorScheme 的更新版 Material Design 规范保持一致。对 ColorScheme 的更新在Material 3 的 ColorScheme 设计文档中进行了更全面的介绍。

迁移指南

迁移前的代码

dart
var colorScheme = ColorScheme(
  primaryVariant: Colors.blue,
  secondaryVariant: Colors.amber,
);
var primaryColor = colorScheme.primaryVariant;
var secondaryColor = colorScheme.secondaryVariant;

迁移后的代码

dart
var colorScheme = ColorScheme(
  primaryContainer: Colors.blue,
  secondaryContainer: Colors.amber,
);
var primaryColor = colorScheme.primaryContainer;
var secondaryColor = colorScheme.secondaryContainer;

参考资料

设计文档

API 文档

相关 PR

ThemeData.primaryColorBrightness

#

软件包：flutter Flutter Fix 支持：是

ThemeData.primaryColorBrightness 已在 v2.6 中弃用，并且自那时起框架就未曾使用过。应移除引用。现在，如果未显式提供 ThemeData.brightness，则会从 ThemeData.primaryColor 推断 Brightness。

此更改是 Theme 更新的一部分，旨在符合新的 Material Design 指南。主题系统的整体更新，包括移除 primaryColorBrightness，在Material 主题系统更新设计文档中进行了更全面的讨论。

迁移指南

迁移前的代码

dart
var themeData = ThemeData(
  primaryColorBrightness: Brightness.dark,
);

迁移后的代码

dart
var themeData = ThemeData(
);

参考资料

设计文档

API 文档

相关 PR

RawScrollbar 和子类的更新

#

软件包：flutter Flutter Fix 支持：是

RawScrollbar、Scrollbar、ScrollbarThemeData 和 CupertinoScrollbar 的 isAlwaysShown 属性已在 v2.9 中弃用。在所有情况下，替代项都是 thumbVisibility。

进行此更改的原因是 isAlwaysShown 始终指滚动条的滑块。随着滚动条轨道的添加，以及其可见性在响应鼠标悬停和拖动时的不同配置，我们重命名了此属性以提供更清晰的 API。

此外，Scrollbar.hoverThickness 也已在 v2.9 中弃用。其替代项是 MaterialStateProperty ScrollbarThemeData.thickness。

进行此更改是为了允许 Scrollbar 的厚度响应各种状态，包括但不限于悬停。使用 MaterialStateProperties 也符合 Material 库中的约定，即根据组件的状态而非为交互状态的每种排列枚举属性来配置组件。

迁移指南

迁移前的代码

dart
var rawScrollbar = RawScrollbar(
  isAlwaysShown: true,
);
var scrollbar = Scrollbar(
  isAlwaysShown: true,
  hoverThickness: 15.0,
);
var cupertinoScrollbar = CupertinoScrollbar(
  isAlwaysShown: true,
);
var scrollbarThemeData = ScrollbarThemeData(
  isAlwaysShown: true,
);

迁移后的代码

dart
var rawScrollbar = RawScrollbar(
  thumbVisibility: true,
);
var scrollbar = Scrollbar(
  thumbVisibility: true,
);
var cupertinoScrollbar = CupertinoScrollbar(
  thumbVisibility: true,
);
var scrollbarThemeData = ScrollbarThemeData(
  thumbVisibility: true,
  thickness: MaterialStateProperty.resolveWith((Set<MaterialState> states) {
    return states.contains(MaterialState.hovered) ? null : 15.0;
  }),
);

参考资料

API 文档

相关 PR

AnimationSheetBuilder display 和 sheetSize

#

包：flutter_test Flutter Fix 支持：是

AnimationSheetBuilder 的 display 和 sheetSize 方法已在 v2.3 中弃用。替代方法是 collate。

AnimationSheetBuilder 的输出步骤此前需要调用这两个方法，但现在通过一次对 collate 的调用即可简化。

collate 函数直接将图像组合在一起并异步返回图像。它所需的样板代码更少，并且在不影响质量的情况下输出更小的图像。

迁移指南

提供了详细的迁移指南

迁移前的代码

dart
final AnimationSheetBuilder animationSheet = AnimationSheetBuilder(
    frameSize: const Size(40, 40)
);

await tester.pumpFrames(animationSheet.record(
  const Directionality(
    textDirection: TextDirection.ltr,
    child: Padding(
      padding: EdgeInsets.all(4),
      child: CircularProgressIndicator(),
    ),
  ),
), const Duration(seconds: 2));

tester.binding.setSurfaceSize(animationSheet.sheetSize());

final Widget display = await animationSheet.display();
await tester.pumpWidget(display);

await expectLater(
  find.byWidget(display),
  matchesGoldenFile('material.circular_progress_indicator.indeterminate.png'),
);

迁移后的代码

dart
final AnimationSheetBuilder animationSheet = AnimationSheetBuilder(
    frameSize: const Size(40, 40)
);

await tester.pumpFrames(animationSheet.record(
  const Directionality(
    textDirection: TextDirection.ltr,
    child: Padding(
      padding: EdgeInsets.all(4),
      child: CircularProgressIndicator(),
    ),
  ),
), const Duration(seconds: 2));

await expectLater(
  animationSheet.collate(20),
  matchesGoldenFile('material.circular_progress_indicator.indeterminate.png'),
);

参考资料

API 文档

相关 PR

flutter_test 超时逻辑

#

包：flutter_test Flutter Fix 支持：否

以下与测试中的超时逻辑相关的 API 已在 v2.6 中弃用。没有替代项，应移除引用，但 testWidgets 的 initialTimeout 参数除外，该参数已由 timeout 替换。

  • TestWidgetsFlutterBinding.addTime
  • TestWidgetsFlutterBinding.runAsync 方法 - additionalTime 参数
  • TestWidgetsFlutterBinding.runTest 方法 - timeout 参数
  • AutomatedTestWidgetsFlutterBinding.runTest 方法 - timeout 参数
  • LiveTestWidgetsFlutterBinding.runTest 方法 - timeout 参数
  • testWidgets 方法 - initialTime 参数

发现这些会导致测试不稳定，并且未被受测客户使用。

自弃用以来，这些参数的使用对测试没有影响，因此移除引用应对现有代码库没有影响。

迁移指南

迁移前的代码

dart
testWidgets('Test', (_) {}, initialTimeout:  Duration(seconds: 5));

迁移后的代码

dart
testWidgets('Test', (_) {}, timeout:  Timeout(Duration(seconds: 5)));

参考资料

API 文档

相关 PR

时间线

#

在稳定版中发布: 3.13.0

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