移除 nullOk 參數

本遷移指南說明如何轉換程式碼，該程式碼在多個 of 靜態存取器和相關存取器上使用 nullOk 參數，以使用具有可為 null 傳回值的替代 API。

Flutter 有一個常見模式，允許使用通常稱為 of 的靜態成員函式，並採用 BuildContext 來查閱某些類型的 Widget (InheritedWidget)。

在預設為非可空性 (non-nullability) 之前，這些 API 上有一個切換選項很有用，它可以在 Widget 沒有出現在 Widget 樹狀結構中時拋出例外，或者在找不到 Widget 時返回 null。這很有用，而且不會造成混淆，因為每個變數都是可空的 (nullable)。

當非可空性成為預設時，就希望最常用的 API 返回非可空的值。因為寫成 MediaQuery.of(context, nullOk: false)，然後仍然需要在呼叫後使用 ! 運算子或 ? 以及回退值，感覺很彆扭。

nullOk 參數提供了一種廉價的空安全切換形式，但在語言真正支援非可空性的情況下，它就提供了冗餘，甚至可能與開發人員產生矛盾的訊號。

為了解決這個問題，of 存取器（以及一些也使用 nullOk 的相關存取器）被拆分為兩個呼叫：一個返回非可空的值，並且在找不到所尋找的 Widget 時拋出例外；另一個返回可空的值，不拋出例外，並且在 Widget 不存在時返回 null。

此變更的設計文件是 消除 nullOk 參數。

實際的變更修改了這些 API，使其不再具有 nullOk 參數，並且返回非可空的值。

• MediaQuery.of
• Navigator.of
• ScaffoldMessenger.of
• Scaffold.of
• Router.of
• Localizations.localeOf
• FocusTraversalOrder.of
• FocusTraversalGroup.of
• Focus.of
• Shortcuts.of
• Actions.handler
• Actions.find
• Actions.invoke
• AnimatedList.of
• SliverAnimatedList.of
• CupertinoDynamicColor.resolve
• CupertinoDynamicColor.resolveFrom
• CupertinoUserInterfaceLevel.of
• CupertinoTheme.brightnessOf
• CupertinoThemeData.resolveFrom
• NoDefaultCupertinoThemeData.resolveFrom
• CupertinoTextThemeData.resolveFrom
• MaterialBasedCupertinoThemeData.resolveFrom

並引入了這些新的 API，以返回可空的值。

• MediaQuery.maybeOf
• Navigator.maybeOf
• ScaffoldMessenger.maybeOf
• Scaffold.maybeOf
• Router.maybeOf
• Localizations.maybeLocaleOf
• FocusTraversalOrder.maybeOf
• FocusTraversalGroup.maybeOf
• Focus.maybeOf
• Shortcuts.maybeOf
• Actions.maybeFind
• Actions.maybeInvoke
• AnimatedList.maybeOf
• SliverAnimatedList.maybeOf
• CupertinoDynamicColor.maybeResolve
• CupertinoUserInterfaceLevel.maybeOf
• CupertinoTheme.maybeBrightnessOf

為了修改您的程式碼以使用新形式的 API，請將所有包含 nullOk = true 作為參數的呼叫實例，改為使用 API 的 maybe 形式。

所以這個

MediaQueryData? data = MediaQuery.of(context, nullOk: true);

變成

MediaQueryData? data = MediaQuery.maybeOf(context);

您還需要修改所有以 nullOk = false（通常是預設值）呼叫 API 的實例，以接受非可空的返回值，或移除任何 ! 運算子。

所以以下兩者

MediaQueryData data = MediaQuery.of(context)!; // nullOk false by default.
MediaQueryData? data = MediaQuery.of(context); // nullOk false by default.

都變成

MediaQueryData data = MediaQuery.of(context); // No ! or ? operator here now.

unnecessary_non_null_assertion 分析選項對於找出應該移除 ! 運算子的地方非常有用，而 unnecessary_nullable_for_final_variable_declarations 分析選項對於找出 final 和 const 變數上不必要問號運算子的情況很有幫助。

已於版本中發布：1.24.0
在穩定版本中：2.0.0

API 文件

• MediaQuery.of
• Navigator.of
• ScaffoldMessenger.of
• Scaffold.of
• Router.of
• Localizations.localeOf
• FocusTraversalOrder.of
• FocusTraversalGroup.of
• Focus.of
• Shortcuts.of
• Actions.handler
• Actions.find
• Actions.invoke
• AnimatedList.of
• SliverAnimatedList.of
• CupertinoDynamicColor.resolve
• CupertinoDynamicColor.resolveFrom
• CupertinoUserInterfaceLevel.of
• CupertinoTheme.brightnessOf
• CupertinoThemeData.resolveFrom
• NoDefaultCupertinoThemeData.resolveFrom
• CupertinoTextThemeData.resolveFrom
• MaterialBasedCupertinoThemeData.resolveFrom
• MediaQuery.maybeOf
• Navigator.maybeOf
• ScaffoldMessenger.maybeOf
• Scaffold.maybeOf
• Router.maybeOf
• Localizations.maybeLocaleOf
• FocusTraversalOrder.maybeOf
• FocusTraversalGroup.maybeOf
• Focus.maybeOf
• Shortcuts.maybeOf
• Actions.maybeFind
• Actions.maybeInvoke
• AnimatedList.maybeOf
• SliverAnimatedList.maybeOf
• CupertinoDynamicColor.maybeResolve
• CupertinoUserInterfaceLevel.maybeOf
• CupertinoTheme.maybeBrightnessOf

相關議題

• 議題 68637

相關 PR

• 移除 MediaQuery.of 中的 nullOk
• 移除 Navigator.of 中的 nullOk
• 從 AnimatedList.of 和 SliverAnimatedList.of 中移除 nullOk 參數
• 從 Shortcuts.of、Actions.find 和 Actions.handler 中移除 nullOk 參數
• 從 Focus.of、FocusTraversalOrder.of 和 FocusTraversalGroup.of 中移除 nullOk 參數
• 從 Localizations.localeOf 中移除 nullOk 參數
• 從 Router.of 中移除 nullOk 參數
• 從 Scaffold.of 和 ScaffoldMessenger.of 中移除 nullOk
• 從 Cupertino 顏色解析 API 中移除 nullOk 參數
• 從 Localizations.localeOf 中移除殘留的 nullOk 參數
• 從 Actions.invoke 中移除 nullOk，新增 Actions.maybeInvoke

除非另有說明，否則本網站上的文件反映了 Flutter 的最新穩定版本。頁面上次更新於 2024-04-04。 檢視原始碼 或 回報問題。