Ditulis oleh Kristofer Selbekk , bekerja sama dengan Caroline Odden . Berdasarkan ceramah dengan nama yang sama dan orang yang sama pada pertemuan ReactJS di Oslo pada Juni 2019.
Dari penerjemah - nama asli dari 10 Komponen Perintah tidak menyebutkan Bereaksi, tetapi sebagian besar contoh dan rekomendasi berkaitan khusus dengan reaksi, di samping itu, artikel tersebut diletakkan di bawah tag reaksi dan pengembang menulis reaksi .
Tidak mudah membuat komponen yang akan digunakan banyak pengembang. Anda harus mempertimbangkan dengan hati-hati props mana yang akan digunakan jika props ini merupakan bagian dari API publik.
Dalam artikel ini, kami akan membuat pengantar singkat untuk beberapa praktik terbaik untuk mengembangkan API secara keseluruhan, serta membentuk sepuluh perintah yang dapat Anda gunakan untuk membuat komponen yang akan digunakan oleh rekan pengembang Anda.
Apa itu API?
API - atau antarmuka pemrograman aplikasi - adalah tempat dua potong kode bertemu. Ini adalah permukaan kontak antara kode Anda dan seluruh dunia. Kami menyebut permukaan ini sebagai antarmuka. Ini adalah serangkaian tindakan atau poin data tertentu yang dengannya Anda dapat berinteraksi.
Antarmuka antara kelas dan kode yang memanggil kelas ini juga merupakan API. Anda dapat memanggil metode kelas untuk menerima data atau menjalankan fungsi yang terlampir di dalamnya.
Mengikuti prinsip yang sama, properti yang diterima komponen Anda, ini adalah API-nya . Ini adalah cara pengembang berinteraksi dengan komponen Anda.
Beberapa Praktik Desain API Terbaik
Jadi, aturan dan pertimbangan apa yang berlaku saat mengembangkan API? Ya, kami melakukan sedikit riset, dan ternyata ada banyak sumber yang bagus tentang hal ini. Kami memilih dua - Josh Tauberer - "Apa yang membuat API bagus?" dan sebuah artikel oleh Ron Kurir dengan judul yang sama - dan sampai pada empat praktik ini.
Versi stabil
Salah satu hal paling penting untuk dipertimbangkan saat membuat API adalah menjaganya tetap stabil. Jumlah perubahan kritis harus minimal. Jika Anda harus membuat perubahan penting, pastikan untuk menulis panduan pembaruan terperinci dan, jika mungkin, tulis kode mod yang mengotomatiskan proses ini untuk pengembang.
Pesan Kesalahan Deskriptif
Setiap kali terjadi kesalahan saat memanggil API Anda, Anda harus melakukan segala yang mungkin untuk menjelaskan apa yang salah dan bagaimana cara memperbaikinya. Jika Anda memarahi pengguna dengan pesan seperti "penyalahgunaan" dan tidak memberikan penjelasan apa pun, API Anda akan meninggalkan kesan buruk.
Alih-alih, tulis kesalahan deskriptif yang membantu pengguna memperbaiki cara mereka menggunakan API Anda.
Minimalkan kejutan untuk pengembang
Pengembang adalah makhluk yang rapuh, dan Anda tidak perlu menakut-nakuti mereka ketika mereka menggunakan API Anda. Dengan kata lain, buat API Anda seintuitif mungkin. Anda akan mencapai ini jika Anda mengikuti praktik terbaik dan konvensi penamaan yang ada.
Selain itu, kode Anda harus selalu konsisten. Jika Anda menggunakan nama logis properti dengan is atau has di satu tempat, tetapi lewati lebih jauh, ini akan membingungkan orang.
Minimalkan permukaan API
API Anda juga perlu diminimalkan. Banyak fitur yang bagus, tetapi semakin kecil permukaan API Anda (permukaan API), semakin sedikit pengembang yang harus mempelajarinya untuk mulai bekerja secara produktif dengannya. Berkat ini, API Anda akan dianggap mudah digunakan!
Selalu ada cara untuk mengontrol ukuran API Anda. Salah satunya adalah refactoring API baru dari yang lama.
Sepuluh Perintah untuk Komponen Web
Jadi, keempat aturan emas ini bekerja dengan baik untuk REST API dan untuk kepingan prosedur lama tentang Pascal - tetapi bagaimana cara mentransfernya ke dunia React modern?
Seperti yang kami katakan sebelumnya, komponen memiliki API mereka sendiri. Kami menyebutnya props , dan dengan bantuan mereka data ditransfer ke komponen. Bagaimana kita menyusun alat peraga agar tidak melanggar aturan di atas?
Kami telah membuat daftar sepuluh aturan emas ini yang paling baik diikuti saat membuat komponen Anda. Kami berharap semoga bermanfaat bagi Anda.
1. Dokumentasikan penggunaan komponen
Jika cara Anda ingin menggunakan komponen Anda tidak didokumentasikan, maka komponen ini tidak berguna. Yah, hampir tidak berguna, Anda selalu dapat melihat implementasinya, tetapi sedikit orang yang suka melakukan ini.
Ada banyak cara untuk mendokumentasikan komponen Anda, tetapi kami sarankan Anda memperhatikan ketiga hal ini:
Dua yang pertama memberi Anda tempat untuk bekerja ketika mengembangkan komponen Anda, dan yang ketiga memungkinkan Anda untuk menulis dokumentasi dalam bentuk bebas menggunakan MDX
Apa pun yang Anda pilih, selalu dokumentasikan baik API itu sendiri dan bagaimana dan kapan komponen Anda harus digunakan . Bagian terakhir sangat penting dalam perpustakaan tujuan umum - bagi orang untuk menggunakan tombol atau tata letak grid dengan benar dalam konteks yang diberikan.
2. Aktifkan semantik kontekstual
HTML adalah bahasa untuk menyusun informasi dengan cara semantik. Hanya di sini, sebagian besar komponen kami terdiri dari <div /> . Ini masuk akal - komponen universal tidak dapat mengetahui sebelumnya apa yang akan terjadi, mungkin <article /> , atau <section /> , atau <aside /> - tetapi situasi ini jauh dari ideal.
Ada opsi lain, biarkan komponen Anda menerima prop as , dan dengan demikian menentukan elemen DOM yang akan diberikan. Berikut adalah contoh cara mengimplementasikan ini:
function Grid({ as: Element, ...props }) { return <Element className="grid" {...props} /> } Grid.defaultProps = { as: 'div', };
Kami mengganti nama prop untuk variabel Element dan menggunakannya di JSX kami. Kami memberikan nilai div standar umum jika kami tidak memiliki tag HTML yang lebih semantik untuk lulus.
Ketika saatnya tiba untuk menggunakan komponen <Grid /> , Anda dapat dengan mudah memberikan tag yang benar:
function App() { return ( <Grid as="main"> <MoreContent /> </Grid> ); }
Ini juga berfungsi dengan komponen Bereaksi. Misalnya, jika Anda ingin komponen <Button /> me-render React Router <Link /> :
<Button as={Link} to="/profile"> Go to Profile </Button>
3. Hindari alat peraga boolean
Alat peraga logis, seperti, ide yang bagus. Mereka dapat digunakan tanpa nilai, sehingga terlihat sangat elegan:
<Button large>BUY NOW!</Button>
Tetapi meskipun terlihat bagus, properti logis hanya memungkinkan dua kemungkinan. Hidup atau mati Terlihat atau disembunyikan. 1 atau 0.
Setiap kali Anda mulai memperkenalkan properti logis untuk hal-hal seperti ukuran, opsi, warna, atau apa pun yang bisa menjadi apa pun selain pilihan biner, Anda memiliki masalah.
<Button large small primary disabled secondary> ?? </Button>
Dengan kata lain, properti logis sering tidak berskala dengan perubahan persyaratan. Alih-alih, untuk nilai yang mungkin menjadi sesuatu selain pemilihan biner, lebih baik menggunakan nilai yang disebutkan, seperti string.
<Button variant="primary" size="large"> </Button>
Ini tidak berarti bahwa properti logis tidak dapat digunakan sama sekali. Kamu bisa! Prop yang disabled , yang saya sebutkan di atas, masih harus logis - karena tidak ada keadaan tengah antara hidup dan mati. Biarkan saja properti boolean hanya untuk pilihan yang benar-benar biner.
4. Gunakan props.children
Bereaksi memiliki beberapa sifat khusus yang diperlakukan berbeda dari yang lain. Salah satu key ini diperlukan untuk melacak urutan item daftar. Dan alat peraga khusus lainnya adalah children - children .
Segala sesuatu yang Anda tempatkan di antara tag pembuka dan penutup komponen ditempatkan di dalam props.children . props.children . Dan Anda harus menggunakan ini sesering mungkin.
Mengapa Karena itu jauh lebih mudah daripada memiliki content prop untuk konten atau sesuatu seperti itu yang biasanya hanya mengambil nilai-nilai sederhana, seperti teks.
<TableCell content="Some text" /> // <TableCell>Some text</TableCell>
Ada beberapa keuntungan menggunakan props.children . Pertama, ini mirip dengan cara kerja HTML biasa. Kedua, Anda dapat dengan bebas mentransfer apa pun yang Anda inginkan! Alih-alih menambahkan alat peraga seperti leftIcon dan rightIcon ke komponen Anda - hanya meneruskannya sebagai bagian dari props.children :
<TableCell> <ImportantIcon /> Some text </TableCell>
Anda mungkin berpendapat bahwa komponen Anda hanya perlu membuat teks biasa, dan dalam beberapa kasus itu. Sampai titik tertentu. Dengan menggunakan props.children , Anda menjamin bahwa API Anda akan siap untuk mengubah persyaratan.
5. Biarkan orang tua berpegang teguh pada logika internal
Terkadang kita membuat komponen dengan banyak logika dan status internal - misalnya, diagram autocomplete atau interaktif.
Komponen seperti itu sering mengalami API yang berlebihan, salah satu alasannya adalah banyaknya kasus penggunaan yang berbeda yang terakumulasi dengan perkembangan proyek.
Tetapi bagaimana jika kita bisa menyediakan satu saja, prop standar yang memungkinkan pengembang untuk mengontrol, merespons, atau hanya mengubah perilaku default komponen?
Kent Dodds menulis artikel yang bagus tentang konsep reduksi negara. Berikut ini adalah artikel tentang konsep itu sendiri , dan juga, di sini adalah artikel tentang cara menerapkan ini untuk React hooks .
Singkatnya, ini adalah pola transfer fungsi peredam keadaan ke komponen Anda, yang akan memungkinkan pengembang untuk mengakses semua tindakan yang dilakukan di dalam komponen Anda. Anda dapat mengubah status atau bahkan menyebabkan efek samping. Ini adalah cara terbaik untuk memberikan tingkat penyesuaian yang tinggi, tanpa alat peraga .
Begini tampilannya:
function MyCustomDropdown(props) { const stateReducer = (state, action) => { if (action.type === Dropdown.actions.CLOSE) { buttonRef.current.focus(); } }; return ( <> <Dropdown stateReducer={stateReducer} {...props} /> <Button ref={buttonRef}>Open</Button> </> }
Omong-omong, Anda dapat membuat cara yang lebih sederhana untuk merespons acara. Menggunakan onClose pada contoh sebelumnya cenderung membuat penggunaan komponen lebih nyaman. Gunakan pola "peredam keadaan" saat dibutuhkan.
6. Gunakan operator spread untuk alat peraga yang tersisa
Setiap kali Anda membuat komponen baru, pastikan Anda menerapkan elipsis ke alat peraga yang tersisa dan mengirimkannya ke elemen yang masuk akal.
Anda tidak perlu terus menambahkan alat peraga ke komponen Anda, yang hanya akan diteruskan ke komponen atau elemen dasar. Ini akan membuat API Anda lebih stabil dengan menghilangkan kebutuhan akan banyak kesalahan versi kecil ketika pengembang berikutnya membutuhkan pendengar acara baru atau tag ARIA.
Anda bisa melakukannya seperti ini:
function ToolTip({ isVisible, ...rest }) { return isVisible ? <span role="tooltip" {...rest} /> : null; }
Setiap kali komponen Anda melewati prop untuk implementasi Anda, seperti nama kelas atau penangan onClick , pastikan bahwa pengembang lain dapat melakukan hal yang sama. Dalam kasus kelas, Anda bisa menambahkan kelas prop menggunakan pustaka classnames npm yang nyaman (atau hanya rangkaian string):
import classNames from 'classnames'; function ToolTip(props) { return ( <span {...props} className={classNames('tooltip', props.tooltip)} /> }
Dalam hal penangan klik dan panggilan balik lainnya, Anda dapat menggabungkannya menjadi satu fungsi menggunakan utilitas kecil. Inilah salah satu cara untuk melakukan ini:
function combine(...functions) { return (...args) => functions .filter(func => typeof func === 'function') .forEach(func => func(...args)); }
Di sini kita membuat fungsi yang menerima daftar fungsi untuk menggabungkannya. Ini mengembalikan panggilan balik baru, yang memanggil mereka semua pada gilirannya dengan argumen yang sama.
Fungsi ini dapat digunakan dengan cara ini:
function ToolTip(props) { const [isVisible, setVisible] = React.useState(false); return ( <span {...props} className={classNames('tooltip', props.className)} onMouseIn={combine(() => setVisible(true), props.onMouseIn)} onMouseOut={combine(() => setVisible(false), props.onMouseOut)} /> ); }
7. Gunakan nilai default
Pastikan Anda memberikan cukup standar (default) untuk alat peraga Anda. Dengan demikian, Anda akan mengurangi jumlah alat peraga wajib. Ini akan sangat menyederhanakan API Anda.
Ambil, misalnya, penangan onClick . Jika kode Anda tidak memerlukan penangan ini, gunakan fungsi kosong (fungsi-noop) sebagai penyangga standar. Dengan cara ini Anda bisa menyebutnya dalam kode Anda seolah-olah itu selalu berlalu.
Contoh lain mungkin untuk input pengguna. Asumsikan string input adalah string kosong kecuali ditentukan lain. Ini akan memungkinkan Anda untuk memastikan bahwa Anda selalu berurusan dengan objek string, bukan sesuatu yang tidak terdefinisi atau nol.
8. Tidak perlu mengganti nama atribut HTML
HTML sebagai bahasa memiliki alat peraga sendiri - atau atribut, dan itu sendiri adalah API untuk elemen HTML. Jadi mengapa tidak terus menggunakan API ini?
Seperti yang kami sebutkan sebelumnya, meminimalkan permukaan API dan intuitifnya adalah metode yang berguna untuk meningkatkan API komponen Anda. Jadi alih-alih membuat prop screenReaderLabel Anda sendiri, mengapa tidak menggunakan aria-label ada saja?
Tinggal jauh dari mengganti nama atribut HTML yang ada untuk "kemudahan penggunaan" Anda sendiri. Anda bahkan tidak mengganti API yang ada - Anda cukup menambahkan sendiri di atasnya. Orang-orang masih dapat melewati aria-label bersama dengan screenReaderLabel screenReaderLabel Anda - dan apa yang seharusnya menjadi nilai akhir?
Juga, pastikan Anda tidak pernah menimpa atribut HTML di komponen Anda. Contoh yang bagus adalah atribut type dari elemen <button /> . Itu bisa submit (default), button atau reset . Namun, banyak pengembang mendefinisikan kembali prop ini untuk menunjukkan tipe visual dari tombol ( primary , cta , dll.).
Jika Anda akan menggunakan prop semacam itu, Anda perlu menambahkan override untuk atribut type sebenarnya. Ini akan menyebabkan kebingungan, keraguan, dan gangguan dari pihak pengembang.
Percayalah - saya membuat kesalahan ini lagi dan lagi - jika Anda membuatnya, maka Anda harus menguraikannya untuk waktu yang lama.
9. Tuliskan jenis alat peraga (atau hanya tipe)
Tidak ada dokumentasi yang sebagus dokumentasi yang ada di dalam kode Anda. Bereaksi datang dengan cara yang bagus untuk mendeklarasikan API Anda menggunakan paket prop-types . Gunakan itu.
Anda dapat menentukan persyaratan format untuk alat peraga wajib dan opsional Anda, dan Anda dapat memperbaikinya dengan komentar JSDoc .
Jika Anda tidak menentukan alat peraga wajib atau memberikan nilai yang tidak valid atau tidak terduga, pada saat dijalankan Anda akan menerima peringatan di konsol. Ini banyak membantu selama pengembangan, dan dapat dihapus dari produksi.
Jika Anda menulis aplikasi Bereaksi Anda dalam TypeScript atau menggunakan Flow, Anda mendapatkan dokumentasi API sebagai fungsi bahasa. Ini semakin meningkatkan dukungan alat pengembangan dan menyederhanakan pekerjaan.
Jika Anda sendiri tidak menggunakan JavaScript yang diketik, Anda harus tetap mempertimbangkan untuk memberikan definisi tipe kepada pengembang yang menggunakannya. Maka akan lebih mudah bagi mereka untuk menggunakan komponen Anda.
10. Desain untuk pengembang
Akhirnya, aturan yang paling penting untuk diikuti. Pastikan API Anda dan bekerja dengan komponen Anda dioptimalkan untuk pengembang yang akan menggunakannya.
Salah satu cara untuk menyederhanakan pekerjaan pengembang adalah memberinya umpan balik tentang penggunaan yang tidak pantas. Lakukan ini dengan pesan kesalahan, dan juga, tetapi hanya selama pengembangan, dengan peringatan bahwa ada cara yang lebih efisien untuk menggunakan komponen Anda.
Saat menulis kesalahan dan peringatan, berikan tautan ke dokumentasi Anda atau tampilkan contoh kode sederhana. Semakin cepat pengembang memahami apa masalahnya dan bagaimana cara memperbaikinya, komponen Anda akan merasa lebih nyaman untuk bekerja.
Luar biasa, tetapi ternyata, keberadaan semua peringatan kesalahan panjang ini tidak mempengaruhi ukuran paket akhir. Berkat keajaiban menghilangkan kode mati, semua teks dan kode kesalahan ini dapat dihapus selama perakitan dalam produksi.
Salah satu perpustakaan yang memberikan umpan balik yang sangat baik adalah Bereaksi sendiri. Tidak masalah jika Anda lupa menentukan kunci untuk item daftar, atau Anda menulis metode siklus hidup secara tidak benar, atau mungkin Anda lupa memperpanjang kelas dasar atau menyebut hook dengan cara yang tidak pasti - dalam hal apa pun, Anda akan mendapatkan pesan kesalahan besar yang tebal di konsol. Mengapa pengembang yang menggunakan komponen Anda mengharapkan lebih sedikit dari Anda?
Jadi desain untuk pengguna masa depan Anda. Desain untuk diri sendiri dari masa depan. Desain untuk yang kurang beruntung yang harus menjaga kode Anda ketika Anda pergi! Desain untuk pengembang.
Total
Kita bisa belajar banyak dari pendekatan API klasik. Dengan mengikuti tip, trik, aturan, dan perintah dari artikel ini, Anda dapat membuat komponen yang mudah digunakan, mudah dirawat, intuitif, dan, jika perlu, sangat fleksibel.