المعاملات الاختيارية (Optional Parameters)

الدرس 12 من 34 · دورة TanStack Router الكاملة · 7 دقيقة و30 ثانية

الفيديو الأصلي باللغة الإنجليزية. إذا تعذّر تشغيله هنا، شاهده على موقع المؤلف. التفريغ النصي العربي الكامل أدناه.

مستودع الكود لهذا الدرس

الفرع: optional-params

[00:01] شيءٌ آخر ربّما رأيته في موجّهات (routers) أخرى أضفًا إلى هذا هو إمكانية امتلاك معاملاتٍ اختيارية (optional parameters). فلنقل مثلًا أنّنا نحتاج إلى مسار (route)، على سبيل المثال، لأرشيفٍ (archive) لشيءٍ ما. إذًا سيتعيّن علينا إنشاء مسار

[00:15] سَيَكُون /archive.

[00:21] وبالنسبة إلى هذا الأرشيف مثلًا، يمكنك أن تزور الأرشيف بذاته فسنحصل على كل شيءٍ موجودٍ في هذا الأرشيف، أو يمكننا حصره أكثر بتمرير تاريخٍ (date) هنا مثلًا. ويمكننا حصره أكثر فأكثر بتمرير ربّما

[00:31] شهرٍ ثم يومٍ وهكذا. غير أنّ كل هذه اختيارية. ولنقل أيضًا أنّه لدينا لغاتٌ متعدّدة، فقبل archive يمكن أن يكون لدينا لغةٌ مثلًا هكذا. غير أنّ هذا اختياري أيضًا.

[00:44] وإذا لم نمرّره فسنحصل على لغة افتراضية (default). فلنزُر هذا المسار ربّما، وهو بالطبع سَيَكُون غير موجود (not found) الآن. فلنرَ كيف يمكننا إنشاؤه هنا في مجلد routes لدينا.

[00:55] إذًا كي نُنشئ معاملاتٍ اختيارية فعلنا ذلك بهذه الطريقة: نستخدم علامة الدولار (dollar sign) ثم اسم المعامل (parameter) بشكلٍ عادي. غير أنّه لنجعله اختياريًا نضعه بين أقواسٍ معقّفة (curly brackets) ثم نضع قبل المعامل علامة ناقص (minus). إذًا ناقص

[01:08] ثم علامة الدولار، والأول من هذه نحتاج إلى أن يكون هو اللغة، فلنجعله local، ثم شرطةً مائلة (slash) ثم archive، ثم شرطةً مائلة، وبعدها لدينا بقيةُ معاملاتنا الاختيارية وهي year.

[01:20] إذًا ناقص ثم علامة الدولار ثم year، ولدينا كذلك الشهر، وأخيرًا لدينا اليوم أيضًا.

[01:30] وبالطبع لا تنسَ tsx.

[01:32] غير أنّي فعلتها بحيث تُنشأ مجلداتٌ داخل بعضها بعضًا.

[01:37] وفلنفعلها أيضًا بالطريقة المسطّحة (flat)، فبدل إنشاء المجلدات لنستبدل هذه الشرطات المائلة بالنقاط بدلًا منها.

[01:46] وهكذا نواصل استخدامَ الطريقة المسطّحة التي كنّا نستخدمها. غير أنّه يمكنك بالطبع أن تفعلها بالمجلدات أيضًا.

[01:53] وبإنشائنا هذا سَتُطابَق (matched) مساراتُنا الآن. ويمكننا أن نرى في أدوات المطوّر (dev tools) أنّ لدينا هذا المسار ومعه معاملاتنا الاختيارية.

[02:04] ويمكننا ببساطة الوصول إلى معاملاتنا الاختيارية داخل مسارنا باستخدام خُطّاف (hook) use params أيضًا. إذًا عبر خُطّاف use params في مسارنا سنحصل على كل معاملاتنا: local وyear وday و

[02:24] month. ولاحظ هنا أنّ نوعها (type)، بما أنّها اختيارية، سَيَكُون string أو undefined.

[02:31] فلنعرض هذه هنا. سأضع هذا div على سبيل المثال كي نعرض معاملاتنا. والآن إن حفظنا فسنحصل على local وyear وmonth وday. غير أنّنا لسنا مضطرّين إلى تمريرها كلها؛ فيمكننا مثلًا أن نزيل اللغة

[02:44] من عنوان URL، فسنحصل على undefined. ويمكننا أن نزيل مثلًا day.

[02:49] سنحصل على undefined هنا، إلا أنّ المسار سيظلّ متطابقًا (matched).

[02:54] وبالطبع عندما نستخدم هذه المعاملات سيتعيّن علينا التحقّق من وجودها أو عدمه قبل أن ننفّذ أيّ إجراءٍ ما.

[03:02] والآن، وبالنسبة إلى الانتقال إلى هذا المسار وتمرير المعاملات الاختيارية، فنحن نستخدم ببساطة مكوّن Link (الرابط) أيضًا. فلتَحَوَّل إلى مسارنا الرئيسي (home) الذي موجود داخل index، ثم أضف رابطًا هنا وجرّب الانتقال إلى مسارنا ذي المعاملات

[03:18] الاختيارية.

[03:20] فلنجعله «الذهاب إلى الأرشيف» (go to archive)، ثم داخل to سنحتاج — عذرًا — إلى استيراد (import) Link أولًا.

[03:30] وداخل to سيتعيّن علينا وضع مسارنا، وهو هذا المسار. ثم يمكننا ببساطة تحديد معاملاتنا بواسطة الخاصية (prop) params هنا. غير أنّنا لسنا مضطرّين إلى وضع معاملاتنا كلها بما أنّها

[03:44] اختيارية؛ لذا يمكننا مثلًا أن نضع اللغة وحدها على سبيل المثال. فإن فعلنا ذلك سينقلنا هذا إلى language/archive من دون أيّ year ولا month ولا day. وبالطبع يمكننا مثلًا أن نضيف year.

[04:00] والآن — عذرًا — يجب أن يكون هذا أيضًا نصًّا (string). والآن سيأخذنا هذا الرابط إلى fr/archive ثم الشرطة المائلة ثم year وهكذا. ويمكننا أيضًا تمرير المعاملات كما رأينا سابقًا بوصفها دالةً (function) إذا رغبنا مثلًا في الحفاظ على

[04:15] معاملاتنا القائمة وأن نحدّث معاملًا واحدًا فقط. ويمكن أن يكون هذا مفيدًا جدًّا في حالتنا لإنشاء مبدّل لغاتٍ (language switcher) مثلًا. فلنقل مثلًا أنّنا نذهب إلى عنوان URL هو: language/archive ثم month — عذرًا — ثم month/day على سبيل

[04:34] المثال. والآن فلنقل أنّنا نحتاج إلى أن يكون هنا — في هذا المسار؛ لِنعُد إلى هذا المسار — طريقةٌ لتبديل لغاتنا، غير أنّ ذلك من دون أن يؤثر في التاريخ المحدَّد حاليًا. إذًا نحتاج فقط

[04:47] إلى تغيير هذا المعامل fr. ويمكن فعل ذلك بسهولة لأنّه يمكننا تمرير دالة إلى الخاصية params بدلًا من تمرير كائنٍ (object) فقط. فلتجدُّ هنا بضعةَ لغات

[05:02] متاحة (available)، فلنمرّ عليها ونعرض رابطًا سَيَنقلنا إلى عنوان URL القائم ولكنّه يحدّث اللغة فقط. إذًا هنا فلنضف div. وداخله سأعرضه فقط لأجل

[05:17] إضافة لون الخلفية والحاشية (padding) وما إلى ذلك. ثم داخله سأمرّ على لغاتي، أي languages.map، وفي هذه المصفوفة (array) لدينا code وname، فلنفكّك (destructure) هنا code وname.

[05:33] ثم فلنُرجِع مكوّن Link.

[05:36] فقم باستيراد Link مثل هذه. ثم لنضع — ربّما — اسمَ اللغة. عذرًا. أي اسم اللغة هنا. وبالطبع لنضف key أيضًا؛ فلنجعل code هي الـ key. فإن حفظنا هذا،

[05:52] فسَنحصل على هذا. ولكن الآن لننجعل هذا الرابط يذهب إلى مسارنا، وهو هذا المسار.

[06:01] ثم فلنمرّر معاملاتنا أيضًا.

[06:04] والآن فلنمرّره دالةً (function) بدلًا من ذلك كي نحافظ على معاملاتنا السابقة ولكنّنا نحدّث اللغة فقط. إذًا في previous سَنحصل على previous هنا، ويمكننا أن نُرجِع كائنًا (object) يحافظ على معاملاتنا السابقة

[06:18] ثم نضع local الجديد.

[06:22] أما local الجديد فلنقل أنّه إن كان English فلسنا بحاجة إلى وضعه، أي لا نحتاج إلى إضافته إلى عنوان URL لأنّه ربّما لغتُنا الافتراضية. فلنتحقّق هنا إن كانت لغتنا هي English.

[06:34] وإن لم نكن بحاجة إلى تمريره فيمكننا أن نحدّده صراحةً ليكون undefined.

[06:39] وإلا فمرّر code فقط هكذا.

[06:42] وسأضيف هذا الصنف (class name) هنا أيضًا كي أُبرز اللغة المحدَّدة حاليًا؛ فإذا كانت اللغة تساوي code الحالية، أو كانت اللغة undefined وكان code الحالي هو English، فسيتعيّن علينا إبراز

[06:56] English. إذًا سناجعل خطَّينا غامقًا (bold) في هذه الحالات. فالآن لدينا الفرنسية (French) مُبرَزةً هنا.

[07:04] لأنّ local لدينا هو الفرنسية. والآن يمكننا التبديل. ولاحظ أنّه عندما اخترنا English في عنوان URL لم يكن لدينا أيّ شيءٍ قبل archive لأنّ هذا ما فعلناه في شيفرتنا، وقد صار local لدينا undefined، وبقية

[07:19] معاملاتنا الاختيارية بقيت محفوظةً لأنّنا نمرّر هذه الدالة هنا ونحافظ على معاملاتنا السابقة.

[07:25] ويمكننا الانتقال إلى لغاتٍ أخرى كذلك، وسَيُحدِّث هذا عنوان URL لدينا.