React forwardRef: راهنمای جامع برای ارسال مرجع

در ری‌اکت، دسترسی مستقیم به یک گره DOM از یک کامپوننت فرزند می‌تواند چالش‌برانگیز باشد. اینجاست که forwardRef وارد عمل می‌شود و مکانیزمی برای ارسال یک ref به کامپوننت فرزند فراهم می‌کند. این مقاله به بررسی عمیق forwardRef می‌پردازد، هدف، کاربرد و مزایای آن را توضیح می‌دهد و شما را با دانش لازم برای استفاده مؤثر از آن در پروژه‌های ری‌اکت خود مجهز می‌کند.

forwardRef چیست؟

forwardRef یک API در ری‌اکت است که به کامپوننت والد اجازه می‌دهد یک ref به گره DOM درون کامپوننت فرزند دریافت کند. بدون forwardRef، refها معمولاً به کامپوننتی که در آن ایجاد شده‌اند محدود می‌شوند. این محدودیت می‌تواند تعامل مستقیم با DOM زیربنایی یک کامپوننت فرزند از والد آن را دشوار کند.

اینطور به آن فکر کنید: تصور کنید یک کامپوننت ورودی سفارشی دارید و می‌خواهید هنگام mount شدن کامپوننت، فیلد ورودی به طور خودکار focus شود. بدون forwardRef، کامپوننت والد راهی برای دسترسی مستقیم به گره DOM ورودی نخواهد داشت. با forwardRef، والد می‌تواند یک مرجع به فیلد ورودی نگه دارد و متد focus() را روی آن فراخوانی کند.

چرا از forwardRef استفاده کنیم؟

در اینجا چند سناریوی رایج وجود دارد که forwardRef بسیار ارزشمند است:

• دسترسی به گره‌های DOM فرزند: این اصلی‌ترین مورد استفاده است. کامپوننت‌های والد می‌توانند مستقیماً گره‌های DOM درون فرزندان خود را دستکاری کرده یا با آنها تعامل داشته باشند.
• ایجاد کامپوننت‌های قابل استفاده مجدد: با ارسال refها، می‌توانید کامپوننت‌های انعطاف‌پذیرتر و قابل استفاده مجددتری بسازید که به راحتی در بخش‌های مختلف برنامه شما ادغام شوند.
• یکپارچه‌سازی با کتابخانه‌های شخص ثالث: برخی از کتابخانه‌های شخص ثالث به دسترسی مستقیم به گره‌های DOM نیاز دارند. forwardRef به شما امکان می‌دهد این کتابخانه‌ها را به طور یکپارچه در کامپوننت‌های ری‌اکت خود ادغام کنید.
• مدیریت فوکوس و انتخاب: همانطور که قبلاً نشان داده شد، مدیریت فوکوس و انتخاب در سلسله‌مراتب پیچیده کامپوننت‌ها با forwardRef بسیار ساده‌تر می‌شود.

forwardRef چگونه کار می‌کند

forwardRef یک کامپوننت مرتبه بالاتر (HOC) است. این تابع یک تابع رندر را به عنوان آرگومان خود می‌گیرد و یک کامپوننت ری‌اکت برمی‌گرداند. تابع رندر props و ref را به عنوان آرگومان دریافت می‌کند. آرگومان ref همان refی است که کامپوننت والد به پایین پاس می‌دهد. در داخل تابع رندر، می‌توانید این ref را به یک گره DOM در کامپوننت فرزند متصل کنید.

سینتکس پایه

سینتکس پایه forwardRef به شرح زیر است:

const MyComponent = React.forwardRef((props, ref) => {
  // Component logic here
  return 
...
;
});

بیایید این سینتکس را تجزیه کنیم:

• React.forwardRef(): این تابعی است که کامپوننت شما را در بر می‌گیرد.
• (props, ref) => { ... }: این تابع رندر است. این تابع props کامپوننت و ref ارسال شده از والد را دریافت می‌کند.
• <div ref={ref}>...</div>: اینجاست که جادو اتفاق می‌افتد. شما ref دریافت شده را به یک گره DOM در کامپوننت خود متصل می‌کنید. این گره DOM سپس برای کامپوننت والد قابل دسترسی خواهد بود.

مثال‌های عملی

بیایید چند مثال عملی را بررسی کنیم تا نشان دهیم چگونه می‌توان از forwardRef در سناریوهای دنیای واقعی استفاده کرد.

مثال ۱: فوکوس کردن روی یک فیلد ورودی

در این مثال، ما یک کامپوننت ورودی سفارشی ایجاد می‌کنیم که هنگام mount شدن، به طور خودکار روی فیلد ورودی فوکوس می‌کند.

import React, { useRef, useEffect } from 'react';

const FancyInput = React.forwardRef((props, ref) => {
  return (
    <input ref={ref} type="text" className="fancy-input" {...props} />
  );
});

function ParentComponent() {
  const inputRef = useRef(null);

  useEffect(() => {
    if (inputRef.current) {
      inputRef.current.focus();
    }
  }, []);

  return (
    <FancyInput ref={inputRef} placeholder="Focus me!" />
  );
}

export default ParentComponent;

توضیح:

1. FancyInput با استفاده از React.forwardRef ایجاد شده است. این کامپوننت props و ref را دریافت می‌کند.
2. ref به عنصر <input> متصل می‌شود.
3. ParentComponent با استفاده از useRef یک ref ایجاد می‌کند.
4. ref به FancyInput پاس داده می‌شود.
5. در هوک useEffect، هنگام mount شدن کامپوننت، روی فیلد ورودی فوکوس می‌شود.

مثال ۲: دکمه سفارشی با مدیریت فوکوس

بیایید یک کامپوننت دکمه سفارشی بسازیم که به والد اجازه می‌دهد فوکوس را کنترل کند.

import React, { forwardRef } from 'react';

const MyButton = forwardRef((props, ref) => {
  return (
    <button ref={ref} className="my-button" {...props}>
      {props.children}
    </button>
  );
});

function App() {
  const buttonRef = React.useRef(null);

  const focusButton = () => {
    if (buttonRef.current) {
      buttonRef.current.focus();
    }
  };

  return (
    <div>
      <MyButton ref={buttonRef} onClick={() => alert('Button Clicked!')}>
        Click Me
      </MyButton>
      <button onClick={focusButton}>Focus Button</button>
    </div>
  );
}

export default App;

توضیح:

1. MyButton از forwardRef برای ارسال ref به عنصر دکمه استفاده می‌کند.
2. کامپوننت والد (App) از useRef برای ایجاد یک ref استفاده می‌کند و آن را به MyButton پاس می‌دهد.
3. تابع focusButton به والد اجازه می‌دهد تا به صورت برنامه‌ریزی شده روی دکمه فوکوس کند.

مثال ۳: یکپارچه‌سازی با یک کتابخانه شخص ثالث (مثال: react-select)

بسیاری از کتابخانه‌های شخص ثالث به دسترسی به گره DOM زیربنایی نیاز دارند. بیایید نشان دهیم چگونه می‌توان forwardRef را با یک سناریوی فرضی با استفاده از react-select ادغام کرد، جایی که ممکن است نیاز به دسترسی به عنصر ورودی select داشته باشید.

نکته: این یک تصویرسازی فرضی و ساده شده است. برای روش‌های رسمی پشتیبانی شده برای دسترسی و سفارشی‌سازی کامپوننت‌های react-select، به مستندات واقعی آن مراجعه کنید.

import React, { useRef, useEffect } from 'react';
// Assuming a simplified react-select interface for demonstration
import Select from 'react-select'; // Replace with actual import

const CustomSelect = React.forwardRef((props, ref) => {
  return (
    <Select ref={ref} {...props} />
  );
});

function MyComponent() {
  const selectRef = useRef(null);

  useEffect(() => {
    // Hypothetical: Accessing the input element within react-select
    if (selectRef.current && selectRef.current.inputRef) {  // inputRef is a hypothetical prop
      console.log('Input Element:', selectRef.current.inputRef.current);
    }
  }, []);

  return (
    <CustomSelect
      ref={selectRef}
      options={[
        { value: 'chocolate', label: 'Chocolate' },
        { value: 'strawberry', label: 'Strawberry' },
        { value: 'vanilla', label: 'Vanilla' },
      ]}
    />
  );
}

export default MyComponent;

ملاحظات مهم برای کتابخانه‌های شخص ثالث:

• مشاوره با مستندات کتابخانه: همیشه مستندات کتابخانه شخص ثالث را بررسی کنید تا روش‌های توصیه شده برای دسترسی و دستکاری کامپوننت‌های داخلی آن را درک کنید. استفاده از روش‌های غیرمستند یا پشتیبانی نشده می‌تواند منجر به رفتار غیرمنتظره یا خرابی در نسخه‌های آینده شود.
• دسترس‌پذیری: هنگام دسترسی مستقیم به گره‌های DOM، اطمینان حاصل کنید که استانداردهای دسترس‌پذیری را حفظ می‌کنید. راه‌های جایگزین برای کاربرانی که به فناوری‌های کمکی متکی هستند برای تعامل با کامپوننت‌های شما فراهم کنید.

بهترین شیوه‌ها و ملاحظات

در حالی که forwardRef ابزار قدرتمندی است، استفاده عاقلانه از آن ضروری است. در اینجا چند بهترین شیوه و ملاحظاتی که باید در نظر داشته باشید آورده شده است:

• از استفاده بیش از حد خودداری کنید: اگر جایگزین‌های ساده‌تری وجود دارد از forwardRef استفاده نکنید. برای ارتباط بین کامپوننت‌ها، استفاده از props یا توابع callback را در نظر بگیرید. استفاده بیش از حد از forwardRef می‌تواند درک و نگهداری کد شما را دشوارتر کند.
• کپسوله‌سازی را حفظ کنید: مراقب شکستن کپسوله‌سازی باشید. دستکاری مستقیم گره‌های DOM کامپوننت‌های فرزند می‌تواند کد شما را شکننده‌تر و بازسازی آن را دشوارتر کند. تلاش کنید تا دستکاری مستقیم DOM را به حداقل برسانید و هر زمان که ممکن بود به API داخلی کامپوننت تکیه کنید.
• دسترس‌پذیری: هنگام کار با refها و گره‌های DOM، همیشه دسترس‌پذیری را در اولویت قرار دهید. اطمینان حاصل کنید که کامپوننت‌های شما برای افراد دارای معلولیت قابل استفاده هستند. از HTML معنایی استفاده کنید، ویژگی‌های ARIA مناسب را ارائه دهید و کامپوننت‌های خود را با فناوری‌های کمکی آزمایش کنید.
• چرخه حیات کامپوننت را درک کنید: آگاه باشید که ref چه زمانی در دسترس قرار می‌گیرد. ref معمولاً پس از mount شدن کامپوننت در دسترس است. از useEffect برای دسترسی به ref پس از رندر شدن کامپوننت استفاده کنید.
• استفاده با تایپ‌اسکریپت: اگر از تایپ‌اسکریپت استفاده می‌کنید، مطمئن شوید که refها و کامپوننت‌هایی که از forwardRef استفاده می‌کنند را به درستی تایپ‌دهی کرده‌اید. این به شما کمک می‌کند تا خطاها را زودتر تشخیص دهید و ایمنی نوع کلی کد خود را بهبود بخشید.

جایگزین‌های forwardRef

در برخی موارد، جایگزین‌هایی برای استفاده از forwardRef وجود دارد که ممکن است مناسب‌تر باشند:

• Props و Callbacks: انتقال داده و رفتار از طریق props اغلب ساده‌ترین و ترجیح داده‌شده‌ترین راه برای ارتباط بین کامپوننت‌ها است. اگر فقط نیاز به انتقال داده یا فراخوانی یک تابع در فرزند دارید، props و callbacks معمولاً بهترین انتخاب هستند.
• Context: برای به اشتراک گذاشتن داده بین کامپوننت‌هایی که به شدت تودرتو هستند، Context API ری‌اکت می‌تواند جایگزین خوبی باشد. Context به شما اجازه می‌دهد تا داده‌ها را به کل زیردرخت کامپوننت‌ها بدون نیاز به پاس دادن دستی props در هر سطح، ارائه دهید.
• Imperative Handle: هوک useImperativeHandle را می‌توان در ترکیب با forwardRef برای افشای یک API محدود و کنترل‌شده به کامپوننت والد استفاده کرد، به جای افشای کل گره DOM. این کار کپسوله‌سازی بهتری را حفظ می‌کند.

کاربرد پیشرفته: useImperativeHandle

هوک useImperativeHandle به شما اجازه می‌دهد تا مقدار نمونه‌ای (instance value) را که هنگام استفاده از forwardRef به کامپوننت‌های والد افشا می‌شود، سفارشی کنید. این امر کنترل بیشتری بر آنچه کامپوننت والد می‌تواند به آن دسترسی داشته باشد فراهم می‌کند و کپسوله‌سازی بهتری را ترویج می‌دهد.

import React, { forwardRef, useImperativeHandle, useRef } from 'react';

const FancyInput = forwardRef((props, ref) => {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    focus: () => {
      inputRef.current.focus();
    },
    getValue: () => {
      return inputRef.current.value;
    },
  }));

  return <input ref={inputRef} type="text" {...props} />;
});

function ParentComponent() {
  const inputRef = useRef(null);

  const handleFocus = () => {
    inputRef.current.focus();
  };

  const handleGetValue = () => {
    alert(inputRef.current.getValue());
  };

  return (
    <div>
      <FancyInput ref={inputRef} placeholder="Enter text" />
      <button onClick={handleFocus}>Focus Input</button>
      <button onClick={handleGetValue}>Get Value</button>
    </div>
  );
}

export default ParentComponent;

توضیح:

1. کامپوننت FancyInput از useRef برای ایجاد یک ref داخلی (inputRef) برای عنصر ورودی استفاده می‌کند.
2. useImperativeHandle برای تعریف یک شیء سفارشی استفاده می‌شود که از طریق ref ارسال شده به کامپوننت والد افشا خواهد شد. در این مورد، ما یک تابع focus و یک تابع getValue را افشا می‌کنیم.
3. کامپوننت والد سپس می‌تواند این توابع را از طریق ref بدون دسترسی مستقیم به گره DOM عنصر ورودی فراخوانی کند.

عیب‌یابی مشکلات رایج

در اینجا برخی از مشکلات رایجی که ممکن است هنگام استفاده از forwardRef با آنها مواجه شوید و نحوه عیب‌یابی آنها آورده شده است:

• Ref تهی (null) است: اطمینان حاصل کنید که ref به درستی از کامپوننت والد به پایین پاس داده شده است و کامپوننت فرزند به درستی ref را به یک گره DOM متصل می‌کند. همچنین، مطمئن شوید که پس از mount شدن کامپوننت به ref دسترسی پیدا می‌کنید (مثلاً در یک هوک useEffect).
• خطای 'Cannot read property 'focus' of null': این معمولاً نشان می‌دهد که ref به درستی به گره DOM متصل نشده است، یا اینکه گره DOM هنوز رندر نشده است. ساختار کامپوننت خود را دوباره بررسی کنید و اطمینان حاصل کنید که ref به عنصر صحیح متصل شده است.
• خطاهای نوع (Type) در تایپ‌اسکریپت: مطمئن شوید که refهای شما به درستی تایپ‌دهی شده‌اند. از React.RefObject<HTMLInputElement> (یا نوع عنصر HTML مناسب) برای تعریف نوع ref خود استفاده کنید. همچنین، اطمینان حاصل کنید که کامپوننتی که از forwardRef استفاده می‌کند به درستی با React.forwardRef<HTMLInputElement, Props> تایپ‌دهی شده است.
• رفتار غیرمنتظره: اگر با رفتار غیرمنتظره‌ای مواجه شدید، کد خود را با دقت بررسی کنید و مطمئن شوید که به طور تصادفی DOM را به روش‌هایی که می‌تواند با فرآیند رندر ری‌اکت تداخل داشته باشد، دستکاری نمی‌کنید. از React DevTools برای بازرسی درخت کامپوننت خود و شناسایی هرگونه مشکل احتمالی استفاده کنید.

نتیجه‌گیری

forwardRef ابزار ارزشمندی در جعبه ابزار توسعه‌دهندگان ری‌اکت است. این ابزار به شما امکان می‌دهد تا شکاف بین کامپوننت‌های والد و فرزند را پر کنید، دستکاری مستقیم DOM را ممکن می‌سازد و قابلیت استفاده مجدد کامپوننت را افزایش می‌دهد. با درک هدف، کاربرد و بهترین شیوه‌های آن، می‌توانید از forwardRef برای ایجاد برنامه‌های ری‌اکت قدرتمندتر، انعطاف‌پذیرتر و قابل نگهداری‌تر استفاده کنید. به یاد داشته باشید که از آن عاقلانه استفاده کنید، دسترس‌پذیری را در اولویت قرار دهید و همیشه تلاش کنید تا کپسوله‌سازی را در هر زمان ممکن حفظ کنید.

این راهنمای جامع دانش و مثال‌های لازم را برای پیاده‌سازی با اطمینان forwardRef در پروژه‌های ری‌اکت شما فراهم کرده است. کدنویسی خوبی داشته باشید!