概述

#

根據 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 規範中的新樣式。這些顏色包括 errorColorbackgroundColorbottomAppBarColortoggleableActiveColor。前兩個由 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 已被 CupertinoContextMenubuilder 替換。透過新增 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 支援:是

ScrollbarshowTrackOnHover 屬性及其關聯的元件主題 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:否

KeepAliveHandlerelease 方法已在 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 支援:是

InteractiveVieweralignPanAxis 屬性已在 v3.3 後移除,並替換為 panAxis。此更改是為了在 InteractiveViewer 中支援更多平移模式。

遷移指南

遷移前的程式碼

dart
InteractiveViewer(
  alignPanAxis: true,
);

遷移後的程式碼

dart
InteractiveViewer(
  panAxis: PanAxis.aligned,
);

參考資料

API 文件

相關 PR


MediaQuery.boldTextOverride

#

軟體包:flutter Flutter Fix 支援:是

MediaQueryboldTextOverride 方法已在 v3.5 後移除,並替換為 boldTextOf。此更改是 MediaQuery 大型重構的一部分,最顯著的是減少了依賴它的 widget 觸發重建的次數。

遷移指南

遷移前的程式碼

dart
MediaQuery.boldTextOverride(context);

遷移後的程式碼

dart
MediaQuery.boldTextOf(context)

參考資料

API 文件

相關 PR


AnimatedList 的 builder 類型別名已重新命名

#

包:flutter 支援 Flutter Fix:否

隨著 AnimatedGrid 的新增,AnimatedList 被重構為共享一個公共基類。之前命名的 AnimatedListItemBuilderAnimatedListRemovedItemBuilder 在 v3.5 後被重新命名,以更好地反映它們可以使用的類。請重新命名對 AnimatedItemBuilderAnimatedRemovedItemBuilder 的任何引用。

參考資料

API 文件

相關 PR


FlutterDriver.enableAccessibility

#

包:flutter_driver 支援 Flutter Fix:是

flutterDriverenableAccessibility 方法在 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:是

TimelineSummarywriteSummaryToFile 方法在 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 以及 TextSelectionControllerSelectableRegionState 的部分內容,在本週期內並未移除,以便為遷移提供更多時間。預計這些棄用將在下一個週期中移除,屆時將再次宣佈。


時間線

#

穩定版本: 3.22.0