v2.10 之後移除的已棄用 API

根據 Flutter 的 棄用政策， 在 2.10 穩定版發佈後達到生命週期終止的 已棄用 API 已被移除。

所有受影響的 API 已彙整於此主來源文件， 以協助遷移作業。同時也提供了 快速參考表。

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

Flutter Fix 支援：是

maxLengthEnforced 在 v1.25 時已被棄用。

請改用 maxLengthEnforcement。 若 maxLengthEnforced 為 true，請替換為 MaxLengthEnforcement.enforce。 若 maxLengthEnforced 為 false，請替換為 MaxLengthEnforcement.none。 此變更允許指定更多行為，超越原本的二元選項， 並新增了 MaxLengthEnforcement.truncateAfterCompositionEnds 作為 額外選項。

以下類別皆有相同的 API 變更：

• TextField
• TextFormField
• CupertinoTextField

遷移指南

提供詳細遷移指南

遷移前的程式碼：

const TextField textField = TextField(maxLengthEnforced: true);
const TextField textField = TextField(maxLengthEnforced: false);
final lengthEnforced = textField.maxLengthEnforced;
​
const TextFormField textFormField = TextFormField(maxLengthEnforced: true);
const TextFormField textFormField = TextFormField(maxLengthEnforced: false);
final lengthEnforced = textFormField.maxLengthEnforced;
​
const CupertinoTextField cupertinoTextField = CupertinoTextField(maxLengthEnforced: true);
const CupertinoTextField cupertinoTextField = CupertinoTextField(maxLengthEnforced: false);
final lengthEnforced = cupertinoTextField.maxLengthEnforced;

遷移後的程式碼：

const TextField textField = TextField(maxLengthEnforcement: MaxLengthEnforcement.enforce);
const TextField textField = TextField(maxLengthEnforcement: MaxLengthEnforcement.none);
final lengthEnforced = textField.maxLengthEnforcement;
​
const TextFormField textFormField = TextFormField(maxLengthEnforcement: MaxLengthEnforcement.enforce);
const TextFormField textFormField = TextFormField(maxLengthEnforcement: MaxLengthEnforcement.none);
final lengthEnforced = textFormField.maxLengthEnforcement;
​
const CupertinoTextField cupertinoTextField = CupertinoTextField(maxLengthEnforcement: MaxLengthEnforcement.enforce);
const CupertinoTextField cupertinoTextField = CupertinoTextField(maxLengthEnforcement: MaxLengthEnforcement.none);
final lengthEnforced = cupertinoTextField.maxLengthEnforcement;

參考資料

API 文件：

• TextField
• TextFormField
• CupertinoTextField

相關議題：

• Issue 67898

相關 PR：

• 已在 #68086 標記為已淘汰
• 已在 #98539 移除

Flutter Fix 支援：是

VelocityTracker 的預設建構函式自 v1.22 起已被標記為已淘汰。

建議改用 VelocityTracker.withKind()。這樣可以為追蹤器指定 PointerDeviceKind。先前 VelocityTracker.kind 的預設值為 PointerDeviceKind.touch。

遷移指南

遷移前的程式碼：

final VelocityTracker tracker = VelocityTracker();

遷移後的程式碼：

final VelocityTracker tracker = VelocityTracker.withKind(PointerDeviceKind.touch);

參考資料

API 文件：

• VelocityTracker
• PointerDeviceKind

相關 PR：

• 已於 #66043 標記為不建議使用（Deprecated）
• 已於 #98541 移除

Flutter Fix 是否支援：否

DayPicker 和 MonthPicker 元件（Widgets）首次於 v1.15 標記為不建議使用（Deprecated），並於 v1.26 延長支援。

這些元件已由一個更完整的元件 CalendarDatePicker 取代。

這些元件原本是透過 showDatePicker 方法顯示。在本次版本之前，該方法已遷移為顯示新的 CalendarDatePicker，因此最終移除這些元件時，通常不需要額外處理。

參考資料

設計文件：

• Material Date Picker Redesign

API 文件：

• CalendarDatePicker
• showDatePicker

相關議題：

• Issue 50133

相關 PR：

• 已於 #50546 標記為不建議使用（Deprecated）
• 已於 #98543 移除

Flutter Fix 是否支援：否

FlatButton、RaisedButton 和 OutlineButton 元件（Widgets）首次於 v1.20 標記為不建議使用（Deprecated），並於 v1.26 延長支援。

這些元件已由新按鈕 TextButton、ElevatedButton 和 OutlinedButton 取代。這些新元件也採用了新的專屬主題，而非通用的 ButtonTheme。

遷移指南

提供詳細樣式的完整遷移指南

遷移前的程式碼：

FlatButton(
  onPressed: onPressed,
  child: Text('Button'),
  // ...
);
​
RaisedButton(
  onPressed: onPressed,
  child: Text('Button'),
  // ...
);
​
OutlineButton(
  onPressed: onPressed,
  child: Text('Button'),
  // ...
);

遷移後的程式碼：

TextButton(
  onPressed: onPressed,
  child: Text('Button'),
  // ...
);
​
ElevatedButton(
  onPressed: onPressed,
  child: Text('Button'),
  // ...
);
​
OutlinedButton(
  onPressed: onPressed,
  child: Text('Button'),
  // ...
);

參考資料

設計文件：

• New Material buttons and themes

API 文件：

• ButtonStyle
• ButtonStyleButton
• ElevatedButton
• ElevatedButtonTheme
• ElevatedButtonThemeData
• OutlinedButton
• OutlinedButtonTheme
• OutlinedButtonThemeData
• TextButton
• TextButtonTheme
• TextButtonThemeData

相關 PR：

• 新增 API 於 #59702
• 已棄用於 #73352
• 已移除於 #98546

Flutter Fix 是否支援：否

以下 Scaffold SnackBar 方法已於 v1.23 棄用。

• showSnackBar
• removeCurrentSnackBar
• hideCurrentSnackBar

請改為使用 ScaffoldMessenger 中同名的方法。每個 MaterialApp 已經預設建立了一個 ScaffoldMessenger。

遷移指南

有詳細的遷移指南可參考

遷移前的程式碼：

Scaffold.of(context).showSnackBar(mySnackBar);
Scaffold.of(context).removeCurrentSnackBar(mySnackBar);
Scaffold.of(context).hideCurrentSnackBar(mySnackBar);

遷移後的程式碼：

ScaffoldMessenger.of(context).showSnackBar(mySnackBar);
ScaffoldMessenger.of(context).removeCurrentSnackBar(mySnackBar);
ScaffoldMessenger.of(context).hideCurrentSnackBar(mySnackBar);

參考資料

設計文件：

• ScaffoldMessenger Design

影片內容：

• SnackBar Delivery
• Widget of the Week

API 文件：

• ScaffoldMessenger
• SnackBar

相關議題：

• Issue 57218
• Issue 62921

相關 PR：

• 新 API 於 #64101 新增
• 於 #67947 標記為已淘汰
• 於 #98549 移除

Flutter Fix 支援：是

RectangularSliderTrackShape.disabledThumbGapWidth 首次於 v1.5 標記為已淘汰，並於 v1.26 擴展。

此功能已不再由框架使用，因為當滑桿（slider）停用時，滑塊（thumb）的動畫（Animation）不再發生。

遷移指南

遷移前的程式碼：

RectangularSliderTrackShape(disabledThumbGapWidth: 2.0);

遷移後的程式碼：

RectangularSliderTrackShape();

參考資料

API 文件：

• RectangularSliderTrackShape

相關 PR：

• 動畫 (Animation) 變更於 #30390
• 已於 #65246 標記為不建議使用（Deprecated）
• 已於 #98613 移除

支援 Flutter Fix：是

以下 ThemeData 成員最初於 v1.23 標記為不建議使用，並於 v1.26 擴充。

• useTextSelectionTheme
• textSelectionColor
• cursorColor
• textSelectionHandleColor

這些應該被更完整的 TextSelectionThemeData 取代，該內容現在已在 ThemeData 本身中指定。

useTextSelectionTheme 旗標曾作為臨時遷移用來區分兩個 API，現在可以移除了。

遷移指南

提供詳細遷移指南

遷移前的程式碼：

ThemeData(
  useTextSelectionTheme: false,
  textSelectionColor: Colors.blue,
  cursorColor: Colors.green,
  textSelectionHandleColor: Colors.red,
);

遷移後的程式碼：

ThemeData(
  textSelectionTheme: TextSelectionThemeData(
    selectionColor: Colors.blue,
    cursorColor: Colors.green,
    selectionHandleColor: Colors.red,
  ),
);

參考資料

設計文件：

• Text Selection Theme

API 文件：

• ThemeData
• TextSelectionThemeData

相關議題：

• Issue 17635
• Issue 56082
• Issue 61227

相關 PR：

• 新 API 於 #62014 新增
• 於 #66485 標記為已淘汰（Deprecated）
• 於 #98578 移除

Flutter Fix 支援：否

RenderEditable.onSelectionChanged 和 TextSelectionDelegate.textEditingValue 自 v1.26 起已被標記為淘汰（deprecated）。

請改為呼叫 TextSelectionDelegate.userUpdateTextEditingValue，以取代上述一或兩個方法。這樣可以修正 TextInputFormatter 取得錯誤選取值的錯誤。

遷移指南

遷移前的程式碼：

renderEditable.onSelectionChanged(selection, renderObject, cause);
textSelectionDelegate.textEditingValue = value;

遷移後的程式碼：

textSelectionDelegate.userUpdateTextEditingValue(value, cause);

參考資料

API 文件：

• RenderEditable
• TextSelectionDelegate

相關議題：

• 已解決 #75505

相關 PR：

• 已在 #75541 標記為已淘汰
• 已在 #98582 移除

Flutter Fix 支援：是

Stack.overflow 以及 Overflow 列舉（enum）已於 v1.22 被標記為已淘汰。

建議替代方案為 Stack.clipBehavior，此更動是為了統一整個框架中的剪裁（clip）行為與語意。原本使用 Overflow.visible 的地方，請改用 Clip.none。原本使用 Overflow.clip 的地方，請改用 Clip.hardEdge。

遷移指南

提供詳細遷移指南

遷移前的程式碼：

const Stack stack = Stack(overflow: Overflow.visible);
const Stack stack = Stack(overflow: Overflow.clip);

遷移後的程式碼：

const Stack stack = Stack(clipBehavior: Clip.none);
const Stack stack = Stack(clipBehavior: Clip.hardEdge);

參考資料

API 文件：

• Stack
• Clip

相關議題：

• 已解決 #66030

相關 PR：

• 已在 #66305 標記為過時
• 已在 #98583 移除

Flutter Fix 支援：否

SemanticsEvent UpdateLiveRegionEvent，最初於 v1.12 標記為過時， 並於 v1.26 延長。

此功能從未由框架實作，任何相關參考都應該移除。

參考資料

API 文件：

• SemanticsEvent

相關 PR：

• 已在 #45940 標記為過時
• 已在 #98615 移除

Flutter Fix 支援：是

以下 RenderObjectElement 方法已於 v1.21 標記為過時。

• insertChildRenderObject
• moveChildRenderObject
• removeChildRenderObject

這些方法分別被以下方法取代：

• insertRenderObjectChild
• moveRenderObjectChild
• removeRenderObjectChild

這些變更屬於軟性不相容的棄用（soft breaking deprecation）， 目的是為了調整函式簽章（function signature）。

遷移指南

遷移前的程式碼：

element.insertChildRenderObject(child, slot);
element.moveChildRenderObject(child, slot);
element.removeChildRenderObject(child);

遷移後的程式碼：

element.insertRenderObjectChild(child, slot);
element.moveRenderObjectChild(child, oldSlot, newSlot);
element.removeRenderObjectChild(child, slot);

參考資料

API 文件：

• RenderObjectElement

相關議題：

• Issue 63269

相關 PR：

• 已在 #64254 標記為已淘汰
• 已在 #98616 移除

於正式版本：3.0.0