useImperativeHandle: benutzerdefinierte Instanzwerte

Wenn Sie eine Ref direkt an ein DOM-Element weiterleiten, erhält die übergeordnete Komponente den unveränderten DOM-Knoten und Zugriff auf jede native Methode und Eigenschaft dieses Knotens. Das stellt häufig eine größere Oberfläche dar, als Sie bereitstellen möchten.

Manchmal möchten Sie der übergeordneten Komponente stattdessen lieber ein kleines, gezielt zusammengestelltes Objekt übergeben als den vollständigen DOM-Knoten. So bleibt die öffentliche API Ihrer Komponente bewusst eng gefasst.

Mit useImperativeHandle können Sie den Wert anpassen, auf den die Ref der übergeordneten Komponente zeigt. Statt des DOM-Knotens erhält die übergeordnete Komponente das von Ihnen zurückgegebene Objekt, sodass Sie exakt festlegen, welche Methoden und Werte bereitgestellt werden.

Dadurch wird die weitergeleitete Ref zu einer definierten imperativen Schnittstelle statt zu einer durchlässigen Weiterleitung an das zugrunde liegende Element.

Der Hook akzeptiert die weitergeleitete Ref als erstes Argument und eine Factory-Funktion als zweites. Die Factory gibt das Handle-Objekt zurück, das in der übergeordneten Komponente zu ref.current wird.

Sie rufen ihn als useImperativeHandle(ref, () => ({ ... })) auf und erstellen innerhalb der Factory das Objekt mit den Methoden und Werten, die verfügbar sein sollen.

Ein häufig verwendetes Muster ist ein benutzerdefiniertes Eingabefeld, das nur focus und clear bereitstellt. Innerhalb der Factory geben Sie ein Objekt mit diesen beiden Methoden zurück, die jeweils auf einer internen Ref zum tatsächlichen Eingabefeld arbeiten.

Die übergeordnete Komponente kann das Feld nun fokussieren oder leeren, aber weder dessen unveränderten Wert auslesen noch beliebiges DOM-Verhalten auslösen. Dadurch bleibt die Verwendung vorhersehbar.

Für Dialoge eignen sich imperative Handles besonders gut. Eine Modal-Komponente kann die Methoden open und close bereitstellen, die ihren internen Sichtbarkeitsstatus ändern. So kann eine übergeordnete Komponente sie imperativ steuern, ohne selbst den Boolean für open verwalten zu müssen.

Das ist praktisch für Code, der einen Dialog von vielen Stellen aus auslösen muss, etwa um nach Abschluss einer asynchronen Aktion eine Bestätigung anzuzeigen.

Indem Sie nur die Methoden zurückgeben, die Sie unterstützen möchten, schaffen Sie einen klaren Vertrag. Verwender hängen von einer kleinen, dokumentierten Menge an Operationen statt von der umfassenden DOM-API ab, wodurch zukünftige Refactorings sicherer werden.

Eine eng gefasste imperative Oberfläche lässt sich leichter testen und nachvollziehen und verursacht deutlich seltener Probleme, wenn Sie die interne Implementierung ändern.

useImperativeHandle akzeptiert ein optionales drittes Argument, ein Abhängigkeitsarray. Wenn sich eine Abhängigkeit ändert, wird die Factory erneut ausgeführt und das Handle-Objekt neu erstellt, ähnlich wie bei useMemo und useEffect.

Wenn die von Ihnen bereitgestellten Methoden Werte einschließen, die sich ändern können, führen Sie diese Werte als Abhängigkeiten auf, damit die übergeordnete Komponente immer ein Handle erhält, das an den aktuellen State gebunden ist.

useImperativeHandle ergibt nur innerhalb einer mit forwardRef umschlossenen Komponente Sinn, da die weitergeleitete Ref benötigt wird, um das benutzerdefinierte Handle an sie anzuhängen. Für sich allein gäbe es keine Ref der übergeordneten Komponente, die befüllt werden könnte.

Die beiden werden daher gemeinsam verwendet: forwardRef nimmt die Ref entgegen, und useImperativeHandle legt fest, worauf diese Ref letztendlich zeigt.

Um ein Handle zu testen, rendern Sie die Komponente mit einer Ref, rufen anschließend die Methoden über ref.current innerhalb eines act-Blocks auf und prüfen das resultierende Verhalten oder die Änderungen im DOM.

Da die bereitgestellte Oberfläche klein und explizit ist, bleiben diese Tests fokussiert. Sie überprüfen, ob jede dokumentierte Methode ihren vertraglich festgelegten Zweck erfüllt, statt interne Details zu untersuchen.

In TypeScript definieren Sie ein Interface, das das Handle beschreibt, beispielsweise eines mit den Methoden focus und clear. Anschließend verwenden Sie es, um sowohl das Generic von forwardRef als auch die Ref zu typisieren, die die übergeordnete Komponente hält.

Dadurch erhalten Sie Autovervollständigung und Prüfungen zur Compile-Zeit an der Aufrufstelle. Verwender sehen genau, welche Methoden vorhanden sind, und eine falsche Verwendung wird bereits vor der Laufzeit erkannt.

Bestätigen Sie, wofür useImperativeHandle tatsächlich gedacht ist.

useImperativeHandle passt an, was eine weitergeleitete Ref bereitstellt. Dazu erhält es die Ref und eine Factory, die ein Handle-Objekt zurückgibt. Sie verwenden es, um eine kleine API wie focus und clear oder open und close für ein Modal bereitzustellen.

Es wird immer zusammen mit forwardRef verwendet, unterstützt ein Abhängigkeitsarray zum Aktualisieren des Handles und lässt sich gut mit TypeScript-Interfaces und fokussierten Tests kombinieren. Eine begrenzte Oberfläche ist beabsichtigt und gutes Design.