useImperativeHandle: aangepaste instantie-waarden

Wanneer je een ref rechtstreeks naar een DOM-element doorstuurt, ontvangt de ouder dat onbewerkte DOM-knooppunt en krijgt hij toegang tot elke ingebouwde methode en eigenschap ervan. Dat is vaak een groter oppervlak dan je beschikbaar wilt maken.

Soms geef je de ouder liever een klein, zorgvuldig samengesteld object dan het volledige DOM-knooppunt, zodat de openbare API van je component bewust beperkt blijft.

Met useImperativeHandle kun je de waarde aanpassen waarnaar de ref van de ouder verwijst. In plaats van het DOM-knooppunt ontvangt de ouder elk object dat je retourneert, zodat je precies bepaalt welke methoden en waarden beschikbaar worden gemaakt.

Zo verandert de doorgestuurde ref in een gedefinieerde imperatieve interface in plaats van een lekke doorgeefverbinding naar het onderliggende element.

De hook accepteert de doorgestuurde ref als eerste argument en een fabrieksfunctie als tweede. De fabriek retourneert het handvatobject dat in de oudercomponent ref.current wordt.

Je roept de hook aan als useImperativeHandle(ref, () => ({ ... })) en bouwt in de fabriek het object met de methoden en waarden die je vanuit de fabriek beschikbaar wilt maken.

Een veelgebruikt patroon is een aangepast invoerveld dat alleen focus en clear beschikbaar maakt. In de fabriek retourneer je een object met die twee methoden, die elk werken op een interne ref naar het echte invoerveld.

De ouder kan het veld nu focus geven of leegmaken, maar kan het onbewerkte value-attribuut niet uitlezen en ook geen willekeurig DOM-gedrag activeren, waardoor het gebruik voorspelbaar blijft.

Imperatieve handvatten passen goed bij dialoogvensters. Een Modal-component kan open- en close-methoden beschikbaar maken die de interne zichtbaarheidsstatus omschakelen, zodat een ouder de component imperatief kan besturen zonder zelf de open-boolean te beheren.

Dit is handig voor code die vanuit veel plaatsen een dialoogvenster moet openen, bijvoorbeeld om een bevestiging te tonen nadat een asynchrone actie is voltooid.

Door alleen de methoden terug te geven die je wilt ondersteunen, creëer je een duidelijk contract. Gebruikers zijn afhankelijk van een kleine, gedocumenteerde set bewerkingen in plaats van de uitgebreide DOM-API, waardoor toekomstige herstructureringen veiliger worden.

Een beperkt imperatief oppervlak is gemakkelijker te testen en te begrijpen, en zal veel minder snel breken wanneer je de interne implementatie wijzigt.

useImperativeHandle accepteert een optioneel derde argument: een afhankelijkheidsarray. Wanneer een afhankelijkheid verandert, wordt de fabriek opnieuw uitgevoerd en wordt het handvatobject opnieuw gemaakt, vergelijkbaar met de werking van useMemo en useEffect.

Als de methoden die je beschikbaar maakt waarden vastleggen die kunnen veranderen, vermeld je die waarden als afhankelijkheden, zodat de ouder altijd een handvat ontvangt dat aan de actuele toestand is gebonden.

useImperativeHandle is alleen zinvol in een component die met forwardRef is verpakt, omdat de hook de doorgestuurde ref nodig heeft om het aangepaste handvat eraan te koppelen. Op zichzelf zou er geen ref van de ouder zijn om te vullen.

Daarom gebruik je ze samen: forwardRef brengt de ref binnen en useImperativeHandle bepaalt waarnaar die ref uiteindelijk verwijst.

Om een handvat te testen, render je de component met een ref. Vervolgens roep je methoden aan via ref.current binnen een act-blok en controleer je het resulterende gedrag of de DOM-wijzigingen.

Omdat het beschikbare oppervlak klein en expliciet is, zijn deze tests gericht: ze controleren of elke gedocumenteerde methode doet wat het contract belooft, in plaats van interne details te onderzoeken.

In TypeScript definieer je een interface die het handvat beschrijft, bijvoorbeeld een interface met focus- en clear-methoden. Vervolgens gebruik je die interface om zowel het generieke typeargument van forwardRef als de ref die de ouder bijhoudt te typeren.

Dit biedt automatisch aanvullen en controles tijdens het compileren op de aanroepplaats, zodat gebruikers precies zien welke methoden bestaan en verkeerd gebruik al vóór runtime wordt ontdekt.

useImperativeHandle bepaalt wat een doorgestuurde ref beschikbaar maakt. De hook ontvangt de ref plus een fabriek die een handvatobject retourneert. Je gebruikt hem om een kleine API beschikbaar te maken, zoals focus en clear, of open en close op een dialoogvenster.

De hook wordt altijd gecombineerd met forwardRef, ondersteunt een afhankelijkheidsarray om het handvat te vernieuwen en werkt goed samen met TypeScript-interfaces en gerichte tests. Een beperkt oppervlak is een bewuste keuze en goed ontwerp.