Создание императивного API компонента

Начните с определения контракта: FocusableInput может предоставлять методы фокусировки, снятия фокуса и getValue. Оберните его в forwardRef, сохраните внутреннюю ссылку на настоящий элемент ввода и верните эти три метода через useImperativeHandle.

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

Медиакомпоненту очень полезен императивный API. VideoPlayer может предоставлять методы воспроизведения, паузы и seekTo, каждый из которых делегирует вызов встроенным методам видеоэлемента HTML через внутреннюю ссылку на видео.

seekTo принимает время в секундах и устанавливает currentTime, что даёт родительским компонентам точный контроль над воспроизведением, которым было бы неудобно управлять только через свойства.

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

Так императивные вызовы сочетаются с декларативным отображением: родительский компонент задаёт переход, а карусель отображает результат через обычный поток работы с состоянием.

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

Рассматривайте дескриптор как любую другую поверхность API: краткий справочник с перечнем методов воспроизведения, паузы и seekTo(секунды) предотвращает неправильное использование и путаницу.

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

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

Многие реальные компоненты сочетают оба подхода. VideoPlayer может декларативно принимать свойство источника и свойство autoPlay, одновременно предоставляя императивные методы воспроизведения и seekTo для ситуаций, которые свойства не могут хорошо описать.

Правило таково: используйте свойства для состояния и настройки, а императивный дескриптор оставляйте для разовых действий, запускаемых в определённые моменты.

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

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

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

Такие истории одновременно служат живой документацией и точно показывают, как императивный API ведёт себя в изоляции.

Императивные дескрипторы часто применяются при обёртывании библиотек, не относящихся к React. Библиотеки для построения графиков предоставляют методы перерисовки или обновления, SDK карт — panTo и setZoom, а редакторы форматированного текста — insertText или getContents.

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

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

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

Примените рекомендации по проектированию императивных API компонентов.

Вы спроектировали дескрипторы для FocusableInput, VideoPlayer и карусели, каждый из которых предоставляет небольшой набор методов действий. Документируйте эти методы и управляйте их версиями, поскольку потребители зависят от них как от публичного API.

Сочетайте императивные действия с декларативными свойствами, тестируйте через ref.current внутри act и демонстрируйте поведение в Storybook. Такой же шаблон аккуратно оборачивает библиотеки для графиков, карт и редакторов.