Budowanie imperatywnego API komponentu

Najpierw należy określić kontrakt: FocusableInput może udostępniać metody focus, blur i getValue. Komponent należy opakować w forwardRef, przechowywać wewnętrzny ref do rzeczywistego pola input i zwracać te trzy metody z useImperativeHandle.

Każda metoda deleguje działanie do bazowego pola input, dzięki czemu komponent nadrzędny otrzymuje dokładnie potrzebne operacje bez bezpośredniego dotykania surowego elementu.

Komponent multimedialny może bardzo skorzystać z imperatywnego API. VideoPlayer może udostępniać metody play, pause i seekTo, z których każda deleguje działanie do natywnych metod HTMLVideoElement za pośrednictwem wewnętrznego ref do elementu video.

seekTo przyjmuje czas w sekundach i ustawia currentTime, zapewniając komponentom nadrzędnym precyzyjną kontrolę nad odtwarzaniem, którą trudno byłoby uzyskać wyłącznie za pomocą propsów.

Carousel może udostępniać metody next, prev i goToSlide, aby zewnętrzne elementy sterujące lub procedury obsługi klawiatury mogły nim sterować. Wewnątrz te metody aktualizują stan aktywnego indeksu, a komponent renderuje się ponownie z nowym slajdem.

Łączy to imperatywne wyzwalanie z deklaratywnym renderowaniem: komponent nadrzędny nakazuje przejście, a karuzela renderuje wynik za pośrednictwem swojego zwykłego przepływu stanu.

Uchwyt imperatywny jest publicznym kontraktem, dlatego należy udokumentować każdą metodę, jej parametry i wartość zwracaną. Jasna dokumentacja informuje konsumentów, co jest obsługiwane, i zniechęca do polegania na nieudokumentowanych elementach wewnętrznych.

Uchwyt należy traktować jak każdą inną powierzchnię API: krótki opis metod takich jak play(), pause() i seekTo(seconds) zapobiega niewłaściwemu użyciu i nieporozumieniom.

Gdy konsumenci zaczną polegać na uchwycie, usunięcie lub zmiana nazwy metody będzie zmianą łamiącą kompatybilność. Należy dodawać nowe metody zamiast zmieniać istniejące sygnatury i stopniowo wycofywać stare metody, zanim zostaną usunięte.

Traktowanie uchwytu jako wersjonowanego API chroni kod zależny przed awariami w miarę rozbudowywania komponentu.

Wiele rzeczywistych komponentów łączy oba style. VideoPlayer może deklaratywnie przyjmować propsy src i autoPlay, a jednocześnie udostępniać imperatywne metody play i seekTo na potrzeby sytuacji, których propsy nie opisują dobrze.

Zasada jest następująca: propsów należy używać do określania stanu i konfiguracji, a uchwyt imperatywny rezerwować dla jednorazowych działań wyzwalanych w określonych momentach.

Aby przetestować imperatywne API, należy wyrenderować komponent z ref, opakować interakcje w act i wywoływać udostępnione metody za pośrednictwem ref.current. Następnie należy sprawdzić obserwowalny rezultat, na przykład to, czy wideo jest wstrzymane albo czy indeks slajdu się zmienił.

Callback ref może przechwycić uchwyt podczas renderowania, dzięki czemu test ma stabilne odwołanie, za pomocą którego może wywoływać metody.

Storybook jest dobrym miejscem do prezentowania uchwytów imperatywnych. Story może przechowywać ref do komponentu i renderować przyciski wywołujące jego metody, pozwalając osobom dokonującym przeglądu interaktywnie sprawdzać play, pause lub goToSlide.

Takie stories są jednocześnie żywą dokumentacją i pokazują dokładnie, jak imperatywne API zachowuje się w izolacji.

Uchwyty imperatywne są często używane podczas opakowywania bibliotek niebędących bibliotekami React. Biblioteki wykresów udostępniają metody redraw lub update, SDK map udostępniają panTo i setZoom, a edytory tekstu sformatowanego udostępniają insertText lub getContents.

Opakowanie takiej biblioteki w komponent React i udostępnienie za jego pośrednictwem przejrzystego uchwytu daje reszcie aplikacji uporządkowany, idiomatyczny sposób sterowania nią.

Metody uchwytu często przechwytują bieżący stan, dlatego należy używać tablicy zależności useImperativeHandle, aby odświeżać je w razie potrzeby, oraz useCallback dla wewnętrznych funkcji pomocniczych, by unikać nieaktualnych domknięć.

Dobrze zarządzany uchwyt zawsze działa na aktualnych wartościach, więc wywołanie getValue lub seekTo przez komponent nadrzędny daje zachowanie zgodne z najnowszym renderowaniem.

Zastosuj zasadę projektowania imperatywnych API komponentów.

Zaprojektowano uchwyty dla FocusableInput, VideoPlayer i Carousel, z których każdy udostępnia niewielki zestaw metod operacyjnych. Metody te należy dokumentować i wersjonować, ponieważ konsumenci polegają na nich jak na publicznym API.

Należy łączyć działania imperatywne z deklaratywnymi propsami, testować je za pośrednictwem ref.current wewnątrz act oraz prezentować ich zachowanie w Storybook. Ten sam wzorzec pozwala czysto opakowywać biblioteki wykresów, map i edytorów.