명령형 컴포넌트 API 구축

계약부터 정하시면 됩니다. FocusableInput은 포커스 설정, 포커스 해제, getValue를 노출할 수 있습니다. forwardRef로 감싸고 실제 입력 요소를 가리키는 내부 참조를 유지한 다음, useImperativeHandle에서 이 세 메서드를 반환하시면 됩니다.

각 메서드는 기반 입력 요소에 작업을 위임하므로, 부모는 원시 요소에 직접 접근하지 않고 필요한 작업만 정확히 사용할 수 있습니다.

명령형 API는 미디어 컴포넌트에 큰 도움이 됩니다. VideoPlayer는 재생, 일시 정지, seekTo를 노출할 수 있으며, 각 작업은 내부 비디오 참조가 가리키는 네이티브 HTML 비디오 요소의 메서드에 위임됩니다.

seekTo는 초 단위 시간을 받아 currentTime을 설정하므로, 프롭만으로는 다루기 까다로운 재생을 부모가 정밀하게 제어할 수 있습니다.

외부 컨트롤이나 키보드 핸들러가 캐러셀을 제어할 수 있도록 다음, 이전, goToSlide를 노출할 수 있습니다. 내부적으로 이 메서드들은 활성 인덱스 상태를 갱신하고 컴포넌트는 새 슬라이드로 다시 렌더링됩니다.

이 방식은 명령형 트리거와 선언형 렌더링을 결합합니다. 부모가 전환을 명령하면 캐러셀이 일반적인 상태 흐름을 통해 결과를 렌더링합니다.

명령형 핸들은 공개 계약이므로 각 메서드와 매개변수, 반환 값을 문서화하셔야 합니다. 명확한 문서는 사용자가 지원되는 기능을 알게 하고 문서화되지 않은 내부 구현에 의존하지 않도록 합니다.

핸들을 다른 API 표면과 동일하게 다루십시오. 재생(), 일시 정지(), seekTo(초)와 같은 메서드를 나열한 짧은 참조 문서가 잘못된 사용과 혼란을 막아 줍니다.

사용자 코드가 핸들에 의존하기 시작하면 메서드를 제거하거나 이름을 바꾸는 것은 호환성을 깨뜨리는 변경입니다. 기존 서명을 변경하기보다 새 메서드를 추가하고, 무엇이든 제거하기 전에 단계적으로 지원 중단을 예고하십시오.

핸들을 버전이 관리되는 API로 생각하면 시간이 지나 컴포넌트를 확장하더라도 하위 코드가 깨지는 일을 막을 수 있습니다.

실제 컴포넌트는 두 스타일을 함께 사용하는 경우가 많습니다. VideoPlayer는 선언적으로 소스 프롭과 autoPlay 프롭을 받으면서, 프롭만으로는 잘 표현하기 어려운 순간을 위해 명령형 재생 및 seekTo도 노출할 수 있습니다.

지침은 상태와 설정에는 프롭을 사용하고, 특정 시점에 트리거되는 일회성 작업에는 명령형 핸들을 사용하라는 것입니다.

명령형 API를 테스트하려면 참조를 연결해 컴포넌트를 렌더링하고, 상호작용을 act로 감싼 다음 ref.current를 통해 노출된 메서드를 호출하십시오. 그런 다음 비디오가 일시 정지되었는지 또는 슬라이드 인덱스가 바뀌었는지와 같은 관찰 가능한 결과를 검증하십시오.

참조 콜백은 렌더링 중 핸들을 캡처할 수 있으므로, 테스트에서 메서드를 호출할 안정적인 참조를 확보할 수 있습니다.

스토리북은 명령형 핸들을 보여 주기에 좋은 곳입니다. 스토리에서 컴포넌트에 대한 참조를 보관하고 해당 메서드를 호출하는 버튼을 렌더링하면, 검토자가 재생, 일시 정지 또는 goToSlide를 직접 실행해 볼 수 있습니다.

이러한 스토리는 살아 있는 문서 역할도 하며, 명령형 API가 독립적으로 어떻게 동작하는지 정확히 보여 줍니다.

명령형 핸들은 리액트가 아닌 라이브러리를 감쌀 때 흔히 사용됩니다. 차트 라이브러리는 다시 그리기 또는 갱신 메서드를 제공하고, 지도 SDK는 panTo와 setZoom을 제공하며, 서식 있는 텍스트 편집기는 insertText 또는 getContents를 제공합니다.

이러한 라이브러리를 리액트 컴포넌트로 감싸고 깔끔한 핸들을 외부에 제공하면, 앱의 나머지 부분에서 해당 라이브러리를 제어할 정돈되고 관용적인 방법을 얻을 수 있습니다.

핸들의 메서드는 현재 상태를 클로저에 캡처하는 경우가 많으므로, 필요할 때 메서드를 갱신하도록 useImperativeHandle의 의존성 배열을 사용하고 오래된 클로저를 피하려면 내부 도우미에 useCallback을 사용하십시오.

잘 관리되는 핸들은 항상 최신 값으로 작동하므로, 부모가 getValue 또는 seekTo를 호출하면 최신 렌더링과 일관된 동작을 얻을 수 있습니다.

명령형 컴포넌트 API에 대한 설계 지침을 적용해 보십시오.

FocusableInput, VideoPlayer, Carousel을 위한 핸들을 설계하고, 각각 소수의 작업 메서드를 노출했습니다. 사용자는 이러한 메서드에 공개 API로 의존하므로 문서화하고 버전을 관리해야 합니다.

명령형 작업과 선언형 프롭을 함께 사용하고, act 안에서 ref.current를 통해 테스트하며, 스토리북에서 동작을 보여 주십시오. 같은 패턴으로 차트, 지도, 편집기 라이브러리도 깔끔하게 감쌀 수 있습니다.