v1.22 之後移除的已棄用 API

根據 Flutter 的 棄用政策， 在 1.22 穩定版發布後達到生命週期終止的已棄用 API 已被移除。 這是 Flutter 首次移除已棄用的 API， 其中部分棄用甚至早於我們的 遷移指南政策。

所有受影響的 API 都已彙整於此 主要來源文件，以協助遷移。 另有快速參考表可供查閱。

如需更多關於 Flutter 棄用政策的背景說明，請參考設計文件與文章。

本節將依受影響的類別列出所有棄用項目。

支援修正工具：僅限 IDE 修正。

CupertinoDialog 已於 v0.2.3 棄用。 請改用 CupertinoAlertDialog 或 CupertinoPopupSurface。

遷移指南

CupertinoAlertDialog

遷移前的程式碼：

CupertinoDialog(child: myWidget);

遷移後的程式碼：

CupertinoAlertDialog(content: myWidget);

CupertinoPopupSurface

遷移前的程式碼：

CupertinoDialog(child: myWidget);

遷移後的程式碼：

CupertinoPopupSurface(child: myWidget);

參考資料

API 文件：

• CupertinoAlertDialog
• CupertinoPopupSurface

相關議題：

• Deprecate CupertinoDialog class

相關 PR：

• 已在 #20649 標記為過時
• 已在 #73604 移除

支援修正工具：否

CupertinoNavigationBar.actionsForegroundColor 和 CupertinoSliverNavigationBar.actionsForegroundColor 自 v1.1.2 起已被標記為過時。 現在請在 CupertinoTheme 中設定 primaryColor 來傳遞此屬性。 若要存取 primaryColor， 請呼叫 CupertinoTheme.of(context).primaryColor。

遷移指南

遷移前的程式碼：

CupertinoNavigationBar(
  actionsForegroundColor: CupertinoColors.systemBlue,
);
CupertinoSliverNavigationBar(
  actionsForegroundColor: CupertinoColors.systemBlue,
);

遷移後的程式碼：

CupertinoTheme(
  data: CupertinoThemeData(
    primaryColor: CupertinoColors.systemBlue
  ),
  child: ...
);
​
// To access the color from the `CupertinoTheme`
CupertinoTheme.of(context).primaryColor;

參考資料

API 文件：

• CupertinoNavigationBar
• CupertinoSliverNavigationBar
• CupertinoTheme
• CupertinoThemeData

相關議題：

• Create a CupertinoApp and a CupertinoTheme

相關 PR：

• 在 #23759 中標記為已淘汰
• 在 #73745 中移除

支援修正工具：是

CupertinoTextThemeData.brightness 已於 v1.10.14 標記為已淘汰（deprecated）。 此欄位成員在標記為已淘汰時即已無效。 此參數沒有替代方案，應將相關引用移除。

遷移指南

遷移前的程式碼：

const CupertinoTextThemeData themeData = CupertinoTextThemeData(brightness: Brightness.dark);
themeData.copyWith(brightness: Brightness.light);

遷移後的程式碼：

const CupertinoTextThemeData themeData = CupertinoTextThemeData();
themeData.copyWith();

參考資料

API 文件：

• CupertinoTextThemeData

相關議題：

• Revise CupertinoColors and CupertinoTheme for dynamic colors

相關 PR：

• 已在 #41859 標記為過時
• 已在 #72017 移除

支援修正工具：是

fromHoverEvent 的建構函式（constructors）在 PointerEnterEvent 和 PointerExitEvent 已於 v1.4.3 標記為過時。 建議改用 fromMouseEvent 建構函式。

遷移指南

遷移前的程式碼：

final PointerEnterEvent enterEvent = PointerEnterEvent.fromHoverEvent(PointerHoverEvent());
final PointerExitEvent exitEvent = PointerExitEvent.fromHoverEvent(PointerHoverEvent());

遷移後的程式碼：

final PointerEnterEvent enterEvent = PointerEnterEvent.fromMouseEvent(PointerHoverEvent());
final PointerExitEvent exitEvent = PointerExitEvent.fromMouseEvent(PointerHoverEvent());

參考資料

API 文件：

• PointerEnterEvent
• PointerExitEvent

相關議題：

• PointerEnterEvent and PointerExitEvent can only be created from hover events

相關 PR：

• 已在 #28602 標記為不建議使用
• 已在 #72395 移除

支援修正工具：是

showDialog 的 child 參數已於 v0.2.3 標記為不建議使用。 應改用 builder 參數。

遷移指南

遷移前的程式碼：

showDialog(child: myWidget);

遷移後的程式碼：

showDialog(builder: (context) => myWidget);

參考資料

API 文件：

• showDialog

相關議題：

• showDialog should take a builder rather than a child

相關 PR：

• 在 #15303 中標記為已淘汰
• 在 #72532 中移除

支援修正工具：是

Scaffold 的 resizeToAvoidBottomPadding 參數自 v1.1.9 起已被淘汰。 請改用 resizeToAvoidBottomInset 參數。

遷移指南

遷移前的程式碼：

Scaffold(resizeToAvoidBottomPadding: true);

遷移後的程式碼：

Scaffold(resizeToAvoidBottomInset: true);

參考資料

API 文件：

• Scaffold

相關議題：

• Show warning when nesting Scaffolds
• SafeArea with keyboard
• Double stacked material scaffolds shouldn't double resizeToAvoidBottomPadding
• viewInsets and padding on Window and MediaQueryData should define how they interact
• bottom overflow issue, when using textfields inside tabbarview

相關 PR：

• 在 #26259 中標記為已淘汰
• 在 #72890 中移除

支援修正工具：否

ButtonTheme 的 bar 建構函式已於 v1.9.1 被標記為已淘汰（deprecated）。 針對 ButtonBar，可以改用 ButtonBarTheme， 若用途不限於 ButtonBar，也可使用 ButtonTheme 的其他建構函式。

針對按鈕的主題化（theming），也可使用 TextButtonTheme、 ElevatedButtonTheme 和 OutlinedButtonTheme 類別， 它們分別對應到相應的按鈕類別， TextButton、ElevatedButton 和 OutlinedButton。

遷移指南

遷移前的程式碼：

ButtonTheme.bar(
  minWidth: 10.0,
  alignedDropdown: true,
  height: 40.0,
);

遷移後的程式碼，使用 ButtonTheme：

ButtonTheme(
  minWidth: 10.0,
  alignedDropdown: true,
  height: 40.0,
);

遷移後，使用 ButtonBarTheme 的程式碼：

ButtonBarTheme(
  data: ButtonBarThemeData(
    buttonMinWidth: 10.0,
    buttonAlignedDropdown: true,
    buttonHeight: 40.0,
  )
);

參考資料

API 文件：

• ButtonTheme
• ButtonBarTheme
• ButtonBar
• TextButtonTheme
• TextButton
• ElevatedButtonTheme
• ElevatedButton
• OutlinedButtonTheme
• OutlinedButton

相關議題：

• ButtonTheme.bar uses accent color when it should be using primary color
• ThemeData.accentColor has insufficient contrast for text
• Increased height as a result of changes to materialTapTargetSize affecting AlertDialog/ButtonBar heights

相關 PR：

• 於 #37544 標記為已淘汰
• 於 #73746 移除

支援修正工具：否

以下方法在 InlineSpan、TextSpan 及 PlaceholderSpan 中被標記為已淘汰， 以支援將元件（Widgets）內嵌於段落中，例如圖片。

遷移指南

參考資料

API 文件：

• InlineSpan
• TextSpan
• PlaceholderSpan
• WidgetSpan

相關議題：

• Text: support inline images

相關 PR：

• 開發歷程：
  • #30069
  • #33946
  • #33794
• 於 #34051 標記為已淘汰
• 於 #73747 移除

支援修正工具：否

RenderView.scheduleInitialFrame 方法已被標記為淘汰並移除， 以避免啟動畫面（splash screen）過早被移除， 導致出現黑畫面。 當呼叫 WidgetsFlutterBinding.ensureInitialized 時會發生此問題。 請改為使用 RenderView.prepareInitialFrame， 並接著呼叫 RenderView.owner.requestVisualUpdate 來取代此方法。

遷移指南

遷移前的程式碼：

scheduleInitialFrame();

遷移後的程式碼：

prepareInitialFrame();
owner.requestVisualUpdate();

參考資料

API 文件：

• RenderView
• WidgetsFlutterBinding

相關議題：

• WidgetsFlutterBinding.ensureInitialized() takes down splash screen too early

相關 PR：

• 已在 #39535 標記為過時
• 已在 #73748 移除

支援修正工具：否

Layer.findAll 方法在引入 Layer.findAnnotations 時被標記為過時， 目的是統一 find 與 findAll 的實作方式。 若要遷移受影響的程式碼，請改為呼叫 findAllAnnotations。 此方法會回傳一個 AnnotationResult，其中包含原本 findAll 在 AnnotationResult.annotations 中的回傳值。

遷移指南

遷移前的程式碼：

findAll(offset);

遷移後的程式碼：

findAllAnnotations(offset).annotations;

參考資料

API 文件：

• Layer
• MouseRegion
• RenderMouseRegion
• AnnotatedRegionLayer
• AnnotationResult

相關議題：

• Breaking Proposal: MouseRegion defaults to opaque; Layers are required to implement findAnnotations

相關 PR：

• 最初變更於 #37896
• 棄用於 #42953
• 移除於 #73749

支援修正工具：否

BinaryMessages 類別、其相關的靜態方法以及 defaultBinaryMessenger getter 已被棄用並移除。defaultBinaryMessenger 實例已移至 ServicesBinding。這使得在測試環境下，可以註冊不同的預設 BinaryMessenger，只需為測試建立 ServicesBinding 子類別即可。這樣做可以讓你追蹤待處理平台訊息的數量，以利同步用途。

遷移指南

參考資料

API 文件：

• ServicesBinding
• BinaryMessenger

相關議題：

• Flutter synchronization support for Espresso/EarlGrey

相關 PR：

• 最初變更於 #37489
• 棄用於 #38464
• 移除於 #73750

支援修正工具：是

BuildContext 中有多個方法使用 Type 來搜尋祖先。這些方法大多在呼叫端需要進行型別轉換，因為它們的回傳型別是父類型。此外，即使型別實際上有限制，分析時也不會檢查所提供的型別。將這些方法改為泛型後，能提升型別安全性並減少程式碼量。

這些方法的變更會影響 BuildContext、Element 和 StatefulElement 類別。TypeMatcher 類別也已被移除。

遷移指南

遷移前程式碼：

ComplexLayoutState state = context.ancestorStateOfType(const TypeMatcher<ComplexLayoutState>()) as ComplexLayoutState;

遷移後的程式碼：

ComplexLayoutState state = context.ancestorStateOfType<ComplexLayoutState>();

BuildContext

Element

StatefulElement

參考資料

API 文件：

• Type
• BuildContext
• Element
• StatefulElement

相關 PR：

• 在 #44189 中標記為已淘汰
• 已於以下 PR 移除：
  • #69620
  • #72903
  • #72901
  • #73751

支援修正工具：是

WidgetsBinding 的 deferFirstFrameReport 和 allowFirstFrameReport 方法 已被標記為淘汰並移除，以便提供延遲首次繪製畫面的選項。 這對於需要非同步取得初始化資訊的元件（Widgets）非常有用， 在等待這些資訊的期間，不應繪製任何畫面，否則會導致啟動畫面過早消失。 請分別改用 deferFirstFrame 和 allowFirstFrame 方法。

遷移指南

遷移前的程式碼：

final WidgetsBinding binding = WidgetsBinding.instance;
binding.deferFirstFrameReport();
binding.allowFirstFrameReport();

遷移後的程式碼：

final WidgetsBinding binding = WidgetsBinding.instance;
binding.deferFirstFrame();
binding.allowFirstFrame();

參考資料

API 文件：

• WidgetsBinding

相關 PR：

• 最初變更於
  • #45135
  • #45588
• 在 #45941 標記為已淘汰
• 在 #72893 移除

支援修正工具：否

flutter_driver 套件中的 WaitUntilNoTransientCallbacks、WaitUntilNoPendingFrame 和 WaitUntilFirstFrameRasterized 方法已被標記為已淘汰並移除，以提供更具組合性的 waitForCondition API，讓用戶端能夠自行組合想要等待的條件。

遷移指南

參考資料

API 文件：

• WaitForCondition

相關議題：

• Flutter synchronization support for Espresso/EarlGrey

相關 PR：

• 最初變更於 #37736
• 在 #38836 標記為已淘汰
• 在 #73754 移除

穩定版發佈：2.0.0