useImperativeHandle: قيم النسخة المخصصة

عند تمرير ref مباشرةً إلى عنصر DOM، يتلقى الأب عقدة DOM الأولية ويحصل على إمكانية الوصول إلى كل أساليبها وخصائصها الأصلية. وغالبًا ما تكون هذه مساحة وصول أكبر مما تريدون إتاحته.

قد تفضّلون أحيانًا تسليم الأب كائن صغيرًا ومنتقًى بدلًا من عقدة DOM كاملة، للحفاظ عمدًا على ضيق واجهة API العامة للمكوّن.

يتيح useImperativeHandle تخصيص القيمة التي يشير إليها ref الخاص بالأب. فبدلًا من عقدة DOM، يتلقى الأب أي كائن تعيدونه، وبذلك تقررون بدقة الأساليب والقيم التي ستتم إتاحتها.

يحوّل ذلك ref المُمرَّر إلى واجهة إجرائية محددة، بدلًا من أن يكون مجرد تمرير مكشوف إلى العنصر الأساسي.

يأخذ الخطاف ref المُمرَّر كمعامل أول، ودالة مُنشئة كمعامل ثانٍ. وتعيد الدالة المُنشئة كائن المقبض الذي يصبح ref.current لدى الأب.

تستدعونه كما يلي: useImperativeHandle(ref, () => ({ ... }))، مع إنشاء كائن الأساليب والقيم التي تريدون إتاحتها من داخل الدالة المُنشئة.

من الأنماط الشائعة إنشاء input مخصص لا يتيح سوى focus وclear. تعيدون داخل الدالة المُنشئة كائنًا يتضمن هذين الأسلوبين، ويعمل كل منهما على ref داخلي يشير إلى input الحقيقي.

يمكن للأب الآن تركيز الحقل أو مسحه، لكنه لا يستطيع قراءة سمة value الأولية أو تشغيل سلوك DOM عشوائي، ما يحافظ على قابلية التنبؤ عند الاستخدام.

تلائم المقابض الإجرائية مربعات الحوار جيدًا. إذ يمكن لمكوّن Modal إتاحة أسلوبي open وclose اللذين يبدّلان حالة الظهور الداخلية، ما يسمح للأب بالتحكم فيه إجرائيًا من دون إدارة القيمة المنطقية open بنفسه.

يفيد ذلك في الشيفرة التي تحتاج إلى تشغيل مربع حوار من مواضع متعددة، مثل عرض تأكيد بعد اكتمال إجراء غير متزامن.

من خلال إعادة الأساليب التي تنوون دعمها فقط، تنشئون عقدًا واضحًا. يعتمد المستهلكون على مجموعة صغيرة وموثقة من العمليات بدلًا من واجهة DOM الواسعة، ما يجعل عمليات إعادة الهيكلة المستقبلية أكثر أمانًا.

وتكون مساحة الوصول الإجرائية الضيقة أسهل في الاختبار والفهم، كما تقل احتمالية كسرها كثيرًا عند تغيير التنفيذ الداخلي.

يقبل useImperativeHandle معاملًا ثالثًا اختياريًا، هو مصفوفة التبعيات. عند تغيّر أي تبعية، تُشغّل الدالة المُنشئة من جديد ويُعاد إنشاء كائن المقبض، على نحو مشابه لما يحدث مع useMemo وuseEffect.

إذا كانت الأساليب التي تتيحونها تعتمد على قيم يمكن أن تتغير، فأدرجوا تلك القيم ضمن التبعيات حتى يتلقى الأب دائمًا مقبضًا مرتبطًا بالحالة الحالية.

لا يكون useImperativeHandle مفيدًا إلا داخل مكوّن مغلّف باستخدام forwardRef، لأنه يحتاج إلى ref المُمرَّر لإسناد المقبض المخصص إليه. ولولاه، فلن يكون هناك ref من الأب لملؤه.

لذلك يُستخدم الاثنان معًا: يُدخل forwardRef الـ ref، ويحدد useImperativeHandle ما سينتهي هذا ref إلى الإشارة إليه.

لاختبار مقبض، صيّروا المكوّن مع ref، ثم استدعوا الأساليب عبر ref.current داخل كتلة act، وتحققوا من السلوك الناتج أو تغييرات DOM.

وبما أن الواجهة المُتاحة صغيرة وصريحة، تكون هذه الاختبارات مركّزة؛ فهي تتحقق من أن كل أسلوب موثق ينفذ ما يعد به عقده، بدلًا من فحص التفاصيل الداخلية.

في TypeScript، عرّفوا واجهة تصف المقبض، مثل واجهة تتضمن أسلوبي focus وclear، ثم استخدموها لتحديد نوع كل من المعامل العام لـ forwardRef وref الذي يحتفظ به الأب.

يوفر ذلك الإكمال التلقائي وعمليات التحقق أثناء الترجمة في موضع الاستدعاء، بحيث يرى المستهلكون الأساليب الموجودة بالضبط، ويُكتشف سوء الاستخدام قبل وقت التشغيل.

تحققوا من الغرض الفعلي لـ useImperativeHandle.

يخصص useImperativeHandle ما يتيحه ref مُمرَّر، إذ يستقبل ref ودالة مُنشئة تعيد كائن مقبض. وتستخدمونه لإتاحة واجهة صغيرة مثل focus وclear، أو open وclose في مربع حوار.

ويُقرن دائمًا مع forwardRef، ويدعم مصفوفة تبعيات لتحديث المقبض، كما يتكامل جيدًا مع واجهات TypeScript والاختبارات المركّزة. إن تقييد مساحة الواجهة أمر مقصود وتصميم جيد.