Eliminación de parámetros nullOk

Esta guía de migración describe la conversión de código que utiliza el parámetro nullOk en múltiples accesores estáticos of y accesores relacionados para utilizar APIs alternativas con valores de retorno nullables.

Flutter tiene un patrón común de permitir la búsqueda de algunos tipos de widgets (InheritedWidgets) utilizando funciones miembro estáticas que típicamente se llaman of, y reciben un BuildContext.

Antes de que la no nulabilidad fuera la opción por defecto, era útil tener un interruptor en estas APIs que alternara entre lanzar una excepción si el widget no estaba presente en el árbol de widgets y retornar null si no se encontraba. Era útil y no resultaba confuso, ya que cada variable admitía nulos.

Cuando la no nulabilidad se convirtió en la opción por defecto, pasó a ser deseable que las APIs más utilizadas retornaran un valor que no admitiera nulos. Esto se debe a que decir MediaQuery.of(context, nullOk: false) y aun así requerir un operador ! o ? y un valor de respaldo después de esa llamada resultaba incómodo.

El parámetro nullOk era una forma económica de proporcionar un interruptor de null safety, que ante el soporte real del lenguaje para la no nulabilidad, estaba proporcionando señales redundantes y quizás contradictorias al desarrollador.

Para resolver esto, los accesores of (y algunos accesores relacionados que también usaban nullOk) se dividieron en dos llamadas: una que retorna un valor no nullable y lanza una excepción cuando el widget buscado no está presente, y otra que retorna un valor nullable que no lanza una excepción y retorna null si el widget no está presente.

El documento de diseño para este cambio es Eliminating nullOk parameters.

El cambio real modificó estas APIs para no tener un parámetro nullOk y para retornar un valor que no admite nulos:

• 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

Y se introdujeron estas nuevas APIs junto a aquellas, para retornar un valor nullable:

• 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

Para modificar tu código y usar la nueva forma de las APIs, convierte todas las instancias de llamadas que incluyan nullOk = true como parámetro para usar la forma maybe de la API en su lugar.

Así que esto:

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

se convierte en:

MediaQueryData? data = MediaQuery.maybeOf(context);

También necesitas modificar todas las instancias de llamadas a la API con nullOk = false (que suele ser el valor por defecto), para aceptar valores de retorno no nullables, o eliminar cualquier operador !:

Así que cualquiera de estos:

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

ambos se convierten en:

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

La opción de análisis unnecessary_non_null_assertion puede ser muy útil para encontrar los lugares donde se debe eliminar el operador !, y la opción de análisis unnecessary_nullable_for_final_variable_declarations puede ser útil para encontrar operadores de signo de interrogación innecesarios en variables final y const variables.

Lanzado en la versión: 1.24.0
En versión estable: 2.0.0

Documentación de la 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

Problema relevante:

• Issue 68637

PRs relevantes:

• Eliminar nullOk en MediaQuery.of
• Eliminar nullOk en Navigator.of
• Eliminar el parámetro nullOk de AnimatedList.of y SliverAnimatedList.of
• Eliminar el parámetro nullOk de Shortcuts.of, Actions.find, y Actions.handler
• Eliminar el parámetro nullOk de Focus.of, FocusTraversalOrder.of, y FocusTraversalGroup.of
• Eliminar el parámetro nullOk de Localizations.localeOf
• Eliminar el parámetro nullOk de Router.of
• Eliminar nullOk de Scaffold.of y ScaffoldMessenger.of
• Eliminar el parámetro nullOk de las APIs de resolución de color de Cupertino
• Eliminar el parámetro vestigial nullOk de Localizations.localeOf
• Eliminar nullOk de Actions.invoke, agregar Actions.maybeInvoke