Bygg ett imperativt komponent-API

Börja med att fastställa kontraktet: en FocusableInput kan exponera focus, blur och getValue. Omslut den med forwardRef, behåll en intern ref till det riktiga input-elementet och returnera de tre metoderna från useImperativeHandle.

Varje metod vidarebefordrar anropet till det underliggande input-elementet, så den överordnade komponenten får exakt de operationer den behöver utan att behöva hantera råelementet direkt.

En mediekomponent har stor nytta av ett imperativt API. En VideoPlayer kan exponera play, pause och seekTo, där varje metod vidarebefordrar anropet till de inbyggda metoderna på HTMLVideoElement via en intern videoref.

seekTo tar emot en tid i sekunder och sätter currentTime, vilket ger överordnade komponenter exakt kontroll över uppspelningen – något som skulle vara omständligt att styra enbart via props.

En Carousel kan exponera next, prev och goToSlide så att externa kontroller eller tangentbordshanterare kan styra den. Internt uppdaterar metoderna state för det aktiva indexet, och komponenten renderas om med den nya sliden.

Detta kombinerar imperativa utlösare med deklarativ rendering: den överordnade komponenten begär en övergång, och karusellen renderar resultatet genom sitt vanliga state-flöde.

Ett imperativt handtag är ett offentligt kontrakt, så dokumentera varje metod, dess parametrar och returvärde. Tydlig dokumentation visar API-användarna vad som stöds och motverkar beroenden på odokumenterade interna detaljer.

Behandla handtaget som vilket annat API-gränssnitt som helst: en kort referens med en lista över metoder som play(), pause() och seekTo(seconds) förebygger felaktig användning och förvirring.

När API-användare väl är beroende av ett handtag innebär det ett breaking change att ta bort eller byta namn på en metod. Lägg till nya metoder i stället för att ändra befintliga signaturer, och fasa ut dem på ett ordnat sätt innan något tas bort.

Om handtaget betraktas som ett versionshanterat API minskar risken att efterföljande kod går sönder när komponenten byggs ut över tid.

Många verkliga komponenter blandar båda stilarna. En VideoPlayer kan ta emot en src-prop och en autoPlay-prop deklarativt, samtidigt som den exponerar play och seekTo för situationer som props inte kan uttrycka på ett bra sätt.

Riktlinjen är att använda props för state och konfiguration och reservera det imperativa handtaget för engångsåtgärder som utlöses vid specifika tidpunkter.

För att testa ett imperativt API renderar man komponenten med en ref, omsluter interaktionerna i act och anropar de exponerade metoderna via ref.current. Därefter verifierar man det observerbara resultatet, till exempel att videon är pausad eller att slide-indexet har ändrats.

En ref-callback kan fånga handtaget under rendering, så att testet får en stabil referens att anropa metoder på.

Storybook är en bra plats för att demonstrera imperativa handtag. En story kan hålla en ref till komponenten och rendera knappar som anropar dess metoder, så att granskare interaktivt kan prova play, pause eller goToSlide.

Dessa stories fungerar även som levande dokumentation och visar exakt hur det imperativa API:t beter sig isolerat.

Imperativa handtag är vanliga när man kapslar in bibliotek som inte är React-bibliotek. Diagrambibliotek exponerar metoder som redraw eller update, kart-SDK:er exponerar panTo och setZoom, och redigerare för formaterad text exponerar insertText eller getContents.

Genom att kapsla in ett sådant bibliotek i en React-komponent och exponera ett rent handtag får resten av applikationen ett tydligt och idiomatiskt sätt att styra det.

Metoder på ett handtag sluter ofta över aktuellt state. Använd därför beroendearrayen i useImperativeHandle för att uppdatera dem vid behov, och använd useCallback för interna hjälpfunktioner för att undvika inaktuella closures.

Ett välhanterat handtag arbetar alltid med uppdaterade värden, så en överordnad komponent som anropar getValue eller seekTo får ett beteende som stämmer med den senaste renderingen.

Du designade handtag för en FocusableInput, en VideoPlayer och en Carousel, där varje handtag exponerar ett litet antal åtgärdsmetoder. Dokumentera och versionshantera dessa metoder, eftersom API-användarna är beroende av dem som ett offentligt API.

Kombinera imperativa åtgärder med deklarativa props, testa via ref.current inuti act och visa beteendet i Storybook. Samma mönster kapslar på ett rent sätt in diagram-, kart- och redigeringsbibliotek.