消除 nullOk 参数
概述
#本迁移指南描述了如何将使用多个 of
静态访问器和相关访问器上的 nullOk
参数的代码转换为使用带有可空返回值的替代 API。
背景
#Flutter 有一种常见模式,即允许使用通常称为 of
的静态成员函数(并接收 BuildContext
)查找某些类型的组件(InheritedWidget
)。
在非空安全成为默认设置之前,这些 API 上有一个开关非常有用,该开关可以在组件未在组件树中时抛出异常和未找到时返回 null 之间切换。这很有用,并且不令人困惑,因为每个变量都是可空的。
当非空安全成为默认设置时,最常用的 API 返回非空值变得合乎需要。这是因为在调用 MediaQuery.of(context, nullOk: false)
后仍然需要 !
运算符或 ?
以及备用值会让人觉得很别扭。
nullOk
参数是提供空安全开关的一种廉价形式,而在真正支持非空安全的情况下,它向开发者提供了冗余甚至可能矛盾的信号。
为了解决这个问题,of
访问器(以及一些也使用 nullOk
的相关访问器)被拆分为两个调用:一个返回非空值并在找不到目标组件时抛出异常;另一个返回可空值,不抛出异常,并在找不到组件时返回 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
相关议题
相关 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