Usar el Flutter inspector

Para obtener información sobre cómo ubicar las pantallas de DevTools en diferentes IDEs, consulta la visión general de DevTools.

El Flutter widget inspector es una herramienta potente para visualizar y explorar árboles de Widgets de Flutter. El framework Flutter usa Widgets como el bloque de construcción principal para cualquier cosa, desde controles (como texto, botones y conmutadores), hasta diseño (como centrado, padding, filas y columnas). El inspector te ayuda a visualizar y explorar los árboles de Widgets de Flutter, y se puede usar para lo siguiente:

• entender diseños existentes
• diagnosticar problemas de diseño

Como parte de Flutter 3.29, el nuevo Flutter inspector está habilitado por defecto. Sin embargo, se puede deshabilitar desde el diálogo de configuración del inspector.

La siguiente es una guía de las funciones disponibles en la barra de herramientas del inspector. Cuando el espacio es limitado, el ícono se usa como la versión visual de la etiqueta.

Modo seleccionar Widget

Habilita este botón para seleccionar un Widget en el dispositivo para inspeccionarlo. Para obtener más información, consulta Inspeccionar un Widget.

Mostrar Widgets de implementación

Habilita este botón para mostrar Widgets de implementación en el árbol de Widgets. Para obtener más información, consulta Usar el Widget Tree.

Actualizar árbol

Recargar la información del Widget actual.

Animaciones lentas

Ejecutar animaciones 5 veces más lento para ayudar a afinarlas.

Mostrar guías

Superponer guías para ayudar a solucionar problemas de diseño.

Mostrar líneas base

Muestra líneas base, que se usan para alinear texto. Puede ser útil para verificar si el texto está alineado.

Resaltar redibujados (repaints)

Muestra bordes que cambian de color cuando los elementos se redibujan. Útil para encontrar redibujados innecesarios.

Resaltar imágenes de tamaño excesivo

Resalta imágenes que están usando demasiada memoria invirtiendo los colores y volteándolas.

Puedes explorar el árbol interactivo de Widgets para ver Widgets cercanos y revisar sus valores de campo.

Para localizar elementos individuales de la UI en el árbol de Widgets, haz clic en el botón Modo seleccionar Widget en la barra de herramientas. Esto pone la aplicación en el dispositivo en un modo "selección de Widget". Haz clic en cualquier Widget en la UI de la aplicación; esto selecciona el Widget en la pantalla de la aplicación y desplaza el árbol de Widgets al nodo correspondiente. Vuelve a alternar el botón Modo seleccionar Widget para salir del modo selección de Widget.

Al depurar problemas de diseño, los campos clave a mirar son los campos size y constraints. Las restricciones fluyen hacia abajo en el árbol, y los tamaños fluyen hacia arriba. Para obtener más información sobre cómo funciona esto, consulta Entender las restricciones.

El Flutter Widget Tree te permite visualizar, entender y navegar el árbol de Widgets de tu aplicación.

Por defecto, el Flutter Widget Tree incluye todos los Widgets creados en el directorio raíz de tu proyecto.

Las relaciones padre-hijo de los Widgets están representadas por una sola línea vertical (si el Widget padre solo tiene un hijo) o a través de sangría (si el Widget padre tiene múltiples hijos).

Por ejemplo, para la siguiente sección de un árbol de Widgets:

• Padding tiene un único hijo Row
• Row tiene tres hijos: Icon, SizedBox y Flexible
• Flexible tiene un único hijo Column
• Column tiene cuatro hijos: Text, Text, SizedBox y Divider

Para ver en su lugar todos los Widgets en tu árbol de Widgets, incluidos aquellos que fueron creados fuera de tu proyecto, activa "Mostrar Widgets de implementación".

Los Widgets de implementación se muestran con una fuente más clara que los Widgets creados en tu proyecto, distinguiéndolos así visualmente. También están ocultos detrás de grupos colapsables que se pueden expandir a través de los botones de expansión en línea.

Por ejemplo, aquí está la misma sección de un árbol de Widgets que arriba con Widgets de implementación mostrados:

• Icon tiene cinco Widgets de implementación colapsados debajo de él
• Ambos Widgets Text tienen hijos Widgets de implementación RichText
• Divider tiene nueve Widgets de implementación colapsados debajo de él

El Flutter Widget Explorer te ayuda a entender mejor el Widget inspeccionado.

Desde el Flutter inspector, selecciona un Widget. El Widget Explorer se mostrará en el lado derecho de la ventana.

Dependiendo del Widget seleccionado, el Widget Explorer incluirá uno o más de los siguientes:

• Pestaña de propiedades del Widget
• Pestaña de flex explorer
• Pestaña de RenderObject

La pestaña de propiedades te muestra una mini vista del diseño de tu Widget, incluyendo ancho, alto y padding, junto con una lista de propiedades de ese Widget.

Estas propiedades incluyen si el valor coincide o no con el valor predeterminado para el argumento de la propiedad.

La pestaña de RenderObject muestra todas las propiedades configuradas en el RenderObject del Widget de Flutter seleccionado.

Cuando seleccionas un Widget flex (por ejemplo, Row, Column, Flex) o un hijo directo de un Widget flex, la herramienta flex explorer aparecerá en el Widget Explorer.

La herramienta flex explorer visualiza cómo se organizan los Widgets Flex y sus hijos. El explorer identifica el eje principal y el eje cruzado, así como la alineación actual para cada uno (por ejemplo, start, end y spaceBetween). También muestra detalles como el factor flex, el ajuste flex (flex fit) y las restricciones de diseño.

Además, el explorer muestra violaciones de las restricciones de diseño y errores de desbordamiento de renderizado (render overflow). Las restricciones de diseño violadas están coloreadas de rojo, y los errores de desbordamiento se presentan en el patrón estándar de "cinta amarilla", como podrías ver en un dispositivo en ejecución. Estas visualizaciones tienen como objetivo mejorar la comprensión de por qué ocurren los errores de desbordamiento así como la forma de solucionarlos.

Hacer clic en un Widget en el flex explorer refleja la selección en el inspector del dispositivo. El Modo seleccionar Widget debe estar habilitado para esto. Para habilitarlo, haz clic en el botón Modo seleccionar Widget en el inspector.

Para algunas propiedades, como el factor flex, el ajuste flex (flex fit) y la alineación, puedes modificar el valor a través de listas desplegables en el explorer. Al modificar una propiedad de un Widget, verás el nuevo valor reflejado no solo en el flex explorer, sino también en el dispositivo que ejecuta tu aplicación Flutter. El explorer anima los cambios de propiedad para que el efecto del cambio sea claro. Los cambios de propiedad de Widget realizados desde el layout explorer no modifican tu código fuente y se revierten con un Hot Reload.

El flex explorer admite la modificación de mainAxisAlignment, crossAxisAlignment y FlexParentData.flex. En el futuro, podríamos agregar soporte para propiedades adicionales tales como mainAxisSize, textDirection y FlexParentData.fit.

mainAxisAlignment

Valores soportados:

• MainAxisAlignment.start
• MainAxisAlignment.end
• MainAxisAlignment.center
• MainAxisAlignment.spaceBetween
• MainAxisAlignment.spaceAround
• MainAxisAlignment.spaceEvenly

crossAxisAlignment

Valores soportados:

• CrossAxisAlignment.start
• CrossAxisAlignment.center
• CrossAxisAlignment.end
• CrossAxisAlignment.stretch

FlexParentData.flex

El flex explorer admite 7 opciones de flex en la UI (null, 0, 1, 2, 3, 4, 5), pero técnicamente el factor flex del hijo de un Widget flex puede ser cualquier int.

Flexible.fit

El flex explorer admite los dos tipos diferentes de FlexFit: loose y tight.

El Flutter Inspector proporciona varias opciones para depurar visualmente tu aplicación.

Cuando está habilitada, esta opción ejecuta las animaciones 5 veces más lento para facilitar la inspección visual. Esto puede ser útil si deseas observar detenidamente y ajustar una animación que no se ve del todo bien.

Esto también se puede configurar en el código:

import 'package:flutter/scheduler.dart';
​
void setSlowAnimations() {
  timeDilation = 5.0;
}

Esto ralentiza las animaciones en un factor de 5.

Los siguientes enlaces proporcionan más información.

• Documentación de Flutter: propiedad timeDilation

Las siguientes grabaciones de pantalla muestran el antes y después de ralentizar una animación.

Esta función dibuja guías sobre tu aplicación que muestran render boxes, alineaciones, paddings, vistas con desplazamiento, recortes y espaciadores.

Esta herramienta se puede usar para comprender mejor tu diseño. Por ejemplo, encontrando padding no deseado o comprendiendo la alineación de los Widgets.

También puedes habilitar esto en el código:

import 'package:flutter/rendering.dart';
​
void showLayoutGuidelines() {
  debugPaintSizeEnabled = true;
}

Los Widgets que se dibujan en la pantalla crean una render box, los bloques de construcción de los diseños de Flutter. Se muestran con un borde azul brillante:

Las alineaciones se muestran con flechas amarillas. Estas flechas muestran los desplazamientos verticales y horizontales de un Widget en relación con su padre. Por ejemplo, el ícono de este botón se muestra centrado por las cuatro flechas:

El Padding se muestra con un fondo azul semitransparente:

Los Widgets con contenidos desplazables (como vistas de lista) se muestran con flechas verdes:

Los recortes, por ejemplo al usar el Widget ClipRect, se muestran con una línea rosa punteada con un ícono de tijeras:

Los Widgets espaciadores se muestran con un fondo gris, como este SizedBox sin hijo:

Esta opción hace visibles todas las líneas base. Las líneas base son líneas horizontales que se usan para posicionar el texto.

Esto puede ser útil para verificar si el texto está precisamente alineado verticalmente. Por ejemplo, las líneas base del texto en la siguiente captura de pantalla están ligeramente desalineadas:

El Widget Baseline se puede usar para ajustar las líneas base.

Se dibuja una línea en cualquier render box que tenga configurada una línea base; las líneas base alfabéticas se muestran en verde y las ideográficas en amarillo.

También puedes habilitar esto en el código:

import 'package:flutter/rendering.dart';
​
void showBaselines() {
  debugPaintBaselinesEnabled = true;
}

Esta opción dibuja un borde alrededor de todas las render boxes que cambia de color cada vez que esa caja se redibuja.

Este arcoíris giratorio de colores es útil para encontrar partes de tu aplicación que se están redibujando con demasiada frecuencia y potencialmente perjudicando el rendimiento.

Por ejemplo, una pequeña animación podría estar haciendo que toda una página se redibuje en cada fotograma (frame). Envolver la animación en un Widget RepaintBoundary limita el redibujado solo a la animación.

Aquí el indicador de progreso hace que su contenedor se redibuje:

class EverythingRepaintsPage extends StatelessWidget {
  const EverythingRepaintsPage({super.key});
​
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Repaint Example')),
      body: const Center(child: CircularProgressIndicator()),
    );
  }
}

Envolver el indicador de progreso en un RepaintBoundary hace que solo esa sección de la pantalla se redibuje:

class AreaRepaintsPage extends StatelessWidget {
  const AreaRepaintsPage({super.key});
​
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Repaint Example')),
      body: const Center(
        child: RepaintBoundary(child: CircularProgressIndicator()),
      ),
    );
  }
}

Los Widgets RepaintBoundary tienen compensaciones (tradeoffs). Pueden ayudar con el rendimiento, pero también tienen una sobrecarga al crear un nuevo lienzo (canvas), lo que utiliza memoria adicional.

También puedes habilitar esta opción en el código:

import 'package:flutter/rendering.dart';
​
void highlightRepaints() {
  debugRepaintRainbowEnabled = true;
}

Esta opción resalta las imágenes que son demasiado grandes tanto invirtiendo sus colores como volteándolas verticalmente:

Las imágenes resaltadas usan más memoria de la requerida; por ejemplo, una imagen grande de 5MB mostrada a 100 por 100 píxeles.

Dichas imágenes pueden causar un rendimiento deficiente, especialmente en dispositivos de gama baja y cuando tienes muchas imágenes, como en una vista de lista, este impacto en el rendimiento se puede acumular. La información sobre cada imagen se imprime en la consola de depuración:

dash.png has a display size of 213×392 but a decode size of 2130×392, which uses an additional 2542KB.

Las imágenes se consideran demasiado grandes si usan al menos 128KB más de lo requerido.

Siempre que sea posible, la mejor manera de solucionar este problema es cambiar el tamaño del archivo de recurso (asset) de la imagen para que sea más pequeño.

Si esto no es posible, puedes usar los parámetros cacheHeight y cacheWidth en el constructor de Image:

class ResizedImage extends StatelessWidget {
  const ResizedImage({super.key});
​
  @override
  Widget build(BuildContext context) {
    return Image.asset('dash.png', cacheHeight: 213, cacheWidth: 392);
  }
}

Esto hace que el motor decodifique esta imagen al tamaño especificado, y reduce el uso de memoria (la decodificación y el almacenamiento siguen siendo más costosos que si se hubiera reducido el propio recurso de la imagen). La imagen se renderiza a las restricciones del diseño o del ancho y alto independientemente de estos parámetros.

Esta propiedad también se puede configurar en el código:

void showOversizedImages() {
  debugInvertOversizedImages = true;
}

Puedes obtener más información en el siguiente enlace:

• Documentación de Flutter: debugInvertOversizedImages

Parte de la funcionalidad del Flutter inspector se basa en instrumentar el código de la aplicación para comprender mejor las ubicaciones del código fuente donde se crean los Widgets. La instrumentación del código fuente permite al Flutter inspector presentar el árbol de Widgets de una manera similar a cómo se definió la UI en tu código fuente. Sin ella, el árbol de nodos en el árbol de Widgets es mucho más profundo y puede ser más difícil comprender cómo se corresponde la jerarquía de Widgets en tiempo de ejecución con la UI de tu aplicación.

Puedes deshabilitar esta función pasando --no-track-widget-creation a la orden flutter run.

Aquí tienes ejemplos de cómo podría verse tu árbol de Widgets con y sin el rastreo de creación de Widgets habilitado.

Rastreo de creación de Widgets habilitado (predeterminado):

Rastreo de creación de Widgets deshabilitado (no recomendado):

Esta función evita que Widgets const que de otro modo serían idénticos sean considerados iguales en ejecuciones de depuración. Para más detalles, consulta la discusión sobre problemas comunes al depurar.

Al pasar el cursor sobre cualquier Widget se muestran sus propiedades y valores.

Cambiar este valor habilita o deshabilita la funcionalidad de inspección al pasar el cursor.

Cuando está habilitada, el árbol de Widgets se actualiza automáticamente después de un Hot Reload o un evento de navegación.

Cuando está habilitada, se usa el inspector legacy en lugar del nuevo inspector.

Por defecto, DevTools limita los Widgets mostrados en el árbol de Widgets a aquellos creados en el directorio raíz del proyecto. Para ver todos los Widgets, incluidos los creados fuera del directorio raíz de un proyecto, activa Mostrar Widgets de implementación

Para incluir otros Widgets en el árbol de Widgets predeterminado, se debe agregar un directorio padre de ellos a los Directorios de Paquetes (Package Directories).

Por ejemplo, considera la siguiente estructura de directorios:

project_foo
  pkgs
    project_foo_app
    widgets_A
    widgets_B

Ejecutar tu aplicación desde project_foo_app muestra solo Widgets de project_foo/pkgs/project_foo_app en el árbol del widget inspector.

Para mostrar Widgets de widgets_A en el árbol de Widgets, agrega project_foo/pkgs/widgets_A a los directorios de paquetes.

Para mostrar todos los Widgets de la raíz de tu proyecto en el árbol de Widgets, agrega project_foo a los directorios de paquetes.

Los cambios en tus directorios de paquetes se conservan la próxima vez que se abra el widget inspector para la aplicación.

Para una demostración de lo que generalmente es posible con el inspector, consulta la charla de DartConf 2018 que demuestra la versión de IntelliJ del Flutter inspector.

Para aprender cómo depurar visualmente problemas de diseño usando DevTools, consulta un tutorial del Flutter Inspector guiado.