跳到主内容

概述

#

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

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

变更

#

本节按软件包和受影响的类列出了废弃项。

TextTheme

#

软件包：flutter Flutter Fix 支持：是

TextTheme 的几个 TextStyle 属性在 v3.1 中已被弃用，以支持 Material Design 规范中的新样式。它们与新 API 中的相应替换项一起列在下表中。

弃用新 API
headline1displayLarge
headline2displayMedium
headline3displaySmall
headline4headlineMedium
headline5headlineSmall
headline6titleLarge
subtitle1titleMedium
subtitle2titleSmall
bodyText1bodyLarge
bodyText2bodyMedium
captionbodySmall
buttonlabelLarge
overlinelabelSmall

迁移指南

迁移前的代码

dart
// TextTheme
// Base constructor
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,
);

// Getters
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
// Base constructor
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 文档

相关 PR

ThemeData

#

软件包：flutter Flutter Fix 支持：是

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

迁移指南

迁移前的代码

dart
var 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;

迁移后的代码

dart
var 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

CupertinoContextMenu.previewBuilder

#

软件包：flutter Flutter Fix 支持：是

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

迁移指南

迁移前的代码

dart
CupertinoContextMenu(
  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'),
  ),
);

迁移后的代码

dart
CupertinoContextMenu(
  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 文档

相关 PR

Scrollbar.showTrackOnHover

#

软件包：flutter Flutter Fix 支持：是

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

迁移指南

迁移前的代码

dart
Scrollbar(
  showTrackOnHover: true,
  child: //...
);
ScrollbarThemeData(
  showTrackOnHover: true,
);

迁移后的代码

dart
Scrollbar(
  child: //...
);
ScrollbarThemeData(
  // This will always show the track for any state.
  trackVisibility: MaterialStateProperty<bool>.all(true),
);
// Or
ScrollbarThemeData(
  // Only show on hover.
  trackVisibility: (Set<MaterialState> states) => states.contains(MaterialState.hovered),
);

参考资料

API 文档

相关 PR

KeepAliveHandle.release 方法

#

包：flutter 支持 Flutter Fix：否

KeepAliveHandle 的 release 方法已在 v3.3 后移除，并替换为调用 dispose。此更改是因为发现 release 经常在未调用 dispose 的情况下被调用，导致内存泄漏。dispose 方法现在执行与 release 相同的功能。

迁移指南

迁移前的代码

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

迁移后的代码

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

参考资料

API 文档

相关 PR

InteractiveViewer.alignPanAxis

#

软件包：flutter Flutter Fix 支持：是

InteractiveViewer 的 alignPanAxis 属性已在 v3.3 后移除，并替换为 panAxis。此更改是为了在 InteractiveViewer 中支持更多平移模式。

迁移指南

迁移前的代码

dart
InteractiveViewer(
  alignPanAxis: true,
);

迁移后的代码

dart
InteractiveViewer(
  panAxis: PanAxis.aligned,
);

参考资料

API 文档

相关 PR

MediaQuery.boldTextOverride

#

软件包：flutter Flutter Fix 支持：是

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

迁移指南

迁移前的代码

dart
MediaQuery.boldTextOverride(context);

迁移后的代码

dart
MediaQuery.boldTextOf(context)

参考资料

API 文档

相关 PR

AnimatedList 的 builder 类型别名已重命名

#

包：flutter 支持 Flutter Fix：否

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

参考资料

API 文档

相关 PR

FlutterDriver.enableAccessibility

#

包：flutter_driver 支持 Flutter Fix：是

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

迁移指南

迁移前的代码

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

迁移后的代码

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

参考资料

API 文档

相关 PR

TimelineSummary.writeSummaryToFile

#

包：flutter_driver 支持 Flutter Fix：是

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

迁移指南

迁移前的代码

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

迁移后的代码

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

参考资料

API 文档

相关 PR

API 22 及更低版本的 Android Platform Views

#

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-17。 查看源代码 或 报告问题。