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 { useImperativeHandle } from 'react';

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

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

Parametreler

  • ref: The ref you received as a prop to the MyInput component.

  • 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.

Not

Starting with React 19, ref is available a prop. In React 18 and earlier, it was necessary to get the ref from forwardRef.

Returns

useImperativeHandle, undefined döndürür.

Kullanım

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

To expose a DOM node to the parent element, pass in the ref prop to the node.

function MyInput({ ref }) {
  return <input ref={ref} />;
};

With the code above, a ref to MyInput will receive the <input> DOM node. However, you can expose a custom value instead. To customize the exposed handle, call useImperativeHandle at the top level of your component:

import { useImperativeHandle } from 'react';

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

  return <input />;
};

Note that in the code above, the ref is no longer passed to the <input>.

Ö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 { useRef, useImperativeHandle } from 'react';

function MyInput({ ref }) {
  const inputRef = useRef(null);

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

  return <input 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.

ÖncekiuseId
SonrakiuseInsertionEffect