useImperativeHandle

useImperativeHandle adalah sebuah React Hook yang memungkinkan Anda menyesuaikan penanganan yang diekspos sebagai ref.

useImperativeHandle(ref, createHandle, dependencies?)

Referensi
- useImperativeHandle(ref, createHandle, dependencies?)
Penggunaan
- Mengekspos sebuah penanganan ref kustom kepada komponen induk
- Mengekspos methods imperatif Anda sendiri

Referensi

`useImperativeHandle(ref, createHandle, dependencies?)`

Panggil fungsi useImperativeHandle di tingkat teratas komponen Anda untuk menyesuaikan penanganan yang diekspos oleh ref:

import { useImperativeHandle } from 'react';

function MyInput({ ref }) {
  useImperativeHandle(ref, () => {
    return {
      // ... your methods ...
    };
  }, []);
  // ...

Lihat lebih banyak contoh di bawah.

Parameter

ref: ref yang Anda terima sebagai prop ke komponen MyInput.
createHandle: Sebuah fungsi yang tidak mengambil argumen dan mengembalikan penanganan ref yang ingin Anda ekspos. Penanganan ref tersebut dapat memiliki tipe apa pun. Biasanya, Anda akan mengembalikan sebuah objek dengan sekumpulan metode yang ingin Anda ekspos.
dependencies opsional: Daftar semua nilai reaktif yang dirujuk di dalam kode setup. Nilai reaktif termasuk props, state, dan semua variabel dan fungsi yang dideklarasikan langsung di dalam tubuh komponen. Jika linter Anda telah dikonfigurasi untuk React, maka linter tersebut akan memverifikasi bahwa setiap nilai reaktif sudah diatur dengan benar sebagai dependensi. Daftar dependensi ini harus memiliki jumlah item yang konstan dan ditulis secara inline seperti [dep1, dep2, dep3]. React akan membandingkan setiap dependensi dengan nilai lama menggunakan perbandingan Object.is. Jika sebuah render ulang menghasilkan sebuah perubahan terhadap beberapa dependency, atau jika Anda menghilangkan argumen ini, fungsi createHandle Anda akan dijalankan ulang, dan penanganan yang baru dibuat akan ditetapkan kepada ref tersebut.

Catatan

Mulai dari React 19, ref tersedia sebagai prop. Di React 18 dan sebelumnya, perlu untuk mendapatkan ref dari forwardRef.

Kembalian

useImperativeHandle mengembalikan undefined.

Penggunaan

Mengekspos sebuah penanganan ref kustom kepada komponen induk

Untuk mengekspos simpul DOM ke elemen induk, berikan prop ref ke simpul tersebut.

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

Dengan kode di atas, ref ke MyInput akan menerima simpul DOM <input>. Namun, Anda dapat mengekspos nilai kustom sebagai gantinya. Untuk menyesuaikan handle yang diekspos, panggil useImperativeHandle di tingkat atas komponen Anda:

import { useImperativeHandle } from 'react';

function MyInput({ ref }) {
  useImperativeHandle(ref, () => {
    return {
      // ... your methods ...
    };
  }, []);

  return <input />;
};

Perlu dicatat bahwa dalam kode di atas, ref tidak lagi diteruskan kepada <input>.

Sebagai contoh, jika Anda tidak ingin mengekspos keseluruhan simpul DOM dari <input>, namun Anda ingin mengekspos dua methods yang tersedia di dalamnya: focus dan scrollIntoView. Untuk melakukan hal tersebut, pertahankan DOM peramban yang asli ke dalam ref yang terpisah. Kemudian gunakan useImperativeHandle untuk mengekspos sebuah penanganan hanya dengan methods yang ingin Anda panggil melalui komponen induk:

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} />;
};

Sekarang, jika komponen induk mendapatkan sebuah ref yang merujuk pada MyInput, komponen tersebut akan dapat memanggil method focus dan scrollIntoView. Meskipun begitu, komponen induk tersebut tidak akan memiliki akses penuh terhadap simpul DOM <input> yang mendasarinya.

Fork

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

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

  function handleClick() {
    ref.current.focus();
    // This won't work because the DOM node isn't exposed:
    // ref.current.style.opacity = 0.5;
  }

  return (
    <form>
      <MyInput placeholder="Enter your name" ref={ref} />
      <button type="button" onClick={handleClick}>
        Edit
      </button>
    </form>
  );
}

Mengekspos methods imperatif Anda sendiri

Methods yang diekspos melalui penanganan imperatif tidak harus sesuai dengan DOM methods secara persis. Sebagai contoh, komponen Post berikut mengekspos sebuah method scrollAndFocusAddComment melalui penanganan imperatif. Hal ini memungkinkan induk Page menggulir (scroll) daftar komentar dan memfokuskan bidang input ketika Anda mengklik tombol:

Fork

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}>
        Write a comment
      </button>
      <Post ref={postRef} />
    </>
  );
}

Sandungan

Jangan terlalu sering menggunakan refs. Anda hanya boleh menggunakan refs untuk perilaku imperatif yang tidak dapat Anda ungkapkan sebagai props: misalnya, menggulir ke sebuah simpul, memfokuskan sebuah simpul, memicu sebuah animasi, memilih teks, dan sebagainya.

Jika Anda dapat mengekspresikan sesuatu sebagai prop, Anda tidak seharusnya menggunakan ref. Sebagai contoh, alih-alih mengekspos penanganan imperatif seperti { open, close } dari sebuah komponen Modal, lebih baik menggunakan isOpen sebagai prop seperti <Modal isOpen={isOpen} />. Efek dapat membantu Anda mengekspos perilaku imperatif melalui props.

SebelumnyauseId

SelanjutnyauseInsertionEffect