Stack Navigator: چیست، ناوبری پشته‌ای در React Native

Stack Navigator چیست؟

Stack Navigator — یکی از ناوبرهای پایه کتابخانه React Navigation که مدل پشته‌ای صفحه‌ها را پیاده‌سازی می‌کند. این ناوبر، ناوبری آشنا را برای کاربران موبایل فراهم می‌کند: باز شدن صفحه جدید با انیمیشن ورود از راست همراه است و دکمه «بازگشت» یا حرکت سوایپ، کاربر را به صفحه قبلی بازمی‌گرداند. Stack Navigator در iOS و Android پشتیبانی می‌شود و از مؤلفه‌های بومی پلتفرم برای حداکثر عملکرد استفاده می‌کند.

React Navigation محبوب‌ترین کتابخانه ناوبری برای React Native است که در ۸۵٪ پروژه‌ها نصب شده است (طبق داده‌های npm، ۲۰۲۶). Stack Navigator در هسته آن قرار دارد و در دو پیاده‌سازی در دسترس است: createNativeStackNavigator (بومی، توصیه‌شده) و createStackNavigator (JavaScript، برای انیمیشن‌های سفارشی پیچیده). نسخه بومی در React Navigation v5 ظاهر شد و در v6+ به استاندارد تبدیل شد.

مزیت اصلی Stack Navigator — رفتار طبیعی آشنا برای کاربران iOS و Android است. در iOS، پشته به صورت بصری با UINavigationController نمایش داده می‌شود، در Android با FragmentManager با انیمیشن slide. توسعه‌دهنده نیازی به پیاده‌سازی دستی منطق پشته ندارد — ناوبر وضعیت صفحه‌ها، back stack و انیمیشن‌ها را به طور خودکار مدیریت می‌کند.

ناوبری پشته‌ای چگونه کار می‌کند

ناوبری پشته‌ای بر اساس اصل LIFO (Last In, First Out) است. وقتی کاربر صفحه جدیدی باز می‌کند، ناوبر آن را بالای پشته قرار می‌دهد. با فشار دادن «بازگشت»، صفحه بالایی حذف می‌شود و کاربر صفحه قبلی را می‌بیند. پشته می‌تواند هر تعداد صفحه داشته باشد — محدودیت فقط حافظه دستگاه است.

هر صفحه در پشته وضعیت خود را حفظ می‌کند. هنگام بازگشت به صفحه قبلی، وضعیت آن به طور خودکار بازیابی می‌شود. این امر پشته را از سایر انواع ناوبری (Tab, Drawer) متمایز می‌کند، جایی که صفحه‌ها ممکن است دوباره ایجاد شوند. React Navigation وضعیت را از طریق مکانیزم زمینه ناوبری خود مدیریت می‌کند.

ژست سوایپ برای بازگشت

در iOS، Stack Navigator از ژست سوایپ از لبه چپ صفحه برای بازگشت پشتیبانی می‌کند — این رفتار استاندارد iOS است که کاربران انتظار دارند. در Android، این ژست به طور پیش‌فرض غیرفعال است، اما می‌توان آن را از طریق گزینه gestureEnabled فعال کرد. در Native Stack، ژست به صورت بومی و بدون تأخیر در رشته JavaScript کار می‌کند.

Native Stack در مقابل JS Stack

React Navigation دو نوع Stack Navigator ارائه می‌دهد: Native Stack (createNativeStackNavigator) و JS Stack (createStackNavigator). تفاوت اصلی محل اجرای انیمیشن است. Native Stack از درایورهای انیمیشن بومی iOS و Android استفاده می‌کند، در حالی که JS Stack از طریق رشته JavaScript React Native کار می‌کند. انتخاب بین آنها به نیازهای عملکرد و سفارشی‌سازی بستگی دارد.

Native Stack برای اکثر پروژه‌ها توصیه می‌شود. انیمیشن‌های روان ۶۰ FPS را بدون مسدود کردن رشته JS فراهم می‌کند، از ژست سوایپ سیستمی در iOS پشتیبانی می‌کند و از انتقال‌های بومی استفاده می‌کند — slide در iOS، fade در Android. با این حال، Native Stack در سفارشی‌سازی انیمیشن محدود است: فقط مجموعه از پیش تعیین‌شده‌ای از انتقال‌ها در دسترس است.

JS Stack کنترل کامل بر انیمیشن‌ها را از طریق cardStyleInterpolator فراهم می‌کند. توسعه‌دهنده می‌تواند هر انیمیشنی ایجاد کند: بزرگنمایی، چرخش، پارالاکس، منحنی‌های سفارشی. نکته منفی — انیمیشن‌ها در رشته JS اجرا می‌شوند که می‌تواند در دستگاه‌های ضعیف هنگام انتقال‌های پیچیده باعث افت فریم شود. برای ۷۰٪ پروژه‌ها، Native Stack کاملاً کافی است.

// Native Stack — پیاده‌سازی توصیه‌شده
import { createNativeStackNavigator } from '@react-navigation/native-stack';

type RootStackParamList = {
  Home: undefined;
  Profile: { userId: string; name: string };
  Settings: undefined;
};

const Stack = createNativeStackNavigator<RootStackParamList>();

function AppNavigator() {
  return (
    <Stack.Navigator screenOptions={{ headerShown: true }}>
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen name="Profile" component={ProfileScreen} />
      <Stack.Screen name="Settings" component={SettingsScreen} />
    </Stack.Navigator>
  );
}

نصب و تنظیم Stack Navigator

برای شروع کار با Stack Navigator باید React Navigation و وابستگی‌های آن را نصب کنید. مجموعه حداقلی شامل @react-navigation/native، @react-navigation/native-stack و react-native-screens است. پس از نصب، اپلیکیشن در NavigationContainer قرار می‌گیرد — زمینه‌ای که وضعیت ناوبری را به همه مؤلفه‌های فرزند ارائه می‌دهد.

# نصب وابستگی‌های React Navigation
npm install @react-navigation/native @react-navigation/native-stack
npm install react-native-screens react-native-safe-area-context

# برای iOS — نصب pod
cd ios && pod install && cd ..

پس از نصب، Stack.Navigator با صفحه‌های تعریف‌شده در RootStackParamList ایجاد می‌شود. هر صفحه از طریق prop component به یک مؤلفه React متصل می‌شود. ناوبر می‌تواند ریشه یا تودرتو در ناوبر دیگری (Tab, Drawer) باشد. برای پیکربندی از screenOptions استفاده می‌شود — مشترک برای همه صفحه‌ها یا جداگانه برای هر کدام.

import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

type RootStackParamList = {
  Home: undefined;
  Details: { itemId: number; title: string };
};

const Stack = createNativeStackNavigator<RootStackParamList>();

export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator initialRouteName="Home"
        screenOptions={{
          headerStyle: { backgroundColor: '#6200ee' },
          headerTintColor: '#fff',
          gestureEnabled: true,
        }}>
        <Stack.Screen name="Home" component={HomeScreen}
          options={{ title: 'خانه' }} />
        <Stack.Screen name="Details" component={DetailsScreen}
          options={({ route }) => ({ title: route.params.title })} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

پارامترها و سفارشی‌سازی Stack Navigator

Stack Navigator گزینه‌های زیادی برای سفارشی‌سازی ظاهر و رفتار ارائه می‌دهد. پارامترهای اصلی از طریق screenOptions در سطح Navigator یا options در سطح Screen تنظیم می‌شوند. توسعه‌دهنده می‌تواند عنوان، انیمیشن انتقال، ژست سوایپ، سبک کارت و تاریک شدن پس‌زمینه را پیکربندی کند. انعطاف‌پذیری تنظیمات امکان تطبیق ناوبری با سیستم طراحی اپلیکیشن را فراهم می‌کند.

انیمیشن‌های سفارشی از طریق cardStyleInterpolator

برای JS Stack، cardStyleInterpolator امکان ایجاد انیمیشن‌های دلخواه انتقال بین صفحه‌ها را فراهم می‌کند. این ابزاری قدرتمند برای پیاده‌سازی جلوه‌های بصری منحصربه‌فرد است: بزرگنمایی، چرخش، پارالاکس، فلپ افقی. تابع مقادیر پیشرفت فعلی انیمیشن (current, next) را دریافت کرده و سبک‌هایی را برای عناصر متحرک برمی‌گرداند.

تایپ‌دهی ناوبری با TypeScript

Stack Navigator از تایپ‌دهی کامل از طریق TypeScript پشتیبانی می‌کند. برای این منظور RootStackParamList تعریف می‌شود — یک نوع-شیء که کلیدها نام صفحه‌ها و مقادیر انواع پارامترها هستند. پس از تایپ‌دهی، navigation.navigate و route.params تکمیل خودکار و بررسی نوع دریافت می‌کنند. این کار خطاهای انتقال پارامتر را در مرحله کامپایل حذف می‌کند.

type RootStackParamList = {
  Home: undefined;
  Product: { id: string; category: string };
  Checkout: { items: CartItem[]; total: number };
};

// صفحه تایپ‌دهی شده
type ProductScreenProps = NativeStackScreenProps<RootStackParamList, 'Product'>;

function ProductScreen({ navigation, route }: ProductScreenProps) {
  const { id, category } = route.params;

  return (
    <View>
      <Text>محصول {id} — {category}</Text>
      <Button title="به سبد خرید"
        onPress={() => navigation.navigate('Checkout', {
          items: [{ id, quantity: 1 }],
          total: 99.99,
        })} />
    </View>
  );
}

سناریوهای پیشرفته: پنجره‌های مودال و گروه‌ها

Stack Navigator از گروه‌بندی صفحه‌ها و پنجره‌های مودال پشتیبانی می‌کند. گروه‌ها (Screen Group) امکان اعمال تنظیمات مشترک به چندین صفحه را بدون تکرار فراهم می‌کنند. پنجره‌های مودال از طریق stack presentation: 'modal' پیاده‌سازی می‌شوند — صفحه از پایین با تیره شدن پس‌زمینه مانند مودال سیستمی در iOS باز می‌شود. این گزینه فقط در Native Stack در دسترس است.

برای ناوبری پیچیده، Stack Navigator می‌تواند در Tab Navigator یا Drawer Navigator تودرتو شود. به عنوان مثال، تب «خانه» شامل پشته صفحه‌های خود و تب «پروفایل» شامل پشته خود است. چنین ترکیبی از ناوبرها رویکرد استاندارد برای اپلیکیشن‌های تولیدی است. هر پشته ایزوله است: back stack درون یک تب بر سایر تب‌ها تأثیر نمی‌گذارد.

// پشته تودرتو در Tab Navigator
const HomeStack = createNativeStackNavigator<HomeStackParamList>();

function HomeStackScreen() {
  return (
    <HomeStack.Navigator>
      <HomeStack.Screen name="Feed" component={FeedScreen} />
      <HomeStack.Screen name="PostDetail" component={PostDetailScreen}
        options={{ presentation: 'modal' }} />
    </HomeStack.Navigator>
  );
}

// گروه‌های صفحه با گزینه‌های مشترک
<Stack.Navigator>
  <Stack.Group screenOptions={{ headerShown: true }}>
    <Stack.Screen name="Main" component={MainScreen} />
    <Stack.Screen name="About" component={AboutScreen} />
  </Stack.Group>
  <Stack.Screen name="Auth" component={AuthScreen}
    options={{ presentation: 'modal', headerShown: false }} />
</Stack.Navigator>