Contents

v3.19 后移除的已弃用 API

Contents

摘要
变更
时间线

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

所有受影响的 API 已编译到此主要资源中，以帮助迁移。为了进一步帮助您的迁移，请查看此快速参考表。

本节按包和受影响的类列出弃用内容。

包：flutter Flutter Fix 支持：是

TextTheme 的几个 TextStyle 属性在 v3.1 中被弃用，以支持来自 Material Design 规范的新样式。它们与新 API 中的适当替代项一起列在下面的表格中。

已弃用	新 API
headline1	displayLarge
headline2	displayMedium
headline3	displaySmall
headline4	headlineMedium
headline5	headlineSmall
headline6	titleLarge
subtitle1	titleMedium
subtitle2	titleSmall
bodyText1	bodyLarge
bodyText2	bodyMedium
caption	bodySmall
button	labelLarge
overline	labelSmall

迁移指南

迁移前的代码：

dart// TextTheme
// 基本构造函数
TextTheme(
  headline1: headline1Style,
  headline2: headline2Style,
  headline3: headline3Style,
  headline4: headline4Style,
  headline5: headline5Style,
  headline6: headline6Style,
  subtitle1: subtitle1Style,
  subtitle2: subtitle2Style,
  bodyText1: bodyText1Style,
  bodyText2: bodyText2Style,
  caption: captionStyle,
  button: buttonStyle,
  overline: overlineStyle,
);

// copyWith
TextTheme.copyWith(
  headline1: headline1Style,
  headline2: headline2Style,
  headline3: headline3Style,
  headline4: headline4Style,
  headline5: headline5Style,
  headline6: headline6Style,
  subtitle1: subtitle1Style,
  subtitle2: subtitle2Style,
  bodyText1: bodyText1Style,
  bodyText2: bodyText2Style,
  caption: captionStyle,
  button: buttonStyle,
  overline: overlineStyle,
);

// Getter
TextStyle style;
style = textTheme.headline1,
style = textTheme.headline2,
style = textTheme.headline3,
style = textTheme.headline4,
style = textTheme.headline5,
style = textTheme.headline6,
style = textTheme.subtitle1,
style = textTheme.subtitle2,
style = textTheme.bodyText1,
style = textTheme.bodyText2,
style = textTheme.caption,
style = textTheme.button,
style = textTheme.overline,

迁移后的代码：

dart// TextTheme
// 基本构造函数
TextTheme(
  displayLarge: headline1Style,
  displayMedium: headline2Style,
  displaySmall: headline3Style,
  headlineMedium: headline4Style,
  headlineSmall: headline5Style,
  titleLarge: headline6Style,
  titleMedium: subtitle1Style,
  titleSmall: subtitle2Style,
  bodyLarge: bodyText1Style,
  bodyMedium: bodyText2Style,
  bodySmall: captionStyle,
  labelLarge: buttonStyle,
  labelSmall: overlineStyle,
);

TextTheme.copyWith(
  displayLarge: headline1Style,
  displayMedium: headline2Style,
  displaySmall: headline3Style,
  headlineMedium: headline4Style,
  headlineSmall: headline5Style,
  titleLarge: headline6Style,
  titleMedium: subtitle1Style,
  titleSmall: subtitle2Style,
  bodyLarge: bodyText1Style,
  bodyMedium: bodyText2Style,
  bodySmall: captionStyle,
  labelLarge: buttonStyle,
  labelSmall: overlineStyle,
);

TextStyle style;
style = textTheme.displayLarge;
style = textTheme.displayMedium;
style = textTheme.displaySmall;
style = textTheme.headlineMedium;
style = textTheme.headlineSmall;
style = textTheme.titleLarge;
style = textTheme.titleMedium;
style = textTheme.titleSmall;
style = textTheme.bodyLarge;
style = textTheme.bodyMedium;
style = textTheme.bodySmall;
style = textTheme.labelLarge;
style = textTheme.labelSmall;

参考资料

API 文档：

TextTheme

相关的 PR：

在 #109817 中弃用
在 #139255 中移除

包：flutter Flutter Fix 支持：是

ThemeData 的几个 Color 属性在 v3.3 中被弃用，以支持来自 Material Design 规范的新样式。这些颜色是 errorColor、backgroundColor、bottomAppBarColor 和 toggleableActiveColor。前两个被 ThemeData.colorScheme 的属性替换，而 bottomAppBarColor 被组件主题的颜色 BottomAppBarTheme 替换。toggleableActiveColor 不再被框架使用，已被移除。

迁移指南

迁移前的代码：

dartvar myTheme = ThemeData(
  //...
  errorColor: Colors.red,
  backgroundColor: Colors.blue,
  bottomAppBarColor: Colors.purple,
  toggleableActiveColor: Colors.orange,
  //...
);
var errorColor = myTheme.errorColor;
var backgroundColor = myTheme.backgroundColor;
var bottomAppBarColor = myTheme.bottomAppBarColor;
var toggleableActiveColor = myTheme.toggleableActiveColor;

迁移后的代码：

dartvar myTheme = ThemeData(
  //...
  colorScheme: ColorScheme(
    /// ...
    error: Colors.red,
    background: Colors.blue,
  ),
  bottomAppBarTheme: BottomAppBarTheme(
    color: Colors.purple,
  ),
  //...
);
var errorColor = myTheme.colorScheme.error;
var backgroundColor = myTheme.colorScheme.background;
var bottomAppBarColor = myTheme.bottomAppBarTheme.color;
var toggleableActiveColor = Colors.orange;

参考资料

API 文档：

相关的 PR：

在 #110162、#111080 和 #97972 中弃用
在 #144178、#144080、#144079 和 #144078 中移除

包：flutter Flutter Fix 支持：是

在 v3.4 之后，previewBuilder 被 CupertinoContextMenu 的 builder 替换。通过添加 builder，上下文菜单执行的整个动画都被覆盖，其中后半部分由 previewBuilder 执行，并由 CupertinoContextMenu.animationOpensAt 描绘。

迁移指南

迁移前的代码：

dartCupertinoContextMenu(
  previewBuilder: (BuildContext context, Animation<double> animation, Widget child) {
    return FittedBox(
      fit: BoxFit.cover,
      child: ClipRRect(
        borderRadius: BorderRadius.circular(64.0 * animation.value),
        child: Image.asset('assets/photo.jpg'),
      ),
    );
  },
  actions: <Widget>[
    CupertinoContextMenuAction(
      child: const Text('Action one'),
      onPressed: () {},
    ),
  ],
  child: FittedBox(
    fit: BoxFit.cover,
    child: Image.asset('assets/photo.jpg'),
  ),
);

迁移后的代码：

dartCupertinoContextMenu(
  actions: <Widget>[
    CupertinoContextMenuAction(
      child: const Text('Action one'),
      onPressed: () {},
    ),
  ],
  builder: (BuildContext context, Animation<double> animation) {
    final Animation<BorderRadius?> borderRadiusAnimation = BorderRadiusTween(
      begin: BorderRadius.circular(0.0),
      end: BorderRadius.circular(CupertinoContextMenu.kOpenBorderRadius),
    ).animate(
      CurvedAnimation(
        parent: animation,
        curve: Interval(
          CupertinoContextMenu.animationOpensAt,
          1.0,
        ),
      ),
    );

    final Animation<Decoration> boxDecorationAnimation = DecorationTween(
      begin: const BoxDecoration(
        color: Color(0xFFFFFFFF),
        boxShadow: <BoxShadow>[],
      ),
      end: BoxDecoration(
        color: Color(0xFFFFFFFF),
        boxShadow: CupertinoContextMenu.kEndBoxShadow,
      ),
    ).animate(
      CurvedAnimation(
        parent: animation,
        curve: Interval(
          0.0,
          CupertinoContextMenu.animationOpensAt,
        )
      )
    );

    return Container(
      decoration: animation.value < CupertinoContextMenu.animationOpensAt
        ? boxDecorationAnimation.value
        : null,
      child: FittedBox(
        fit: BoxFit.cover,
        child: ClipRRect(
          borderRadius: borderRadiusAnimation.value ?? BorderRadius.circular(0.0),
          child: SizedBox(
            height: 150,
            width: 150,
            child: Image.asset('assets/photo.jpg'),
          ),
        ),
      )
    );
   }
 )

参考资料

API 文档：

CupertinoContextMenu

相关的 PR：

在 #110616 中弃用
在 #143990 中移除

包：flutter Flutter Fix 支持：是

Scrollbar 的 showTrackOnHover 属性及其关联的组件主题 ScrollbarThemeData.showTrackOnHover 在 v3.4 之后被状态属性 ScrollbarThemeData.trackVisibility 替换。通过使用 trackVisibility，所有状态的排列组合都可以影响滚动条轨道的显示，而不仅仅是悬停。

迁移指南

迁移前的代码：

dartScrollbar(
  showTrackOnHover: true,
  child: //...
);
ScrollbarThemeData(
  showTrackOnHover: true,
);

迁移后的代码：

dartScrollbar(
  child: //...
);
ScrollbarThemeData(
  // 这将始终显示任何状态下的轨道。
  trackVisibility: MaterialStateProperty<bool>.all(true),
);
// 或者
ScrollbarThemeData(
  // 仅在悬停时显示。
  trackVisibility: (Set<MaterialState> states) => states.contains(MaterialState.hovered),
);

参考资料

API 文档：

相关的 PR：

在 #111706 中弃用
在 #144180 中移除

包：flutter Flutter Fix 支持：否

KeepAliveHandle 的 release 方法已被移除，并被调用…… 在 v3.3 之后，release 方法被 dispose 方法取代。进行此更改是因为发现 release 方法经常在未调用 dispose 方法的情况下被调用，从而导致内存泄漏。dispose 方法现在执行与 release 方法相同的函数。

迁移指南

迁移前的代码：

dartKeepAliveHandle handle = KeepAliveHandle();
handle.release();
handle.dispose();

迁移后的代码：

dartKeepAliveHandle handle = KeepAliveHandle();
handle.dispose();

参考资料

API 文档：

KeepAliveHandle

相关的 PR：

在 #108384 中弃用
在 #143961 中移除

包：flutter Flutter Fix 支持：是

在 v3.3 之后，InteractiveViewer 的 alignPanAxis 属性被 panAxis 属性替换。进行此更改是为了在 InteractiveViewer 中启用更多平移模式。

迁移指南

迁移前的代码：

dartInteractiveViewer(
  alignPanAxis: true,
);

迁移后的代码：

dartInteractiveViewer(
  panAxis: PanAxis.aligned,
);

参考资料

API 文档：

相关的 PR：

在 #109014 中弃用
在 #142500 中移除

包：flutter Flutter Fix 支持：是

在 v3.5 之后，MediaQuery 的 boldTextOverride 方法被 boldTextOf 方法替换。此更改是作为 MediaQuery 的更大重构的一部分进行的，最显著的是减少了依赖它的 widget 触发的重建次数。

迁移指南

迁移前的代码：

dart

MediaQuery.boldTextOverride(context);

迁移后的代码：

dart

MediaQuery.boldTextOf(context)

参考资料

API 文档：

MediaQuery

相关的 PR：

在 #114459 中弃用
在 #143960 中移除

包：flutter Flutter Fix 支持：否

随着 AnimatedGrid 的添加，AnimatedList 进行了重构以共享一个公共基类。在 v3.5 之后，以前命名的 AnimatedListItemBuilder 和 AnimatedListRemovedItemBuilder 被重命名为更好地反映它们可以使用的类。重命名任何对 AnimatedItemBuilder 和 AnimatedRemovedItemBuilder 的引用。

参考资料

API 文档：

相关的 PR：

在 #113793 中弃用
在 #143974 中移除

包：flutter_driver Flutter Fix 支持：是

flutterDriver 的 enableAccessibility 方法在 v2.3 中被弃用。它已被移除并被 setSemantics 替换。此更改使得可以启用或禁用辅助功能，而不仅仅是启用它。

迁移指南

迁移前的代码：

dartFlutterDriver driver = FlutterDriver.connectedTo(
  // ...
);
driver.enableAccessibility();

迁移后的代码：

dartFlutterDriver driver = FlutterDriver.connectedTo(
  // ...
);
driver.setSemantics(true);

参考资料

API 文档：

FlutterDriver

相关的 PR：

在 #82939 中弃用
在 #143979 中移除

包：flutter_driver Flutter Fix 支持：是

TimelineSummary 的 writeSummaryToFile 方法在 v2.1 中被弃用。它已被移除并被 writeTimelineToFile 替换。

迁移指南

迁移前的代码：

dartTimelineSummary summary = TimelineSummary.summarize(
  myTimeline,
);
summary.writeSummaryToFile(
  traceName,
  pretty: true,
);

迁移后的代码：

dartTimelineSummary summary = TimelineSummary.summarize(
  myTimeline,
);
summary.writeTimelineToFile(
  traceName,
  pretty: true,
);

参考资料

API 文档：

TimelineSummary

相关的 PR：

在 #79310 中弃用
在 #143983 中移除

Flutter Fix 支持：否

从 Flutter 3.0 开始，平台视图需要 API 23 或更高版本。在 Flutter 3.19 中，当在运行 API 级别 22 及以下的 Android 设备上使用平台视图时，我们现在会抛出 UnsupportedOperationException 异常。

迁移指南

将最小 API 级别设置为 23（或更高）或在显示平台视图之前检查 Android API 级别。

先前宣布的 (之前宣布) 关于上下文菜单的弃用，涉及 ToolbarOptions 以及 TextSelectionController 和 SelectableRegionState 的部分内容，在本周期中未被移除，以便有更多时间进行迁移。预计这些弃用将在下个周期中移除，届时将再次宣布。

稳定版发布：3.22.0

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

v3.19 后移除的已弃用 API

摘要

变更

`TextTheme`

`ThemeData`

`CupertinoContextMenu.previewBuilder`

`Scrollbar.showTrackOnHover`

`KeepAliveHandle.release` 方法

`InteractiveViewer.alignPanAxis`

`MediaQuery.boldTextOverride`

`AnimatedList` 的重命名 builder 类型定义

`FlutterDriver.enableAccessibility`

`TimelineSummary.writeSummaryToFile`

API 22 及以下版本的 Android 平台视图

时间线

摘要

变更

TextTheme

ThemeData

CupertinoContextMenu.previewBuilder

Scrollbar.showTrackOnHover

KeepAliveHandle.release 方法

InteractiveViewer.alignPanAxis

MediaQuery.boldTextOverride

AnimatedList 的重命名 builder 类型定义

FlutterDriver.enableAccessibility

TimelineSummary.writeSummaryToFile

API 22 及以下版本的 Android 平台视图

时间线

`TextTheme`

`ThemeData`

`CupertinoContextMenu.previewBuilder`

`Scrollbar.showTrackOnHover`

`KeepAliveHandle.release` 方法

`InteractiveViewer.alignPanAxis`

`MediaQuery.boldTextOverride`

`AnimatedList` 的重命名 builder 类型定义

`FlutterDriver.enableAccessibility`

`TimelineSummary.writeSummaryToFile`