useImperativeHandle: anpassade instansvärden

När ni vidarebefordrar en ref direkt till ett DOM-element får parent den råa DOM-noden och tillgång till alla dess inbyggda metoder och egenskaper. Det är ofta mer åtkomst än ni vill exponera.

Ibland vill ni i stället ge parent ett litet, noggrant utvalt objekt i stället för hela DOM-noden och därmed hålla komponentens publika API avsiktligt begränsat.

useImperativeHandle låter er anpassa värdet som parentens ref pekar på. I stället för DOM-noden får parent det objekt ni returnerar, så ni bestämmer exakt vilka metoder och värden som exponeras.

Detta gör den vidarebefordrade ref:en till ett definierat imperativt gränssnitt i stället för en läckande genomkoppling till det underliggande elementet.

Hooken tar den vidarebefordrade ref:en som sitt första argument och en fabrikfunktion som sitt andra. Fabrikfunktionen returnerar handle-objektet som blir ref.current hos parent.

Ni anropar den som useImperativeHandle(ref, () => ({ ... })), där ni bygger objektet med de metoder och värden som ska vara tillgängliga i fabrikfunktionen.

Ett vanligt mönster är ett anpassat inputfält som endast exponerar focus och clear. I fabrikfunktionen returnerar ni ett objekt med dessa två metoder, där var och en arbetar mot en intern ref till det riktiga inputfältet.

Parent kan nu fokusera eller rensa fältet, men kan inte läsa dess råa value-attribut eller utlösa godtyckligt DOM-beteende, vilket gör användningen förutsägbar.

Imperativa handtag passar bra för dialoger. En Modal-komponent kan exponera metoderna open och close, som ändrar komponentens interna synlighetsstatus, så att parent kan styra den imperativt utan att själv hantera det booleska värdet open.

Detta är praktiskt för kod som behöver utlösa en dialog från många platser, till exempel för att visa en bekräftelse när en asynkron åtgärd har slutförts.

Genom att endast returnera de metoder ni avser att stödja skapar ni ett tydligt kontrakt. Konsumenter är beroende av en liten, dokumenterad uppsättning operationer i stället för det omfattande DOM-API:et, vilket gör framtida refaktoreringar säkrare.

En begränsad imperativ yta är enklare att testa och förstå och löper mycket mindre risk att gå sönder när ni ändrar den interna implementationen.

useImperativeHandle tar ett valfritt tredje argument, en beroendearray. När något beroende ändras körs fabrikfunktionen igen och handle-objektet återskapas, på liknande sätt som med useMemo och useEffect.

Om metoderna ni exponerar sluter över värden som kan ändras ska ni ange dessa värden som beroenden, så att parent alltid får ett handle-objekt som är kopplat till det aktuella tillståndet.

useImperativeHandle är bara meningsfullt inuti en komponent som omslutits med forwardRef, eftersom den behöver den vidarebefordrade ref:en för att koppla det anpassade handtaget till den. På egen hand skulle det inte finnas någon parent-ref att fylla i.

Därför används de tillsammans: forwardRef tar in ref:en och useImperativeHandle definierar vad ref:en slutligen pekar på.

För att testa ett handle renderar ni komponenten med en ref, anropar sedan metoder via ref.current i ett act-block och gör påståenden om det resulterande beteendet eller DOM-förändringarna.

Eftersom den exponerade ytan är liten och tydligt definierad blir dessa tester fokuserade. De verifierar att varje dokumenterad metod gör det kontraktet lovar, i stället för att undersöka interna detaljer.

I TypeScript definierar ni ett interface som beskriver handle-objektet, till exempel ett med metoderna focus och clear, och använder det sedan för att typa både forwardRef-generiken och den ref som parent håller.

Detta ger autokomplettering och kompileringstidskontroller på anropsstället, så att konsumenter ser exakt vilka metoder som finns och felaktig användning upptäcks före runtime.

useImperativeHandle anpassar vad en vidarebefordrad ref exponerar genom att ta emot ref:en och en fabrikfunktion som returnerar ett handle-objekt. Ni använder den för att exponera ett litet API, till exempel focus och clear eller open och close på en modal.

Den används alltid tillsammans med forwardRef, har stöd för en beroendearray som uppdaterar handle-objektet och passar bra ihop med TypeScript-interface och fokuserade tester. En begränsad yta är avsiktlig och utgör god design.