useImperativeHandle: пользовательские значения экземпляра

Когда ссылка ref напрямую пересылается элементу DOM, родитель получает исходный узел DOM и доступ ко всем его встроенным методам и свойствам. Это часто даёт больше возможностей, чем требуется предоставить.

Иногда лучше передать родителю небольшой, тщательно отобранный объект вместо полного узла DOM, намеренно сохранив публичный интерфейс компонента узким.

useImperativeHandle позволяет настроить значение, на которое указывает ref родителя. Вместо узла DOM родитель получает любой возвращённый вами объект, поэтому именно вы решаете, какие методы и значения будут доступны.

Так переданная дальше ссылка ref превращается в определённый императивный интерфейс, а не в неконтролируемый проход к исходному элементу.

Хук принимает переданную дальше ссылку ref первым аргументом, а функцию-фабрику — вторым. Фабрика возвращает объект дескриптора, который становится значением ref.current у родителя.

Вызов выглядит так: useImperativeHandle(ref, () => ({ ... })); внутри фабрики создаётся объект методов и значений, которые вы хотите сделать доступными.

Распространённый шаблон — пользовательское поле ввода, предоставляющее только focus() и clear(). Внутри фабрики вы возвращаете объект с этими двумя методами, каждый из которых работает с внутренней ссылкой ref на настоящее поле ввода.

Теперь родитель может сфокусировать поле или очистить его, но не может прочитать его исходный атрибут value или запустить произвольное поведение DOM, что делает использование предсказуемым.

Императивные дескрипторы хорошо подходят для диалоговых окон. Компонент Modal может предоставить методы open() и close(), которые изменяют его внутреннее состояние видимости, позволяя родителю управлять императивно, не управляя самостоятельно логическим значением open.

Это удобно для кода, которому нужно запускать диалоговое окно из разных мест, например показывать подтверждение после завершения асинхронного действия.

Возвращая только те методы, поддержку которых вы намерены обеспечивать, вы создаёте ясный контракт. Пользователи зависят от небольшого документированного набора операций, а не от обширного интерфейса DOM, поэтому будущие переработки становятся безопаснее.

Узкий императивный интерфейс проще проверять и анализировать, и он гораздо реже ломается при изменении внутренней реализации.

useImperativeHandle принимает необязательный третий аргумент — массив зависимостей. Когда любая зависимость изменяется, фабрика запускается снова и объект дескриптора создаётся заново, подобно тому как работают useMemo и useEffect.

Если предоставляемые методы замыкают значения, которые могут изменяться, укажите эти значения в зависимостях, чтобы родитель всегда получал дескриптор, связанный с текущим состоянием.

useImperativeHandle имеет смысл только внутри компонента, обёрнутого в forwardRef, поскольку ему нужна переданная дальше ссылка ref, к которой можно прикрепить пользовательский дескриптор. Сам по себе он не имел бы ссылки ref родителя, которую можно заполнить.

Поэтому эти два инструмента используются вместе: forwardRef передаёт ссылку ref внутрь, а useImperativeHandle определяет, на что в итоге будет указывать эта ссылка.

Чтобы проверить дескриптор, отрисуйте компонент со ссылкой ref, затем вызовите методы через ref.current внутри блока act и проверьте получившееся поведение или изменения DOM.

Поскольку предоставляемый интерфейс небольшой и явно определён, такие проверки получаются целенаправленными: каждая проверяет, выполняет ли документированный метод обещанное контрактом, а не обращается к внутренним деталям.

В TypeScript определите интерфейс, описывающий дескриптор, например интерфейс с методами focus() и clear(), а затем используйте его для типизации обобщённого параметра forwardRef и ссылки ref, которую хранит родитель.

Это обеспечивает автодополнение и проверки во время компиляции в месте вызова, поэтому пользователи видят, какие именно методы существуют, а неправильное использование обнаруживается ещё до выполнения.

Убедитесь, что понимаете, для чего на самом деле предназначен useImperativeHandle.

useImperativeHandle настраивает содержимое, предоставляемое переданной дальше ссылкой ref, принимая ссылку ref и фабрику, которая возвращает объект дескриптора. Используйте его, чтобы предоставить небольшой интерфейс вроде focus() и clear() или open() и close() для модального окна.

Он всегда используется вместе с forwardRef, поддерживает массив зависимостей для обновления дескриптора и хорошо сочетается с интерфейсами TypeScript и целенаправленными проверками. Ограниченный интерфейс — это намеренный и хороший проектный подход.