Eine imperative Komponenten-API entwickeln

Legen Sie zunächst den Vertrag fest: Ein FocusableInput kann focus, blur und getValue bereitstellen. Verpacken Sie es in forwardRef, halten Sie eine interne Ref auf das eigentliche Eingabefeld und geben Sie diese drei Methoden aus useImperativeHandle zurück.

Jede Methode delegiert an das zugrunde liegende Eingabefeld. So erhält die übergeordnete Komponente genau die benötigten Operationen, ohne auf das rohe Element zugreifen zu müssen.

Eine Medienkomponente profitiert stark von einer imperativen API. Ein VideoPlayer kann play, pause und seekTo bereitstellen, wobei jede Methode an die nativen Methoden von HTMLVideoElement über eine interne Video-Ref delegiert.

seekTo nimmt eine Zeitangabe in Sekunden entgegen und setzt currentTime. Dadurch erhalten übergeordnete Komponenten präzise Kontrolle über die Wiedergabe, die sich nur mit Props nur umständlich umsetzen ließe.

Ein Carousel kann next, prev und goToSlide bereitstellen, damit externe Steuerelemente oder Tastatur-Handler es bedienen können. Intern aktualisieren diese Methoden den Zustand des aktiven Index, woraufhin die Komponente den neuen Slide rendert.

Damit werden imperative Auslöser mit deklarativem Rendering verbunden: Die übergeordnete Komponente gibt den Befehl für einen Übergang, und das Carousel rendert das Ergebnis über seinen normalen Zustandsfluss.

Ein imperatives Handle ist ein öffentlicher Vertrag. Dokumentieren Sie daher jede Methode, ihre Parameter und ihren Rückgabewert. Eine klare Dokumentation zeigt den Konsumenten, was unterstützt wird, und verhindert, dass sie sich auf undokumentierte Interna verlassen.

Behandeln Sie das Handle wie jede andere API-Oberfläche: Eine kurze Referenz mit Methoden wie play(), pause() und seekTo(seconds) verhindert Fehlbedienung und Missverständnisse.

Sobald Konsumenten von einem Handle abhängen, ist das Entfernen oder Umbenennen einer Methode eine inkompatible Änderung. Fügen Sie neue Methoden hinzu, statt bestehende Signaturen zu ändern, und markieren Sie Methoden vor dem Entfernen schrittweise als veraltet.

Wenn Sie das Handle als versionierte API betrachten, verhindern Sie, dass nachgelagerter Code bricht, während Sie die Komponente im Laufe der Zeit erweitern.

Viele reale Komponenten kombinieren beide Stile. Ein VideoPlayer kann deklarativ eine src-Prop und eine autoPlay-Prop akzeptieren und gleichzeitig imperative Methoden wie play und seekTo bereitstellen, wenn sich bestimmte Situationen mit Props nicht gut ausdrücken lassen.

Die Richtlinie lautet: Verwenden Sie Props für Zustand und Konfiguration und reservieren Sie das imperative Handle für einmalige Aktionen, die zu bestimmten Zeitpunkten ausgelöst werden.

Um eine imperative API zu testen, rendern Sie die Komponente mit einer Ref, kapseln Sie Interaktionen in act und rufen Sie die bereitgestellten Methoden über ref.current auf. Prüfen Sie anschließend das beobachtbare Ergebnis, etwa ob das Video pausiert ist oder sich der Slide-Index geändert hat.

Ein Ref-Callback kann das Handle während des Renderns erfassen, sodass Ihr Test eine stabile Referenz hat, über die Methoden aufgerufen werden können.

Storybook eignet sich gut, um imperative Handles zu demonstrieren. Eine Story kann eine Ref auf die Komponente halten und Schaltflächen rendern, die ihre Methoden aufrufen. So können Reviewer play, pause oder goToSlide interaktiv ausprobieren.

Diese Stories dienen zugleich als lebende Dokumentation und zeigen genau, wie sich die imperative API isoliert verhält.

Imperative Handles sind beim Einbinden von Bibliotheken außerhalb von React weit verbreitet. Chart-Bibliotheken stellen Methoden wie redraw oder update bereit, Karten-SDKs bieten panTo und setZoom, und Rich-Text-Editoren stellen insertText oder getContents bereit.

Wenn Sie eine solche Bibliothek in eine React-Komponente verpacken und ein sauberes Handle nach außen geben, erhält der Rest Ihrer App eine übersichtliche, idiomatische Möglichkeit, sie zu steuern.

Methoden eines Handles schließen häufig den aktuellen Zustand ein. Verwenden Sie daher das Abhängigkeitsarray von useImperativeHandle, um sie bei Bedarf zu aktualisieren, und useCallback für interne Hilfsfunktionen, um veraltete Closures zu vermeiden.

Ein gut verwaltetes Handle arbeitet immer mit aktuellen Werten. Wenn eine übergeordnete Komponente getValue oder seekTo aufruft, erhält sie daher ein Verhalten, das mit dem neuesten Rendern übereinstimmt.

Wenden Sie die Designrichtlinie für imperative Komponenten-APIs an.

Sie haben Handles für einen FocusableInput, einen VideoPlayer und ein Carousel entworfen, die jeweils eine kleine Anzahl von Aktionsmethoden bereitstellen. Dokumentieren und versionieren Sie diese Methoden, da Konsumenten von ihnen als öffentlicher API abhängen.

Kombinieren Sie imperative Aktionen mit deklarativen Props, testen Sie über ref.current innerhalb von act und zeigen Sie das Verhalten in Storybook. Dasselbe Muster bindet Chart-, Karten- und Editor-Bibliotheken sauber ein.