useImperativeHandle: niestandardowe wartości instancji

Gdy ref jest przekazywany bezpośrednio do elementu DOM, rodzic otrzymuje surowy węzeł DOM i uzyskuje dostęp do wszystkich jego natywnych metod i właściwości. Jest to często większy zakres dostępu, niż chcemy udostępniać.

Czasami lepiej przekazać rodzicowi niewielki, starannie dobrany obiekt zamiast całego węzła DOM, celowo ograniczając publiczne API komponentu.

useImperativeHandle pozwala dostosować wartość, na którą wskazuje ref rodzica. Zamiast węzła DOM rodzic otrzymuje dowolny zwrócony obiekt, dzięki czemu można dokładnie określić, które metody i wartości zostaną udostępnione.

W ten sposób przekazany ref staje się zdefiniowanym interfejsem imperatywnym, a nie niekontrolowanym przekazaniem dostępu do bazowego elementu.

Hook przyjmuje przekazany ref jako pierwszy argument oraz funkcję fabrykującą jako drugi. Fabryka zwraca obiekt uchwytu, który staje się wartością ref.current u rodzica.

Wywołuje się go jako useImperativeHandle(ref, () => ({ ... })), budując wewnątrz fabryki obiekt metod i wartości, które mają być dostępne.

Typowym wzorcem jest niestandardowy input udostępniający tylko metody focus i clear. Wewnątrz fabryki zwraca się obiekt z tymi dwiema metodami, z których każda działa na wewnętrznym ref wskazującym rzeczywisty input.

Rodzic może teraz ustawić fokus na polu lub je wyczyścić, ale nie może odczytać jego surowego atrybutu value ani wywoływać dowolnych zachowań DOM, co zapewnia przewidywalne użycie.

Uchwyty imperatywne dobrze sprawdzają się w przypadku okien dialogowych. Komponent Modal może udostępniać metody open i close, które zmieniają jego wewnętrzny stan widoczności, pozwalając rodzicowi sterować nim imperatywnie bez samodzielnego zarządzania wartością logiczną open.

Jest to wygodne w kodzie, który musi wywoływać okno dialogowe z wielu miejsc, na przykład wyświetlać potwierdzenie po zakończeniu asynchronicznej operacji.

Zwracając tylko metody, które mają być obsługiwane, tworzy się jasny kontrakt. Konsumenci zależą od niewielkiego, udokumentowanego zestawu operacji zamiast od rozbudowanego API DOM, dzięki czemu przyszłe refaktoryzacje są bezpieczniejsze.

Wąski zakres imperatywny łatwiej testować i zrozumieć, a także znacznie rzadziej powoduje problemy przy zmianie wewnętrznej implementacji.

useImperativeHandle przyjmuje opcjonalny trzeci argument — tablicę zależności. Gdy zmieni się dowolna zależność, fabryka jest uruchamiana ponownie, a obiekt uchwytu tworzony od nowa, podobnie jak w przypadku useMemo i useEffect.

Jeśli udostępniane metody korzystają z wartości, które mogą się zmieniać, należy umieścić te wartości wśród zależności, aby rodzic zawsze otrzymywał uchwyt powiązany z aktualnym stanem.

useImperativeHandle ma sens tylko wewnątrz komponentu opakowanego za pomocą forwardRef, ponieważ potrzebuje przekazanego ref, do którego przypisze niestandardowy uchwyt. Samodzielnie nie miałby żadnego ref rodzica do uzupełnienia.

Te dwa mechanizmy są więc używane razem: forwardRef przekazuje ref do środka, a useImperativeHandle określa, na co ten ref ostatecznie wskazuje.

Aby przetestować uchwyt, należy wyrenderować komponent z ref, a następnie wywołać metody za pośrednictwem ref.current wewnątrz bloku act i sprawdzić wynikające z tego działanie lub zmiany w DOM.

Ponieważ udostępniany zakres jest niewielki i jasno określony, testy te są skoncentrowane: weryfikują, czy każda udokumentowana metoda działa zgodnie z kontraktem, zamiast zaglądać do szczegółów implementacji.

W TypeScript definiuje się interfejs opisujący uchwyt, na przykład zawierający metody focus i clear, a następnie używa się go do typowania zarówno typu generycznego forwardRef, jak i ref przechowywanego przez rodzica.

Zapewnia to autouzupełnianie i kontrole w czasie kompilacji w miejscu wywołania, dzięki czemu konsumenci widzą dokładnie, jakie metody istnieją, a ich nieprawidłowe użycie zostaje wykryte przed uruchomieniem.

Sprawdź, do czego właściwie służy useImperativeHandle.

useImperativeHandle dostosowuje to, co udostępnia przekazany ref, przyjmując ref oraz fabrykę zwracającą obiekt uchwytu. Używa się go do udostępniania niewielkiego API, takiego jak focus i clear albo open i close w komponencie modal.

Zawsze łączy się go z forwardRef; obsługuje tablicę zależności do odświeżania uchwytu i dobrze współpracuje z interfejsami TypeScript oraz skoncentrowanymi testami. Ograniczony zakres jest zamierzony i stanowi przejaw dobrego projektowania.