Membangun API Komponen Imperatif

Mulailah dengan menentukan kontraknya: FocusableInput dapat menyediakan fokus, penghilangan fokus, dan getValue. Bungkus dengan forwardRef, pertahankan referensi internal ke masukan yang sebenarnya, lalu kembalikan ketiga metode tersebut dari useImperativeHandle.

Setiap metode mendelegasikan tugasnya kepada masukan yang mendasarinya, sehingga komponen induk memperoleh operasi yang benar-benar dibutuhkannya tanpa menyentuh elemen mentah.

Komponen media sangat diuntungkan oleh API imperatif. VideoPlayer dapat menyediakan putar, jeda, dan seekTo, yang masing-masing mendelegasikan tugasnya kepada metode bawaan elemen video HTML pada referensi video internal.

seekTo menerima waktu dalam satuan detik dan menetapkan currentTime, sehingga komponen induk dapat mengendalikan pemutaran secara presisi, sesuatu yang sulit dilakukan hanya melalui properti.

Karusel dapat menyediakan berikutnya, sebelumnya, dan goToSlide agar kontrol eksternal atau penangan keyboard dapat menggerakkannya. Di dalamnya, metode-metode ini memperbarui status indeks aktif, lalu komponen merender ulang ke slide baru.

Pendekatan ini memadukan pemicu imperatif dengan perenderan deklaratif: komponen induk memerintahkan transisi, lalu karusel merender hasilnya melalui alur status normal.

Pegangan imperatif merupakan kontrak publik, jadi dokumentasikan setiap metode, parameternya, dan nilai kembaliannya. Dokumentasi yang jelas memberi tahu pengguna apa saja yang didukung dan mencegah mereka bergantung pada bagian internal yang tidak didokumentasikan.

Perlakukan pegangan seperti permukaan API lainnya: referensi singkat yang mencantumkan metode seperti putar(), jeda(), dan seekTo(detik) dapat mencegah penyalahgunaan dan kebingungan.

Setelah pengguna bergantung pada suatu pegangan, menghapus atau mengganti nama metode menjadi perubahan yang memutus kompatibilitas. Tambahkan metode baru alih-alih mengubah tanda tangan yang sudah ada, dan tandai metode lama sebagai usang secara bertahap sebelum menghapusnya.

Menganggap pegangan sebagai API berversi membantu mencegah kode hilir rusak saat Anda mengembangkan komponen dari waktu ke waktu.

Banyak komponen nyata memadukan kedua gaya tersebut. VideoPlayer mungkin menerima properti sumber dan properti putar otomatis secara deklaratif, sekaligus menyediakan tindakan imperatif untuk memutar dan seekTo pada situasi yang sulit dinyatakan dengan properti.

Panduannya adalah menggunakan properti untuk status dan konfigurasi, lalu menyimpan pegangan imperatif untuk tindakan satu kali yang dipicu pada waktu tertentu.

Untuk menguji API imperatif, render komponen dengan referensi, bungkus interaksi dalam tindakan, lalu panggil metode yang tersedia melalui ref.current. Setelah itu, periksa hasil yang dapat diamati, seperti video yang sedang dijeda atau indeks slide yang berubah.

Panggilan balik referensi dapat menangkap pegangan selama perenderan, sehingga pengujian Anda memiliki referensi stabil untuk memanggil metode.

Storybook merupakan tempat yang baik untuk mendemonstrasikan pegangan imperatif. Sebuah cerita dapat menyimpan referensi ke komponen dan merender tombol yang memanggil metodenya, sehingga peninjau dapat mencoba memutar, menjeda, atau berpindah ke slide tertentu secara interaktif.

Cerita-cerita ini juga berfungsi sebagai dokumentasi hidup yang menunjukkan dengan tepat perilaku API imperatif secara terpisah.

Pegangan imperatif umum digunakan saat membungkus pustaka non-React. Pustaka bagan menyediakan metode untuk menggambar ulang atau memperbarui, SDK peta menyediakan panTo dan setZoom, sedangkan penyunting teks kaya menyediakan insertText atau getContents.

Membungkus pustaka semacam itu dalam komponen React dan menyediakan pegangan yang rapi memberi bagian lain dari aplikasi Anda cara yang teratur dan sesuai dengan pola React untuk mengendalikannya.

Metode pada pegangan sering menangkap status saat ini, jadi gunakan larik dependensi useImperativeHandle untuk menyegarkannya saat diperlukan, dan gunakan useCallback untuk pembantu internal agar tidak terjadi penutupan yang sudah kedaluwarsa.

Pegangan yang dikelola dengan baik selalu beroperasi menggunakan nilai terbaru, sehingga komponen induk yang memanggil getValue atau seekTo memperoleh perilaku yang sesuai dengan perenderan terakhir.

Terapkan pedoman desain untuk API komponen imperatif.

Anda merancang pegangan untuk FocusableInput, VideoPlayer, dan Karusel, yang masing-masing menyediakan sejumlah kecil metode tindakan. Dokumentasikan dan versikan metode-metode tersebut karena pengguna bergantung padanya sebagai API publik.

Padukan tindakan imperatif dengan properti deklaratif, lakukan pengujian melalui ref.current di dalam tindakan, dan tampilkan perilakunya dalam Storybook. Pola yang sama dapat membungkus pustaka bagan, peta, dan penyunting dengan rapi.