useImperativeHandle: Tilpassede instansverdier

Når en ref videresendes direkte til et DOM-element, mottar forelderen den rå DOM-noden og får tilgang til alle innebygde metoder og egenskaper. Det er ofte et større API-omfang enn man ønsker å eksponere.

Noen ganger er det bedre å gi forelderen et lite, nøye utvalgt objekt i stedet for hele DOM-noden, slik at komponentens offentlige API holdes bevisst avgrenset.

useImperativeHandle lar man tilpasse verdien som foreldrens ref peker på. I stedet for DOM-noden mottar forelderen objektet som returneres, slik at man bestemmer nøyaktig hvilke metoder og verdier som eksponeres.

Dermed blir den videresendte ref-en et definert imperativt grensesnitt i stedet for en lekkende videresending til det underliggende elementet.

Hooken tar den videresendte ref-en som første argument og en fabrikkfunksjon som andre argument. Fabrikkfunksjonen returnerer handle-objektet som blir ref.current hos forelderen.

Den kalles som useImperativeHandle(ref, () => ({ ... })), der man bygger objektet med metodene og verdiene som skal gjøres tilgjengelige fra fabrikkfunksjonen.

Et vanlig mønster er et egendefinert input-element som bare eksponerer focus og clear. I fabrikkfunksjonen returneres et objekt med disse to metodene, som begge opererer på en intern ref til det ekte input-elementet.

Forelderen kan nå fokusere eller tømme feltet, men kan ikke lese det rå value-attributtet eller utløse vilkårlig DOM-atferd. Dermed blir bruken forutsigbar.

Imperative handles passer godt for dialoger. En Modal-komponent kan eksponere metodene open og close, som endrer komponentens interne synlighetsstatus, slik at en forelder kan styre den imperativt uten selv å håndtere den boolske verdien open.

Dette er praktisk for kode som må utløse en dialog fra mange steder, for eksempel for å vise en bekreftelse etter at en asynkron handling er fullført.

Ved å returnere bare metodene som skal støttes, oppretter man en tydelig kontrakt. Forbrukere er avhengige av et lite, dokumentert sett med operasjoner i stedet for det omfattende DOM-API-et, noe som gjør fremtidige omstruktureringer tryggere.

Et avgrenset imperativt API er enklere å teste og forstå, og det er langt mindre sannsynlig at det bryter sammen når den interne implementasjonen endres.

useImperativeHandle tar imot et valgfritt tredje argument, et avhengighetsarray. Når en avhengighet endres, kjøres fabrikkfunksjonen på nytt og handle-objektet opprettes på nytt, på samme måte som med useMemo og useEffect.

Hvis metodene som eksponeres, lukker over verdier som kan endres, må disse verdiene oppgis som avhengigheter slik at forelderen alltid mottar et handle-objekt som er knyttet til gjeldende state.

useImperativeHandle gir bare mening inne i en komponent som er omsluttet av forwardRef, fordi den trenger den videresendte ref-en for å koble det egendefinerte handle-objektet til. Uten dette ville det ikke finnes noen ref fra forelderen å fylle ut.

De to brukes derfor sammen: forwardRef tar imot ref-en, og useImperativeHandle definerer hva ref-en til slutt peker på.

For å teste et handle-objekt rendere man komponenten med en ref, kaller metodene gjennom ref.current inne i en act-blokk og kontrollerer den resulterende atferden eller DOM-endringene.

Fordi det eksponerte API-et er lite og tydelig, blir disse testene fokuserte. De bekrefter at hver dokumenterte metode gjør det kontrakten lover, i stedet for å undersøke interne detaljer.

I TypeScript definerer man et interface som beskriver handle-objektet, for eksempel ett med metodene focus og clear, og bruker det til å type både det generiske typeargumentet til forwardRef og ref-en forelderen har.

Dette gir autofullføring og kompileringstidskontroller på kallestedet, slik at forbrukere ser nøyaktig hvilke metoder som finnes, og feil bruk oppdages før kjøring.

useImperativeHandle tilpasser det en videresendt ref eksponerer, ved å ta imot ref-en og en fabrikkfunksjon som returnerer et handle-objekt. Det brukes til å eksponere et lite API som focus og clear, eller open og close på en modal.

Det brukes alltid sammen med forwardRef, støtter et avhengighetsarray for å oppdatere handle-objektet og passer godt sammen med TypeScript-interfacer og fokuserte tester. Et begrenset API-omfang er et bevisst valg og god design.