Imperatiivisen komponentti-API:n rakentaminen

Aloittakaa määrittelemällä sopimus: FocusableInput voi tarjota metodit focus, blur ja getValue. Käyttäkää forwardRef-funktiota, säilyttäkää sisäinen ref varsinaiseen input-elementtiin ja palauttakaa nämä kolme metodia useImperativeHandle-kutsulla.

Kukin metodi delegoi toiminnon taustalla olevalle inputille, joten vanhempi komponentti saa täsmälleen tarvitsemansa operaatiot koskematta suoraan paljaaseen elementtiin.

Mediakomponentti hyötyy suuresti imperatiivisesta API:sta. VideoPlayer voi tarjota metodit play, pause ja seekTo, joista kukin delegoi toiminnon sisäisen video-refin natiivin HTMLVideoElementin metodeille.

seekTo ottaa vastaan ajan sekunteina ja asettaa arvon currentTime, joten vanhemmat komponentit voivat hallita toistoa tarkasti tavalla, jota olisi hankala toteuttaa pelkillä propseilla.

Carousel voi tarjota metodit next, prev ja goToSlide, jotta ulkoiset ohjaimet tai näppäimistön tapahtumankäsittelijät voivat ohjata sitä. Sisäisesti nämä metodit päivittävät aktiivisen dian indeksin tilaa, minkä jälkeen komponentti renderöityy uudelleen uuden dian mukaiseksi.

Tässä yhdistyvät imperatiiviset käynnistimet ja deklaratiivinen renderöinti: vanhempi komponentti käskee siirtymään, ja carousel renderöi tuloksen normaalin tilavirtansa kautta.

Imperatiivinen handle on julkinen sopimus, joten dokumentoikaa jokainen metodi, sen parametrit ja palautusarvo. Selkeä dokumentaatio kertoo käyttäjille, mitä tuetaan, ja ehkäisee riippuvuutta dokumentoimattomista sisäisistä toteutuksista.

Kohdelkaa handlea kuten mitä tahansa muuta API-pintaa: lyhyt viite, jossa luetellaan play(), pause() ja seekTo(seconds) -metodien kaltaiset metodit, ehkäisee väärinkäyttöä ja sekaannusta.

Kun käyttäjät ovat riippuvaisia handlesta, metodin poistaminen tai nimeäminen uudelleen on rikkova muutos. Lisätkää uusia metodeja sen sijaan, että muuttaisitte olemassa olevia allekirjoituksia, ja merkitkää vanhat metodit hallitusti vanhentuneiksi ennen niiden poistamista.

Kun ajattelette handlea versioituna API:na, muualla sovelluksessa oleva koodi ei rikkoudu komponentin laajentuessa ajan mittaan.

Monissa todellisissa komponenteissa yhdistetään molemmat tyylit. VideoPlayer voi vastaanottaa src- ja autoPlay-propit deklaratiivisesti ja tarjota samalla imperatiiviset play- ja seekTo-metodit tilanteisiin, joita propsit eivät ilmaise hyvin.

Nyrkkisääntönä on käyttää propseja tilan ja asetusten välittämiseen sekä varata imperatiivinen handle yksittäisiin toimintoihin, jotka käynnistetään tiettynä ajankohtana.

Testataksenne imperatiivista API:a renderöikää komponentti refin kanssa, käärikää vuorovaikutukset act-kutsuun ja kutsukaa paljastettuja metodeja ref.current-arvon kautta. Varmistakaa sitten havaittava lopputulos, kuten videon pysähtyminen tai dian indeksin muuttuminen.

Ref-takaisinkutsu voi tallentaa handlen renderöinnin aikana, jolloin testillä on vakaa viite, jonka kautta metodeja voi kutsua.

Storybook sopii hyvin imperatiivisten handlejen esittelyyn. Tarina voi säilyttää refiä komponenttiin ja renderöidä painikkeita, jotka kutsuvat sen metodeja, jolloin tarkastajat voivat kokeilla play-, pause- tai goToSlide-toimintoja vuorovaikutteisesti.

Nämä tarinat toimivat samalla elävänä dokumentaationa ja näyttävät tarkasti, miten imperatiivinen API toimii erillään muusta sovelluksesta.

Imperatiiviset handlet ovat yleisiä käärittäessä muita kuin React-kirjastoja. Kaaviokirjastot tarjoavat redraw- tai update-metodeja, kartta-SDK:t tarjoavat panTo- ja setZoom-metodeja, ja rich text -editorit tarjoavat insertText- tai getContents-metodeja.

Kun tällainen kirjasto kääritään React-komponentiksi ja sen käyttöön tarjotaan selkeä handle, muu sovellus saa siistin ja idiomaattisen tavan ohjata sitä.

Handlen metodit sulkevat usein sisäänsä nykyisen tilan, joten päivittäkää niitä tarvittaessa useImperativeHandle-funktion riippuvuuslistan avulla ja käyttäkää sisäisissä apufunktioissa useCallbackia vanhentuneiden sulkeumien välttämiseksi.

Hyvin hallittu handle toimii aina ajan tasalla olevilla arvoilla, joten vanhemman komponentin getValue- tai seekTo-kutsu toimii viimeisimmän renderöinnin mukaisesti.

Suunnittelitte handlet FocusableInputille, VideoPlayerille ja Carouselille siten, että kukin tarjosi pienen joukon toimintametodeja. Dokumentoikaa ja versioikaa nämä metodit, koska käyttäjät ovat riippuvaisia niistä julkisena API:na.

Yhdistäkää imperatiiviset toiminnot deklaratiivisiin propseihin, testatkaa ref.currentin kautta act-kutsun sisällä ja esitelkää toiminta Storybookissa. Sama malli käärii kaavio-, kartta- ja editorikirjastot siististi.