API Referansı
Hook'lar

useImperativeHandle

useImperativeHandle, bir ref olarak açığa çıkarılan tanımlayıcıyı özelleştirmenizi sağlayan bir React Hook’udur.

useImperativeHandle(ref, createHandle, dependencies?)

Başvuru dokümanı

useImperativeHandle(ref, createHandle, dependencies?)

Açığa çıkarılan ref tanımlayıcısını özelleştirmek için bileşeninizin üst düzeyinde useImperativeHandle’ı çağırın:

import { forwardRef, useImperativeHandle } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
  useImperativeHandle(ref, () => {
    return {
      // ... metotlarınız ...
    };
  }, []);
  // ...

Daha fazla örnek için aşağıya bakınız.

Parametreler

  • ref: forwardRef render fonksiyonunun ikinci argümanı olarak aldığınız ref.

  • createHandle: Herhangi bir argüman almayan ve açığa çıkarmak istediğiniz ref tanımlayıcısını döndüren bir fonksiyondur. Bu ref tanımlayıcısı herhangi bir tipte olabilir. Genellikle, açığa çıkarmak istediğiniz metotların bulunduğu bir nesne döndürürsünüz.

  • isteğe bağlı dependencies: createHandle kodu içinde referans alınan tüm tepkisel değerlerin listesidir. Tepkisel değerler, prop’lar, state ve bileşeninizin doğrudan içerisinde bildirilen tüm değişkenler ve fonskiyonlar gibi değerleri içerir. Eğer linter’ınız React için yapılandırılmışsa, her tepkisel değerin doğru bir şekilde bağımlılık(dependency) olarak belirtildiğini doğrular. Bağımlılık listesi, sabit bir sayıda öğeye sahip olmalı ve [dep1, dep2, dep3] gibi iç içe yazılmalıdır. React, her bir bağımlılığı önceki değeriyle Object.is karşılaştırması kullanarak karşılaştırır. Eğer bir yeniden render’lama, bazı bağımlılıklarda değişikliğe neden olduysa veya bu argümanı atladıysanız, createHandle fonksiyonunuz yeniden çalıştırılır ve yeni oluşturulan tanımlayıcı ref’e atanır.

Dönüş değerleri

useImperativeHandle, undefined döndürür.

Kullanım

Özel bir ref tanımlayıcısını üst elemana açığa çıkarma

Bileşenler DOM düğümlerini varsayılan olarak üst elemana açığa çıkarmazlar. Örneğin, MyInput bileşeninin üst elemanın <input> DOM düğümüne erişmesini istiyorsanız, forwardRef ile tercih etmelisiniz.

import { forwardRef } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
  return <input {...props} ref={ref} />;
});

Yukarıdaki kodla bir MyInput bileşenine ait ref, <input> DOM düğümünü alacaktır. Ancak, isteğe bağlı olarak özel bir değer de açığa çıkarabilirsiniz. Açığa çıkarılan tanımlayıcıyı özelleştirmek için bileşeninizin üst düzeyinde useImperativeHandle’ı çağırın.

import { forwardRef, useImperativeHandle } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
  useImperativeHandle(ref, () => {
    return {
      // ... metotlarınız ...
    };
  }, []);

  return <input {...props} />;
});

Yukarıdaki koda dikkat ettiğinizde, ref artık <input> bileşenine iletilmediğini fark edeceksiniz.

Örneğin, <input> DOM düğümünün tamamını açığa çıkarmak istemiyorsunuz, ancak focus ve scrollIntoView gibi iki metodu açığa çıkarmak istiyorsunuz. Bunun için gerçek tarayıcı DOM’unu ayrı bir ref içinde tutun. Ardından, yalnızca üst elemanın çağırmasını istediğiniz metotlara sahip bir tanımlayıcıyı açığa çıkarmak için useImperativeHandle’ı kullanın:

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

const MyInput = forwardRef(function MyInput(props, ref) {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => {
    return {
      focus() {
        inputRef.current.focus();
      },
      scrollIntoView() {
        inputRef.current.scrollIntoView();
      },
    };
  }, []);

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

Artık, eğer üst eleman MyInput için bir ref alırsa, onun üzerinde focus ve scrollIntoView metotlarını çağırabilecektir. Ancak, altında bulunan <input> DOM düğümüne tam erişimi olmayacaktır.

import { useRef } from 'react';
import MyInput from './MyInput.js';

export default function Form() {
  const ref = useRef(null);

  function handleClick() {
    ref.current.focus();
    // DOM düğümü açığa çıkarılmadığı için bu çalışmayacaktır:
    // ref.current.style.opacity = 0.5;
  }

  return (
    <form>
      <MyInput placeholder="Adınızı girin" ref={ref} />
      <button type="button" onClick={handleClick}>
        Düzenle
      </button>
    </form>
  );
}

Zorunlu fonksiyonlarızı açığa çıkarma

İstemci tarafından kullanılabilir hâle getirdiğiniz metotlar, DOM metotlarıyla tam olarak eşleşmek zorunda değildir. Örneğin, bu Post bileşeni, bir istemci tarafından kullanılabilir hâle getirilen scrollAndFocusAddComment metodunu açığa çıkarır. Bu, üst eleman olan Page’in, butona tıklandığında yorum listesine kaydırmasına ve giriş alanına odaklanmasına olanak tanır:

import { useRef } from 'react';
import Post from './Post.js';

export default function Page() {
  const postRef = useRef(null);

  function handleClick() {
    postRef.current.scrollAndFocusAddComment();
  }

  return (
    <>
      <button onClick={handleClick}>
        Bir yorum yazın
      </button>
      <Post ref={postRef} />
    </>
  );
}

Tuzak

Ref’leri aşırı kullanmayın. Ref’leri sadece, prop olarak ifade edemeyeceğiniz zorunlu davranışlar için kullanmalısınız: örneğin, bir düğüme kaydırmak, bir düğüme odaklanmak, bir animasyonu tetiklemek, metin seçmek vb.

Bir şeyi bir prop olarak ifade edebiliyorsanız, bir ref kullanmamalısınız. Örneğin, bir Modal bileşeninden { open, close } gibi bir ref açığa çıkarmak yerine, <Modal isOpen={isOpen} /> gibi bir isOpen prop’unu almak daha iyidir. Effect’ler, ref’leri prop’lar aracılığıyla açığa çıkarmada size yardımcı olabilir.

PrevioususeId
NextuseInsertionEffect