移除 nullOk 引數

本遷移指南描述瞭如何將使用多個 of 靜態訪問器及相關訪問器上的 nullOk 引數的程式碼，轉換為使用具有可空返回值的備用 API。

Flutter 中有一種常見的模式，即允許使用靜態成員函式（通常稱為 of）來查詢某些型別的 widget（InheritedWidget），這些函式需要一個 BuildContext。

在非空性成為預設設定之前，這些 API 上有一個開關很有用，可以在 widget 不存在於 widget 樹中時丟擲異常，或者在未找到 widget 時返回 null。這很有用，而且不令人困惑，因為當時每個變數都是可空的。

當非空性成為預設設定後，就希望最常用的 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 呼叫，轉換為使用 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