Implementar navegación con React Navigation

Introducción a React Navigation: El Sistema de Carreteras de tu Aplicación

En el desarrollo de aplicaciones móviles nativas, la capacidad de mover al usuario entre diferentes pantallas es tan fundamental como la existencia de las propias pantallas. React Navigation es la biblioteca estándar de facto para manejar la navegación en aplicaciones construidas con React Native. Su propósito es proporcionar una experiencia de navegación fluida, consistente y con gestos nativos, tanto en iOS como en Android, utilizando componentes JavaScript. Imagina tu aplicación como un país: las pantallas son las ciudades y el contenido valioso, mientras que React Navigation es la red completa de autopistas, carreteras y señales que permiten a los usuarios viajar de un lugar a otro de forma intuitiva y predecible.

Antes de React Navigation, los desarrolladores enfrentaban el complejo desafío de interactuar directamente con las APIs de navegación nativas de cada plataforma, lo que resultaba en código duplicado y difícil de mantener. Esta biblioteca abstrae esas complejidades, ofreciendo una API declarativa y centrada en React. Para el nivel intermediate, es crucial entender que React Navigation no es un componente monolítico, sino un ecosistema. Se estructura en torno a un concepto central: el navegador (o navigator). Un navegador es un componente que gestiona un tipo específico de transición y organización de pantallas, como un stack (pila), pestañas o un cajón lateral. La elección del navegador correcto define la estructura de navegación primaria de tu app.

En esta lección, nos sumergiremos en la implementación práctica, comenzando con el navegador más común: el Stack Navigator. Aprenderás a configurar tu proyecto, definir rutas, pasar parámetros entre pantallas y manejar el encabezado de navegación. Este conocimiento sienta las bases para estructuras más complejas, como combinar un Tab Navigator dentro de un Stack Navigator, o implementar navegación de tipo Drawer. La meta es que tengas un control total sobre el flujo de tu aplicación, creando una experiencia de usuario profesional y pulida.

Concepto Clave: Navegadores, Rutas y Navegación - La Analogía del Teatro

Para internalizar cómo funciona React Navigation, usemos una analogía del mundo real: un teatro con múltiples obras. El NavigationContainer es el teatro en sí. Es el componente de nivel superior que envuelve toda tu estructura de navegación y gestiona el estado global de la navegación. No puede haber obras (navegación) sin el teatro (el contenedor). Dentro de este teatro, tienes diferentes escenarios o navegadores. Cada navegador es como un tipo distinto de escenario: uno puede ser un escenario tradicional con un telón que sube y baja (Stack Navigator), otro puede ser un escenario circular con múltiples focos (Tab Navigator).

Cada pantalla o componente en tu aplicación es una ruta. En nuestra analogía, una ruta es una obra de teatro específica, como "Hamlet" o "El Lago de los Cisnes". Cada obra/ruta tiene un nombre único (por ejemplo, 'Home', 'Details') y un conjunto de parámetros (el elenco, el vestuario, la escenografía) que puedes pasarle cuando la "presentas". El objeto navigation, que se pasa como prop a cada pantalla, es el director de escena. Te da métodos como navigate, goBack, y push para cambiar de obra (pantalla) y gestionar el orden de presentación.

Finalmente, el objeto route, también pasado como prop, contiene la información sobre la obra actual que se está representando. Incluye el nombre de la ruta y los parámetros que recibió. Entender la distinción y la relación entre el contenedor, los navegadores, las rutas y el objeto de navegación es el primer paso fundamental para dominar la biblioteca. No son solo componentes y funciones; son los actores principales en la coreografía del flujo de tu aplicación.

Cómo Funciona en la Práctica: Configuración y Stack Navigator Paso a Paso

La implementación práctica comienza con la instalación de los paquetes necesarios. React Navigation tiene una arquitectura modular. Para un Stack Navigator básico, necesitas instalar el paquete core y los paquetes específicos para la navegación en stack nativa, que utilizan APIs nativas de cada plataforma para un rendimiento óptimo. En un proyecto Expo, esto se hace fácilmente con npx expo install. El primer paso es siempre instalar las dependencias: @react-navigation/native y, para stack, @react-navigation/native-stack. También se requieren dependencias de compatibilidad como react-native-screens y react-native-safe-area-context, que Expo instalará automáticamente.

Una vez instaladas las dependencias, el patrón de implementación sigue una estructura clara. Primero, importas el NavigationContainer y el navegador que vas a usar (en este caso, createNativeStackNavigator). Luego, creas una instancia del navegador llamando a la función. Esta instancia te proporciona dos componentes clave: <Navigator> y <Screen>. El componente Navigator actúa como el contenedor padre que define el comportamiento de navegación (stack), y dentro de él, defines cada una de tus pantallas utilizando componentes Screen. Cada Screen asocia un name (un string identificador) con un component (el componente React que se renderizará).

El siguiente paso es integrar esta estructura en tu componente principal de la aplicación, típicamente en App.js. Envuelves toda tu estructura de navegadores con el NavigationContainer. Ahora, desde cualquier pantalla definida dentro del navegador, recibirás automáticamente las props navigation y route. Para navegar a otra pantalla, usas navigation.navigate('NombreDeLaRuta'). Si necesitas pasar datos, los agregas como un segundo argumento en forma de objeto: navigation.navigate('Details', { itemId: 86, title: 'Mi Producto' }). En la pantalla de destino, accedes a estos datos mediante route.params.

Tip Profesional: Siempre define los nombres de tus rutas como constantes. Crear un archivo src/navigation/routes.js que exporte objetos como export const ROUTES = { HOME: 'Home', DETAILS: 'Details' } previene errores tipográficos fatales y facilita refactorizaciones a lo largo del proyecto.

Código en Acción: Una Aplicación de Lista de Tareas con Navegación

A continuación, veremos un ejemplo completo y funcional de una aplicación simple de lista de tareas (To-Do) que utiliza React Navigation con un Stack Navigator. La aplicación tendrá dos pantallas: una pantalla principal (HomeScreen) que muestra una lista de tareas, y una pantalla de detalles (DetailsScreen) que muestra la información completa de una tarea cuando se toca. Este flujo es universal en las aplicaciones móviles.

// App.js - Punto de entrada principal
import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import HomeScreen from './screens/HomeScreen';
import DetailsScreen from './screens/DetailsScreen';

// Crear la instancia del Stack Navigator
const Stack = createNativeStackNavigator();

function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator initialRouteName="Home">
        <Stack.Screen 
          name="Home" 
          component={HomeScreen}
          options={{ title: 'Mis Tareas' }}
        />
        <Stack.Screen 
          name="Details" 
          component={DetailsScreen}
          options={({ route }) => ({ title: route.params?.taskTitle || 'Detalles' })}
        />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

export default App;

Ahora, veamos la implementación de las pantallas. La pantalla de inicio muestra una lista y navega a los detalles pasando parámetros.

// screens/HomeScreen.js
import React from 'react';
import { View, Text, FlatList, TouchableOpacity, StyleSheet } from 'react-native';

const TASK_LIST = [
  { id: '1', title: 'Comprar leche', description: 'Ir al supermercado', priority: 'Alta' },
  { id: '2', title: 'Revisar correo', description: 'Responder a clientes', priority: 'Media' },
  { id: '3', title: 'Hacer ejercicio', description: '30 minutos de cardio', priority: 'Baja' },
];

function HomeScreen({ navigation }) {
  const renderTaskItem = ({ item }) => (
    <TouchableOpacity
      style={styles.taskItem}
      onPress={() => navigation.navigate('Details', {
        taskId: item.id,
        taskTitle: item.title,
        taskDescription: item.description,
        taskPriority: item.priority,
      })}
    >
      <Text style={styles.taskTitle}>{item.title}</Text>
      <Text style={styles.taskSubtitle}>Prioridad: {item.priority}</Text>
    </TouchableOpacity>
  );

  return (
    <View style={styles.container}>
      <FlatList
        data={TASK_LIST}
        renderItem={renderTaskItem}
        keyExtractor={item => item.id}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 },
  taskItem: { padding: 20, borderBottomWidth: 1, borderBottomColor: '#ccc' },
  taskTitle: { fontSize: 18, fontWeight: 'bold' },
  taskSubtitle: { fontSize: 14, color: 'gray' },
});

export default HomeScreen;

Finalmente, la pantalla de detalles recibe los parámetros y los muestra. También incluye un botón para volver atrás.

// screens/DetailsScreen.js
import React from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';

function DetailsScreen({ route, navigation }) {
  // Extraer parámetros con valores por defecto para evitar errores
  const {
    taskId = 'N/A',
    taskTitle = 'Tarea sin título',
    taskDescription = 'Sin descripción',
    taskPriority = 'No definida'
  } = route.params || {};

  return (
    <View style={styles.container}>
      <Text style={styles.header}>Detalles de la Tarea</Text>
      <Text style={styles.label}>ID: <Text style={styles.value}>{taskId}</Text></Text>
      <Text style={styles.label}>Título: <Text style={styles.value}>{taskTitle}</Text></Text>
      <Text style={styles.label}>Descripción: <Text style={styles.value}>{taskDescription}</Text></Text>
      <Text style={styles.label}>Prioridad: <Text style={styles.value}>{taskPriority}</Text></Text>
      
      <View style={styles.buttonContainer}>
        <Button title="Volver a la lista" onPress={() => navigation.goBack()} />
        <Button title="Ir al Inicio" onPress={() => navigation.popToTop()} />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 24 },
  header: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 },
  label: { fontSize: 18, marginTop: 10, fontWeight: '600' },
  value: { fontWeight: 'normal' },
  buttonContainer: { marginTop: 30, gap: 10 },
});

export default DetailsScreen;

Errores Comunes y Cómo Evitarlos

Al implementar React Navigation, varios errores recurrentes pueden causar frustración. Identificarlos y saber cómo solucionarlos es clave para un desarrollo eficiente.

1. Olvidar el NavigationContainer: Es el error más básico. Si tus pantallas no navegan o recibes un error relacionado con el contexto de navegación, lo primero es verificar que toda tu estructura de navegadores esté envuelta dentro del <NavigationContainer>. Este componente proporciona el contexto necesario para que toda la magia de la navegación funcione. Sin él, los objetos navigation y route serán undefined.

2. Pasar parámetros incorrectamente o no manejarlos de forma segura: Un error común es intentar acceder a route.params.property directamente sin verificar si route.params existe. Esto lanzará un error si la pantalla se abre sin parámetros (por ejemplo, desde un enlace profundo). Siempre usa desestructuración con valores por defecto o verifica condicionalmente: const itemId = route.params?.itemId;. Además, recuerda que los parámetros deben ser serializables (objetos, arrays, strings, números). No intentes pasar funciones o componentes complejos.

3. Confundir navigate con push: Ambos métodos llevan a una nueva pantalla, pero su comportamiento en el stack es diferente. navigate('ScreenName') navegará a la pantalla si ya existe en el stack, volviendo a ella y reiniciando sus parámetros, en lugar de agregar una nueva instancia. push('ScreenName') siempre agregará una nueva instancia de la pantalla al stack, incluso si ya está presente. Usa push cuando quieras permitir múltiples instancias de la misma pantalla (por ejemplo, ver detalles de diferentes productos uno tras otro). Usa navigate para una navegación más típica entre secciones distintas.

4. No configurar correctamente las opciones del encabezado (header): El encabezado es gestionado por el navegador, no por la pantalla individual. Para personalizarlo, puedes usar la prop options en <Stack.Screen>. Un error es intentar cambiar el título desde dentro del componente de la pantalla usando, por ejemplo, navigation.setOptions en un useEffect sin las dependencias correctas, lo que puede causar actualizaciones infinitas o que no se apliquen. Para configuraciones dinámicas basadas en parámetros, usa la forma de función de options como se mostró en el ejemplo de App.js.

5. Anidar navegadores de forma incorrecta: La estructura de navegación puede volverse compleja. Un patrón común es tener un Tab Navigator dentro de un Stack Navigator, o viceversa. Un error es colocar el NavigationContainer en múltiples lugares. Debe haber un solo NavigationContainer en la raíz de tu aplicación. Los navegadores hijos (como las pantallas de pestañas) se pasan como componentes a las pantallas del navegador padre. Nunca anides un NavigationContainer dentro de otro.

Checklist de Dominio

Para verificar que has comprendido y puedes implementar correctamente la navegación con React Navigation, asegúrate de poder realizar y explicar cada uno de los siguientes puntos:

• Instalar y configurar correctamente las dependencias de React Navigation y un Stack Navigator en un proyecto Expo.
• Definir una estructura básica de navegación con NavigationContainer y al menos un Stack.Navigator con múltiples Stack.Screen.
• Navegar programáticamente entre pantallas utilizando los métodos navigate, goBack, y popToTop del objeto navigation.
• Pasar parámetros complejos (objetos) de una pantalla a otra y manejarlos de forma segura en la pantalla de destino, incluyendo la provisión de valores por defecto.
• Personalizar el encabezado de navegación (título, botones, estilos) tanto de forma estática en la configuración del Screen como dinámicamente desde dentro del componente usando navigation.setOptions.
• Explicar la diferencia práctica entre los métodos navigate y push y decidir cuándo es apropiado usar cada uno.
• Identificar y solucionar los errores más comunes, como el contexto de navegación faltante o el acceso inseguro a route.params.
• Comprender el flujo de ciclo de vida relacionado con la navegación (enfocado/desenfocado) y su potencial integración con hooks como useFocusEffect.