useImperativeHandle: Nilai Instans Khusus

Ketika Anda meneruskan ref langsung ke elemen DOM, komponen induk menerima node DOM mentah tersebut dan memperoleh akses ke setiap metode serta properti bawaannya. Cakupan akses ini sering kali lebih luas daripada yang ingin Anda tampilkan.

Terkadang Anda lebih baik memberikan objek kecil yang telah dipilih secara khusus kepada komponen induk daripada seluruh node DOM, sehingga API publik komponen tetap sengaja dibuat terbatas.

useImperativeHandle memungkinkan Anda menyesuaikan nilai yang ditunjuk oleh ref komponen induk. Alih-alih node DOM, komponen induk menerima objek apa pun yang Anda kembalikan, sehingga Anda dapat menentukan metode dan nilai mana yang benar-benar diekspos.

Dengan demikian, ref yang diteruskan menjadi antarmuka imperatif yang terdefinisi, bukan sekadar jalur penerusan ke elemen dasar yang membocorkan detail internal.

Hook ini menerima ref yang diteruskan sebagai argumen pertama dan fungsi pabrik sebagai argumen kedua. Fungsi pabrik tersebut mengembalikan objek kendali yang menjadi ref.current pada komponen induk.

Anda memanggilnya sebagai useImperativeHandle(ref, () => ({ ... })), lalu menyusun objek berisi metode dan nilai yang ingin Anda sediakan dari dalam fungsi pabrik.

Pola yang umum adalah input khusus yang hanya mengekspos focus dan clear. Di dalam fungsi pabrik, Anda mengembalikan objek dengan kedua metode tersebut, yang masing-masing bekerja pada ref internal menuju input sebenarnya.

Komponen induk kini dapat memfokuskan atau mengosongkan bidang tersebut, tetapi tidak dapat membaca atribut value mentahnya atau memicu perilaku DOM sembarang, sehingga penggunaannya tetap mudah diprediksi.

Kendali imperatif sangat cocok untuk dialog. Komponen Modal dapat mengekspos metode open dan close yang mengubah status visibilitas internalnya, sehingga komponen induk dapat mengendalikannya secara imperatif tanpa mengelola nilai boolean open sendiri.

Hal ini memudahkan kode yang perlu memicu dialog dari banyak tempat, misalnya menampilkan konfirmasi setelah tindakan asinkron selesai.

Dengan hanya mengembalikan metode yang memang ingin Anda dukung, Anda membuat kontrak yang jelas. Pengguna bergantung pada sekumpulan kecil operasi yang terdokumentasi, bukan pada API DOM yang sangat luas, sehingga refaktor di masa mendatang menjadi lebih aman.

Cakupan imperatif yang terbatas lebih mudah diuji dan dipahami, serta jauh lebih kecil kemungkinannya rusak ketika Anda mengubah implementasi internal.

useImperativeHandle menerima argumen ketiga yang bersifat opsional, yaitu array dependensi. Ketika salah satu dependensi berubah, fungsi pabrik dijalankan kembali dan objek kendali dibuat ulang, serupa dengan cara kerja useMemo dan useEffect.

Jika metode yang Anda ekspos menangkap nilai yang dapat berubah, cantumkan nilai tersebut sebagai dependensi agar komponen induk selalu menerima kendali yang terikat pada status terkini.

useImperativeHandle hanya bermakna di dalam komponen yang dibungkus dengan forwardRef, karena pengait ini memerlukan ref yang diteruskan untuk memasang kendali khusus. Jika berdiri sendiri, tidak ada ref dari komponen induk yang dapat diisi.

Jadi, keduanya digunakan bersama: forwardRef membawa ref masuk, sedangkan useImperativeHandle menentukan apa yang akhirnya ditunjuk oleh ref tersebut.

Untuk menguji kendali, tampilkan komponen dengan sebuah ref, lalu panggil metode melalui ref.current di dalam blok act dan verifikasi perilaku atau perubahan DOM yang dihasilkan.

Karena cakupan yang diekspos kecil dan jelas, pengujian ini terarah: setiap metode yang terdokumentasi diverifikasi agar melakukan hal yang dijanjikan kontraknya, bukan dengan mengutak-atik detail internal.

Dalam TypeScript, Anda mendefinisikan antarmuka yang menjelaskan kendali tersebut, misalnya antarmuka dengan metode focus dan clear, lalu menggunakannya untuk mengetik parameter generik forwardRef dan ref yang disimpan oleh komponen induk.

Dengan begitu, lokasi pemanggilan memperoleh pelengkapan otomatis dan pemeriksaan saat kompilasi, sehingga pengguna dapat melihat metode yang benar-benar tersedia dan penggunaan yang keliru terdeteksi sebelum waktu berjalan.

Pastikan Anda memahami kegunaan sebenarnya dari useImperativeHandle.

useImperativeHandle menyesuaikan hal yang diekspos oleh ref yang diteruskan dengan menerima ref dan fungsi pabrik yang mengembalikan objek kendali. Anda menggunakannya untuk menyediakan API kecil seperti focus dan clear, atau open dan close pada modal.

Hook ini selalu dipasangkan dengan forwardRef, mendukung array dependensi untuk memperbarui kendali, serta cocok digunakan bersama antarmuka TypeScript dan pengujian yang terarah. Cakupan yang terbatas adalah pilihan yang disengaja dan merupakan desain yang baik.