跳到主内容

概述

#

根据 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 替代。

这些更改是为了与更新的 Material Design 规范对 ColorScheme 的要求保持一致。关于 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，则 Brightness 会从 ThemeData.primaryColor 推断出来。

此更改是为了更新 Theme 以匹配新的 Material Design 指南。关于 theaming 系统的整体更新，包括 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 始终指向滚动条的 thumb。随着滚动条 track 的添加，以及其在响应鼠标悬停和拖动时的可见性配置的多样化，我们重命名了此属性以提供更清晰的 API。

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

此更改是为了让 Scrollbar 的 thickness 能够响应所有类型的状态，而不仅仅是悬停。使用 MaterialStateProperties 也符合 material 库中基于状态配置 widget 的约定，而不是为每种交互状态的排列枚举属性。

迁移指南

迁移前的代码

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 支持：否

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

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

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

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

迁移指南

迁移前的代码

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

迁移后的代码

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

参考资料

API 文档

相关 PR

时间线

#

在稳定版中发布: 3.13.0

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