عرض مصدر React/forwarding refs

<noinclude>{{DISPLAYTITLE:تمرير المراجع في React}}</noinclude>
تمرير المراجع هو تقنية لتمرير مرجع <code>[[React/refs and the dom|ref]]</code> تلقائيًّا من مكوّن إلى عناصره الأبناء. لا يكون هذا ضروريًّا بشكل نموذجي لمعظم مكوّنات التطبيق، ولكن قد يكون مفيدًا لبعض أنواع المكوّنات، خاصّة مكتبات المكوّنات القابلة لإعادة الاستخدام. سنتحدث في هذه الصفحة عن أشيع الحالات التي نحتاج فيها تمرير المراجع.

== تمرير المراجع إلى مكونات DOM ==
فلنأخذ مثال عن المكوّن <code>FancyButton</code> والذي يُصيِّر زر <code>button</code> في DOM:<syntaxhighlight lang="javascript">
function FancyButton(props) {
  return (
    <button className="FancyButton">
      {props.children}
    </button>
  );
}

</syntaxhighlight>تُخفي مكوّنات React تفاصيلها التنفيذية، بما في ذلك الناتج المُصيَّر. لا تحتاج المكوّنات الأخرى التي تستخدم المكوّن <code>FancyButton</code> عادةً إلى [[React/refs and the dom|الحصول على مرجع]] <code>ref</code> لعنصر الزر <code>button</code> الداخلي. يكون هذا جيّدًا لأنّه يمنع المكوّنات من الاعتماد كثيرًا على بنية DOM للمكوّنات الأخرى.

قد يكون مثل هذا التغليف مرغوبًا في مكوّنات التطبيق مثل <code>FeedStory</code> أو <code>Comment</code>، ولكنّه قد يكون غير ملائم بالنسبة للمكوّنات القابلة لإعادة الاستخدام بكثرة مثل <code>FancyButton</code> أو <code>MyTextInput</code>. تميل هذه المكوّنات لاستخدامها عبر التطبيق بنفس الطريقة مثل الزر <code>button</code> وحقل الإدخال <code>input</code> في DOM، وقد يكون الوصول إلى عقد DOM الخاصّة بها أمرًا لا بُدّ منه لإدارة التركيز، أو الاختيار، أو التحريكات.

'''تمرير المراجع هو عبارة عن ميزة تسمح لبعض المكوّنات باستقبال مرجع <code>ref</code> وتمريره إلى المستويات الأدنى إلى المكوّنات الأبناء.'''

يستخدم المكوّن <code>FancyButton</code> في المثال التالي <code>React.forwardRef</code> للحصول على المرجع <code>ref</code> المُمرَّر له، ومن ثمّ يُمرِّره إلى الزر <code>button</code> الذي يُصيِّره:<syntaxhighlight lang="javascript">
const FancyButton = React.forwardRef((props, ref) => (
  <button ref={ref} className="FancyButton">
    {props.children}
  </button>
));

// تستطيع الآن الحصول على مرجع بشكل مباشر للزر button
const ref = React.createRef();
<FancyButton ref={ref}>Click me!</FancyButton>;

</syntaxhighlight>بهذه الطريقة تستطيع المكوّنات التي تستخدم المكوّن <code>FancyButton</code> الحصول على مرجع للزر <code>button</code> والوصول إليه عند الضرورة كما لو أنّها تستخدم الزر بشكل مباشر.

وهذا شرح مُفصَّل عمّا حدث في المثال السابق:
# [[React/refs and the dom|أنشأنا مرجعًا]] <code>ref</code> عن طريق استدعاء <code>React.createRef</code> وتعيينه إلى المتغيّر ref.
# مرّرنا المرجع <code>ref</code> إلى المكوّن ‎<code><FancyButton ref={ref}></code>‎ عن طريق تحديده كخاصيّة JSX.
# تُمرِّر React المرجع <code>ref</code> إلى الدالة <code>‎(props, ref) => ...</code>‎ الموجودة بداخل التابع <code>forwardRef</code> كوسيط ثانٍ له.
# نُمرِّر هذا المرجع إلى الزر <code>‎‎<button ref={ref}></code>‎‎ عن طريق تحديده كخاصيّة JSX.
# عند ربط المرجع <code>ref</code> ستُشير <code>ref.current</code> إلى عقدة DOM الخاصّة بالزر <code>‎<button></code>‎.
'''ملاحظة:''' يُوجَد الوسيط الثاني <code>ref</code> فقط عندما تُعرِّف مكوّن باستخدام الاستدعاء <code>React.forwardRef</code>. لا تستقبل مكوّنات الأصناف أو الدوال الاعتيادية الوسيط <code>ref</code>، وهو ليس متوفر ضمن الخاصيّات حتى.

لا يكون تمرير المراجع محدودًا فقط لمكوّنات DOM، فبإمكانك تمرير المراجع إلى نُسَخ مكوّنات الأصناف أيضًا.

== ملاحظة بالنسبة لمكتبات المكونات ==
عندما تبدأ باستخدام <code>forwardRef</code> في مكتبة مكوّناتك الخاصّة، فيجب عليك معاملتها كتغيير جذري وإصدار رئيسي جديد من مكتبتك، وذلك لأنّه من الغالب أنّ مكتبتك لديها سلوك ملحوظ مختلف تمامًا (مثل الأشياء التي نُعيِّن إليها المراجع، والأنواع المستخرجة) وقد يُعطِّل هذا التطبيقات والمكتبات الأخرى التي تعتمد على السلوك القديم.

لا نوصي بتطبيق <code>React.forwardRef</code> بشكلٍ شرطي عند وجودها لنفس الأسباب، فهي تغيّر سلوك مكتبتك وقد تُعطِّل تطبيقات مستخدميك عند تحديثهم لمكتبة React بحد ذاتها.

== تمرير المراجع في المكونات ذات الترتيب الأعلى ==
تكون هذه الطريقة مفيدة بشكل خاص مع [[React/higher order components|المكوّنات ذات الترتيب الأعلى]] (higher-order components واختصارًا HOCs). فلنبدأ بمثال عن المكوّنات ذات الترتيب الأعلى والذي يعرض خاصيّات المكوّنات في الكونسول:<syntaxhighlight lang="javascript">
function logProps(WrappedComponent) {
  class LogProps extends React.Component {
    componentDidUpdate(prevProps) {
      console.log('old props:', prevProps);
      console.log('new props:', this.props);
    }

    render() {
      return <WrappedComponent {...this.props} />;
    }
  }

  return LogProps;
}
</syntaxhighlight>يُمرِّر المكوّن <code>logProps</code> كل الخاصيّات عبر المكوّن الذي يُغلِّفه، لذا سيكون الناتج المُصيَّر نفسه. فمثلًا نستطيع استخدام هذا المكوّن ذو الترتيب الأعلى لعرض جميع الخاصيّات المُمرَّرة إلى المكوّن <code>FancyButton</code>:<syntaxhighlight lang="javascript">
class FancyButton extends React.Component {
  focus() {
    // ...
  }

  // ...
}

// بدلا من استخراج FancyButton
// نستخرج LogProps
/// سيصير المكون FancyButton رغم ذلك
export default logProps(FancyButton);

</syntaxhighlight>هنالك شيء واحد يجب الانتباه له في المثال السابق وهو عدم القدرة على تمرير المراجع وذلك لأنّ <code>ref</code> ليست خاصيّة مثل المفتاح <code>key</code> مثلًا، حيث تُعامِلها React بشكلٍ مختلف. إن أضفت مرجعًا إلى المكوّن ذو الترتيب الأعلى فسيُشير إلى المكوّن الخارجي الحاوي وليس المكوّن المُغلّف.

هذا يعني أنّ المراجع المُخصَّصة من أجل المكوّن <code>FancyButton</code> سترتبط فعليًّا بالمكوّن <code>LogProps</code>:<syntaxhighlight lang="javascript">
import FancyButton from './FancyButton';

const ref = React.createRef();

// المكوّن FancyButton الذي استوردناه في المكوّن LogProps
// على الرغم من بقاء الناتج نفسه
// سيشير المرجع إلى LogProps بدلًا من المكوّن FancyButton الداخلي
// يعني هذا عدم قدرتنا على استدعاء ref.current.focus()

<FancyButton
  label="انقر هنا"
  handleClick={handleClick}
  ref={ref}
/>;

</syntaxhighlight>لحسن الحظ نستطيع تمرير المراجع إلى المكوّن الداخلي <code>FancyButton</code> باستخدام <code>React.forwardRef</code> والتي تقبل دالة تصيير تستقبل مُعامِلات للخاصيّات <code>props</code> والمرجع <code>ref</code> وتُعيد عقدة React، على سبيل المثال:<syntaxhighlight lang="javascript">
function logProps(Component) {
  class LogProps extends React.Component {
    componentDidUpdate(prevProps) {
      console.log('old props:', prevProps);
      console.log('new props:', this.props);
    }

    render() {
      const {forwardedRef, ...rest} = this.props;

	  // تعين الخاصية المخصصة forwardedRef كمرجع
      return <Component ref={forwardedRef} {...rest} />;
    }
  }

  // لاحظ أن المعامل الثاني ref زودتنا به React.forwardRef
  // نستطيع تمريره إلى LogProps كخاصية اعتيادية forwardedRef
  // وبعدها يمكن ربطه بالمكون
  return React.forwardRef((props, ref) => {
    return <LogProps {...props} forwardedRef={ref} />;
  });
}

</syntaxhighlight>

== عرض اسم مخصص في أدوات التطوير ==
يقبل <code>React.forwardRef</code> دالة تصيير. تستخدم أدوات تطوير React هذه الدالة لتحديد ماذا ستعرض من أجل المكوّن الذي يُمرِّر المرجع.

على سبيل المثال سيظهر المكوّن التالي بالاسم <code>"ForwardRef"</code> في أدوات التطوير:<syntaxhighlight lang="javascript">
const WrappedComponent = React.forwardRef((props, ref) => {
  return <LogProps {...props} forwardedRef={ref} />;
});

</syntaxhighlight>إن سميت دالة التصيير فستُضمّن أدوات التطوير اسمها (على الشكل ‎<code>"ForwardRef(myFunction)"‎</code>):<syntaxhighlight lang="javascript">
const WrappedComponent = React.forwardRef(
  function myFunction(props, ref) {
    return <LogProps {...props} forwardedRef={ref} />;
  }
);

</syntaxhighlight>بإمكانك أيضًا تعيين الخاصيّة <code>displayName</code> لتضمين المكوّن الذي تُغلِّفه:<syntaxhighlight lang="javascript">
function logProps(Component) {
  class LogProps extends React.Component {
    // ...
  }

  function forwardRef(props, ref) {
    return <LogProps {...props} forwardedRef={ref} />;
  }

  // إعطاء هذا المكون اسمًا أكثر فائدة في أدوات التطوير
  // e.g. "ForwardRef(logProps(MyComponent))"
  
  const name = Component.displayName || Component.name;
  forwardRef.displayName = `logProps(${name})`;

  return React.forwardRef(forwardRef);
}


</syntaxhighlight>
== انظر أيضًا ==
* [[React/jsx in depth|شرح JSX بالتفصيل]]
* [[React/static type checking|التحقق من الأنواع الثابتة]]
* [[React/typechecking with proptypes|التحقق من الأنواع باستخدام PropTypes]]
* [[React/refs and the dom|استخدام المراجع مع DOM]]
* [[React/uncontrolled components|المكونات غير المضبوطة]]
* [[React/optimizing performance|تحسين الأداء]]
* [[React/react without es6|React بدون ES6]]
* [[React/react without jsx|React بدون JSX]]
* [[React/reconciliation|المطابقة (Reconciliation)]]
* [[React/context|استخدام السياق (Context) في React]]
* [[React/fragments|استخدام الأجزاء (Fragments) في React]]
* [[React/portals|المداخل (Portals) في React]]
* [[React/error boundaries|حدود الأخطاء]]
* [[React/web components|مكونات الويب]]
* [[React/higher order components|المكونات ذات الترتيب الأعلى]]
* [[React/render props|خاصيات التصيير]]
* [[React/integrating with other libraries|تكامل React مع المكتبات الأخرى]]
* [[React/accessibility|سهولة الوصول]]
* [[React/code splitting|تقسيم الشيفرة]]
* [[React/strict mode|الوضع الصارم (Strict Mode)]]

== مصادر==
*[https://reactjs.org/docs/forwarding-refs.html صفحة تمرير المراجع في توثيق React الرسمي].
[[تصنيف:React]]
[[تصنيف:React Advanced Guides]]