استفد من الأنواع (typings) في React Navigation
أصبح بناء التنقل ميزة أساسية في أي تطبيق للهاتف هذه الأيام. وفي عالم React Native لدينا React Navigation في متناول اليد.
يشرح هذا المقال كيف يمكن تنفيذ React Navigation بشكل نموذجي باستخدام TypeScript، مع مقارنة استراتيجيات مختلفة لاستخدام TypeScript.
والأهم من ذلك، يتناول أيضًا كيف نستفيد إلى أقصى حد من ميزات TypeScript لنبني بنية تنقل أكثر قابلية للتوسع.
تنبيه: الأمثلة في هذا المقال مأخوذة باستخدام الإصدار @react-navigation@6.x.
تنبيه: الطرق والاستراتيجيات التي سيتناولها هذا المقال ليست قواعد لا غنى عنها يجب أن تتبعها حرفيًا، بل هي تفضيلاتي الشخصية التي وجدتها مفيدة وأحببت مشاركتها مع القراء. لدى React Navigation أصلًا قسم رائع وموثّق جيدًا حول استخدام TypeScript. ومع ذلك، يمكنك بالفعل بناء بنية ممتازة لـ react-navigation مع TypeScript بمجرد اتباع هذا التوثيق.
إنشاء Stack Navigator
لنلقِ نظرة على طريقة إنشاء stack navigator باستخدام حزمة React Navigation .
انظر إلى المثال أدناه المأخوذ من React Navigation:
import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";
const Stack = createStackNavigator();
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;
function AppStack() {
return (
<Stack.Navigator>
<Stack.Screen name="Home" component={Home} />
<Stack.Screen name="Notifications" component={Notifications} />
<Stack.Screen name="Profile" component={Profile} />
<Stack.Screen name="Settings" component={Settings} />
</Stack.Navigator>
);
}
كما ترى، لا يوجد هنا شيء خاص بـ TypeScript، فلنضف قليلًا من TypeScript إلى مقتطف الكود هذا.
import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";
type AppStackParamList = {
Home: undefined;
Notifications: undefined;
Profile: undefined;
Settings: undefined;
};
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;
const Stack = createStackNavigator<AppStackParamList>();
function AppStack() {
return (
<Stack.Navigator>
<Stack.Screen name="Home" component={Home} />
<Stack.Screen name="Notifications" component={Notifications} />
<Stack.Screen name="Profile" component={Profile} />
<Stack.Screen name="Settings" component={Settings} />
</Stack.Navigator>
);
}
في الكود أعلاه أضفنا النوع ParamList إلى createStackNavigator. لكن مهلًا، كيف نعرف أن createStackNavigator تقبل نوعًا عامًا (generic)؟ هناك عدة طرق لمعرفة ذلك. ومن الممارسات الجيدة دائمًا أن تراجع التوثيق أولًا. وفي هذا المثال ستلاحظ أن هناك قسمًا مخصصًا لذلك في التوثيق.
من ناحية أخرى، لو افترضنا أن هذا النوع الخاص بـ createStackNavigator غير موثّق على الموقع، فإن إحدى الطرق الممكنة لمعرفة ما إذا كانت الدالة تقبل هذا النوع هي ببساطة الانتقال إلى تعريف النوع (type definition) الخاص بالدالة. قد يبدو ذلك مخيفًا في البداية لأنك سترى الكثير من الأنواع والواجهات والـ generics، لكن كلما اعتدت على الانتقال إلى تعريف النوع، أصبح الأمر أقل إرهاقًا بكثير.
تحديث!
إذا كنت تريد التعامل مع تعقيد إضافي في TypeScript، وتريد أيضًا تجاهل الأداة الرائعة التي يوفرها فريق React في TS (React.ComponentProps)، فيمكنك متابعة القراءة حتى نهاية المقال.
لكنني أخشى أن هذا القسم قد يكون النهاية!
سنتمكن من استخراج الأنواع الخاصة بكل شاشة في الـ stack وإعداداتها باستخدام React.ComponentProps
انظر أدناه إلى المثال الكامل:
import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";
type AppStackParamList = {
Home: undefined;
Notifications: undefined;
Profile: undefined;
Settings: undefined;
};
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;
const Stack = createStackNavigator<AppStackParamList>();
const routes: Array<React.ComponentProps<typeof Stack.Screen>> = [
{
name: "Home",
component: Home,
},
{
name: "Notifications",
component: Notifications,
},
{
name: "Profile",
component: Profile,
},
{
name: "Settings",
component: Settings,
},
];
function AppStack() {
return (
<Stack.Navigator>
{routes.map((routeConfig) => (
<Stack.Screen key={routeConfig.name} {...routeConfig} />
))}
</Stack.Navigator>
);
}
ونعم، سيبقى الـ intellisense موجودًا، وسيظل يحذّرك إذا أضفت إلى الـ stack شاشة لا علاقة لها به (أي شاشة غير موجودة في تعريف نوع الـ stack)، هكذا:
شاشة غير صالحة
وسيكون الـ Intellisense حاضرًا أيضًا:

كما أنه أنظف وأكثر قابلية للإعداد وأكثر ديناميكية:
const getAuthStackRoutes = (
// other parameters...
theme: ThemeType
): Array<React.ComponentProps<typeof Stack.Screen>> => {
// more business logic...
return [
{
name: "Home",
component: Home,
options: {
headerStyle: {
backgroundColor: theme.colors.primary,
// other theme stylings...
},
},
},
];
};
في الختام، يتيح لنا هذا النهج إدارة بنى التنقل المعقدة بسهولة (على الأقل عند مقارنته بالطرق الأخرى في هذا المقال). والسبب أنك ستحصل على JSX أنظف، وستتمكن أيضًا من إعداد المسارات (routes) بطريقة أكثر ديناميكية وتقسيمًا إلى وحدات.
خطوة أبعد في استخدام TypeScript
الأمر لا يقتصر على تعريف النوع العام لـ createStackNavigator فقط. ماذا عن نوع العناصر الأبناء التي سيحتويها Stack.Navigator؟ ورغم أن هذا المفهوم معرّف جيدًا في التوثيق الرسمي، فلنرَ أدناه كيف يمكننا التلاعب به للحصول على طريقة أكثر فصلًا في إنشاء البنية.
import type { RouteConfig, StackNavigationState } from "@react-navigation/core";
import {
createStackNavigator,
StackNavigationEventMap,
StackNavigationOptions,
} from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";
// stack param list type
type AppStackParamList = {
Home: undefined;
Notifications: undefined;
Profile: undefined;
Settings: undefined;
};
// type of the single route in app stack
type AppStackRoutesType = RouteConfig<
AppStackParamList,
keyof AppStackParamList,
StackNavigationState<AppStackParamList>,
StackNavigationOptions,
StackNavigationEventMap
>;
// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;
// strictly typed array of app stack routes
const appStackRoutes: Array<AppStackRoutesType> = [
{
name: "Home",
component: Home,
},
{
name: "Notifications",
component: Notifications,
},
{
name: "Profile",
component: Profile,
},
{
name: "Settings",
component: Settings,
},
];
const Stack = createStackNavigator<AppStackParamList>();
function AppStack() {
return (
<Stack.Navigator>
{/** mapping the app stack routes */}
{appStackRoutes.map((stackRoute) => (
<Stack.Screen key={stackRoute.name} {...stackRoute} />
))}
</Stack.Navigator>
);
}
أوه، هناك الكثير مما يحدث هنا… لنقسّم كل كتلة كود إلى أجزاء منفصلة.
import type { RouteConfig, StackNavigationState } from "@react-navigation/core";
import {
createStackNavigator,
StackNavigationEventMap,
StackNavigationOptions,
} from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";
في أعلى مقتطف الكود نستورد الوحدات اللازمة. تتضمن هذه الاستيرادات أنواعًا ودوالًا وأشياء أخرى ضرورية. ليست مثيرة للاهتمام لكنها ضرورية :)
// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;
في الأعلى نستورد المكوّن View من react-native حتى يكون المثال أبسط في العرض.
// type of the single route in app stack
type AppStackRoutesType = RouteConfig<
AppStackParamList,
keyof AppStackParamList,
StackNavigationState<AppStackParamList>,
StackNavigationOptions,
StackNavigationEventMap
>;
والآن يأتي الجزء المثير. النوع RouteConfig المستورد من @react-navigation/core يقبل خمسة أنواع بالضبط كـ نوع عام (generic type). وتعريف النوع هذا غير موثّق على موقع react-navigation الرسمي، لكن يمكنك معرفته بسهولة باستخدام طريقة الانتقال إلى تعريف النوع التي ذكرناها أعلاه.
ورغم أنه قد يبدو زائدًا أو غير ضروري في مشروع react-native نموذجي مع TypeScript، فإنه يأتي بعدة فوائد سنتناولها في القسم التالي.
IntelliSense
بما أن لدينا مصفوفة لمسارات الـ stack (أي مسارات التطبيق) بأنواع صارمة، فإن كل عنصر في المصفوفة أصبح ملزمًا بالالتزام بتعريف نوع المصفوفة. وهذا يعني أن IntelliSense سيعمل مباشرة عند إضافة عنصر جديد إلى المصفوفة.
وفوق ذلك، يُلزمنا تطبيق هذا النوع بتحديث AppStackRoutesType كلما أردنا إضافة عنصر جديد إلى مسارات التطبيق. وإلا فلن نتمكن من إضافة عنصر جديد غير موجود في AppStackRoutesType (AppStackParamList).
ربط المسارات (Mapping)
وهنا يأتي الجزء الأخير: ننشئ الـ stack navigator باستخدام createStackNavigator. ثم يصبح الأمر ببساطة مسألة المرور (map) على المصفوفة التي أنشأناها أعلاه مع نوعها الصارم.
يمكننا في النهاية أن نثق بكل عنصر في مصفوفتنا، فكل العناصر ستكون بأنواع صحيحة، لذا من الآمن استخدام صياغة النشر (spread syntax).
const Stack = createStackNavigator<AppStackParamList>();
function AppStack() {
return (
<Stack.Navigator>
{/** mapping the app stack routes */}
{appStackRoutes.map((stackRoute) => (
<Stack.Screen key={stackRoute.name} {...stackRoute} />
))}
</Stack.Navigator>
);
}
هل كان هذا حقًا الجزء الأخير؟
حسنًا… لا!
ما زال بإمكاننا تحسين الأنواع في المثال الذي تناولناه.
// generic stack routes type
export type StackRoutesType<ParamList extends ParamListBase> = Array<
RouteConfig<
ParamList,
keyof ParamList,
StackNavigationState<ParamList>,
StackNavigationOptions,
StackNavigationEventMap
>
>;
type AppStackRoutesType = StackRoutesType<AppStackParamList>;
// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;
// strictly typed array of app stack routes
const appStackRoutes: AppStackRoutesType = [
{
name: "Home",
component: Home,
},
{
name: "Notifications",
component: Notifications,
},
{
name: "Profile",
component: Profile,
},
{
name: "Settings",
component: Settings,
},
];
الفرق الذي ربما لاحظته هو أن لدينا StackRoutesType الذي يقبل نوعًا عامًا ويساوي النوع الذي رأيناه من قبل. لكن قد تسأل: ما الفائدة هنا؟ من الأفضل أن نجيب عن هذا السؤال بشكل مرئي.
// too much duplicated code...
type AppStackRoutesType = RouteConfig<
AppStackParamList,
keyof AppStackParamList,
StackNavigationState<AppStackParamList>,
StackNavigationOptions,
StackNavigationEventMap
>;
type OtherStackRoutesType = RouteConfig<
OtherStackParamList,
keyof OtherStackParamList,
StackNavigationState<OtherStackParamList>,
StackNavigationOptions,
StackNavigationEventMap
>;
type AnotherStackRoutesType = RouteConfig<
AnotherStackParamList,
keyof AnotherStackParamList,
StackNavigationState<AnotherStackParamList>,
StackNavigationOptions,
StackNavigationEventMap
>;
لو لم نختر استخدام StackRoutesType العام، لاضطررنا إلى تكرار الأنواع لكل stack في التطبيق.
وسيصبح ذلك كابوسًا كلما كبر التطبيق. (الفكرة هنا أن عدد الـ stacks في التطبيق يتناسب طرديًا مع تعقيد التطبيق. في الواقع هذا الافتراض ليس صحيحًا بنسبة 100% دائمًا، لكنه مناسب لهذا المثال تحديدًا)
// generic stack routes type
export type StackRoutesType<ParamList extends ParamListBase> = Array<
RouteConfig<
ParamList,
keyof ParamList,
StackNavigationState<ParamList>,
StackNavigationOptions,
StackNavigationEventMap
>
>;
// becomes one line typings for each stack
type AppStackRoutesType = StackRoutesType<AppStackParamList>;
type OtherStackRoutesType = StackRoutesType<OtherStackParamList>;
type AnotherStackRoutesType = StackRoutesType<AnotherStackParamList>;
في المقابل، انظر أعلاه كيف يصبح الأمر أبسط وأنظف الآن عند استخدام النوع العام.
الصورة النهائية
لنقارن كيف ستبدو دالة Stack نموذجية في سيناريوهين مختلفين:
الصورة 1: عرض كل شاشات الـ stack واحدة تلو الأخرى في JSX.
// ...imports, components
function AppStack() {
return (
<Stack.Navigator>
<Stack.Screen name="Home" component={Home} />
<Stack.Screen name="Notifications" component={Notifications} />
<Stack.Screen name="Profile" component={Profile} />
<Stack.Screen name="Settings" component={Settings} />
{/** n more screens... */}
</Stack.Navigator>
);
}
الصورة 2: عرض الشاشات باستخدام مصفوفة مسارات الـ stack المنشأة بأنواع TypeScript صارمة. 🎉
function AppStack() {
return (
<Stack.Navigator>
{appStackRoutes.map((stackRoute) => (
<Stack.Screen key={stackRoute.name} {...stackRoute} />
))}
</Stack.Navigator>
);
}
شيء أخير… ماذا عن props الخاصة بالـ Navigator
ربما بقي أمامنا أمر واحد يجب أخذه في الاعتبار، وهو props الخاصة بالـ stack navigator. بالنظر إلى StackNavigator أدناه، نجد كتلة من الإعدادات لـ navigator واحد. لماذا لا نفصل هذه الإعدادات عن JSX؟
import type {
DefaultNavigatorOptions,
ParamListBase,
StackNavigationState,
} from "@react-navigation/core";
import {
StackNavigationEventMap,
StackNavigationOptions,
} from "@react-navigation/stack";
// other necessary imports for screens...
// generic typing for stack navigator options
type StackNavigatorOptions<ParamList extends ParamListBase> =
DefaultNavigatorOptions<
ParamList,
StackNavigationState<ParamList>,
StackNavigationOptions,
StackNavigationEventMap
>;
// omit the children as it corresponds to stack screen
const appStackNavigatorProps: Omit<
StackNavigatorOptions<AppStackParamList>,
"children"
> = {
initialRouteName: "Home",
screenOptions: {
headerShown: false,
cardOverlayEnabled: true,
gestureEnabled: false,
cardStyle: {
backgroundColor: "royalblue",
},
headerLeftContainerStyle: {
backgroundColor: "firebrick",
},
presentation: "modal",
headerTitleStyle: {
fontSize: 24,
color: "olivedrab",
},
},
// ...rest
};
// screen components and stack routes...
function AppStack() {
return (
<Stack.Navigator {...appStackNavigatorProps}>
{appStackRoutes.map((stackRoute) => (
<Stack.Screen key={stackRoute.name} {...stackRoute} />
))}
</Stack.Navigator>
);
}
بدءًا من السطر 13، يُفترض أننا صرنا نعرف لماذا نستخدم النوع العام. والفرق الوحيد تقريبًا في الأنواع مقارنةً بمسارات الـ stack هنا هو النوع DefaultNavigatorOptions المستورد من @react-navigation/core. واسم النوع نفسه يشرح نفسه: إنه خيارات الـ navigator.
وكما في النوع RouteConfig الذي ذكرناه أعلاه، يقبل هذا النوع أيضًا عدة أنواع عامة. إلى جانب ذلك، تذكّر أننا نستبعد (omit) المفتاح children صراحةً، لأننا نعرض أصلًا أبناء Stack.Navigator التي تقابل Stack.Screen.
في السطر 22 ننشئ كائنًا جديدًا تمامًا (أو يمكن أن يكون دالة، طالما أنها تعيد كائنًا يحقق نوع خيارات الـ navigator) يمثل خيارات الـ navigator الخاص بنا.
ونتيجة لذلك، في السطر 50 يمكن استخدام هذا الكائن بأمان مع صياغة النشر طالما أنه يحقق النوع المحدد.
JSX أنظف بكثير… في رأيي…
الصورة النهائية: props الخاصة بالـ Navigator
لنقارن مرة أخرى كيف ستبدو دالة Stack نموذجية في سيناريوهين مختلفين:
الصورة 1: إعدادات الـ stack navigator داخل JSX.
function AppStack() {
return (
<Stack.Navigator
initialRouteName="Home"
screenOptions={{
headerShown: false,
cardOverlayEnabled: true,
gestureEnabled: false,
cardStyle: {
backgroundColor: "royalblue",
},
headerLeftContainerStyle: {
backgroundColor: "firebrick",
},
presentation: "modal",
headerTitleStyle: {
fontSize: 24,
color: "olivedrab",
},
}}
// rest...
>
{appStackRoutes.map((stackRoute) => (
<Stack.Screen key={stackRoute.name} {...stackRoute} />
))}
</Stack.Navigator>
);
}
الصورة 2: إعدادات الـ stack navigator مفصولة عن JSX.
// ...
function AppStack() {
return (
<Stack.Navigator {...appStackNavigatorProps}>
{appStackRoutes.map((stackRoute) => (
<Stack.Screen key={stackRoute.name} {...stackRoute} />
))}
</Stack.Navigator>
);
}
الخلاصة
تناولنا في هذا المقال كيف نستفيد فعلًا من TypeScript ونصل إلى طريقة أنظف لهيكلة الـ navigators في react-native.
أتمنى لكم جميعًا يومًا خاليًا من الأخطاء.
منشور أيضًا على
هذا المقال منشور أيضًا على: