跳到主内容

概述

#

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

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

变更

#

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

TextTheme

#

软件包：flutter Flutter Fix 支持：是

v3.1 中弃用了 `TextTheme` 的几个 `TextStyle` 属性，以支持 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 支持：是

v3.3 中弃用了 `ThemeData` 的几个 `Color` 属性，以支持 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 后，`CupertinoContextMenu` 的 `previewBuilder` 被 `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 支持：是

v3.4 后，`Scrollbar` 的 `showTrackOnHover` 属性及其关联的组件主题 `ScrollbarThemeData.showTrackOnHover` 被有状态属性 `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 支持：否

v3.3 后，`KeepAliveHandle` 的 `release` 方法被移除，并替换为调用 `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 支持：是

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

迁移指南

迁移前的代码

dart
InteractiveViewer(
  alignPanAxis: true,
);

迁移后的代码

dart
InteractiveViewer(
  panAxis: PanAxis.aligned,
);

参考资料

API 文档

相关 PR

MediaQuery.boldTextOverride

#

软件包：flutter Flutter Fix 支持：是

v3.5 后，`MediaQuery` 的 `boldTextOverride` 方法被移除，并替换为 `boldTextOf`。进行此更改是 `MediaQuery` 大规模重构的一部分，最值得注意的是减少了依赖于它的 widgets 触发的重建次数。

迁移指南

迁移前的代码

dart
MediaQuery.boldTextOverride(context);

迁移后的代码

dart
MediaQuery.boldTextOf(context)

参考资料

API 文档

相关 PR

`AnimatedList` 的构建器 typedefs 重命名

#

包：flutter Flutter Fix 支持：否

随着 `AnimatedGrid` 的加入，`AnimatedList` 被重构以共享一个公共基类。v3.5 后，之前命名的 `AnimatedListItemBuilder` 和 `AnimatedListRemovedItemBuilder` 被重命名，以更好地反映它们可以与哪些类一起使用。请将所有对 `AnimatedItemBuilder` 和 `AnimatedRemovedItemBuilder` 的引用重命名。

参考资料

API 文档

相关 PR

FlutterDriver.enableAccessibility

#

包：flutter_driver Flutter Fix 支持：是

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

迁移指南

迁移前的代码

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

迁移后的代码

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

参考资料

API 文档

相关 PR

TimelineSummary.writeSummaryToFile

#

包：flutter_driver Flutter Fix 支持：是

v2.1 中弃用了 `TimelineSummary` 的 `writeSummaryToFile` 方法。它已被移除并替换为 `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 平台视图

#

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。 查看源文件 或 报告问题。