useImperativeHandle: 사용자 지정 인스턴스 값

ref를 DOM 요소에 곧바로 전달하면 부모는 해당 DOM 노드 자체를 받으며, 그 노드의 모든 기본 메서드와 속성에 접근할 수 있습니다. 하지만 이는 공개하려는 범위보다 넓은 경우가 많습니다.

때로는 전체 DOM 노드 대신 작고 엄선된 객체를 부모에게 제공하여, 컴포넌트의 공개 API를 의도적으로 좁게 유지하는 편이 좋습니다.

useImperativeHandle을 사용하면 부모의 ref가 가리키는 값을 사용자 지정할 수 있습니다. 부모는 DOM 노드 대신 반환한 객체를 받으므로, 어떤 메서드와 값을 공개할지 정확하게 결정할 수 있습니다.

이를 통해 전달된 ref가 기반 요소를 그대로 통과시키는 방식이 아니라, 명확하게 정의된 명령형 인터페이스가 되도록 만들 수 있습니다.

이 훅은 전달된 ref를 첫 번째 인수로 받고 팩토리 함수를 두 번째 인수로 받습니다. 팩토리는 부모의 ref.current가 되느 핸들 객체를 반환합니다.

useImperativeHandle(ref, () => ({ ... }))과 같이 호출하고, 팩토리 내부에서 사용할 수 있게 만들 메서드와 값으로 객체를 구성합니다.

일반적인 패턴은 focus와 clear만 노출하는 사용자 정의 입력 컴포넌트입니다. 팩토리 내부에서 이 두 메서드를 가진 객체를 반환하고, 각 메서드는 실제 입력 요소를 가리키는 내부 ref를 사용합니다.

이제 부모는 필드에 포커스를 맞추거나 필드를 지울 수 있지만, 원시 value 속성을 읽거나 임의의 DOM 동작을 실행할 수는 없습니다. 따라서 사용 방식이 예측 가능하게 유지됩니다.

명령형 핸들은 대화상자에 잘 맞습니다. 모달 컴포넌트는 내부 표시 상태를 전환하는 open 및 close 메서드를 공개할 수 있으므로, 부모가 open 불리언을 직접 관리하지 않고도 명령형으로 모달을 제어할 수 있습니다.

이는 비동기 작업이 완료된 후 확인 대화상자를 표시하는 것처럼 여러 위치에서 대화상자를 실행해야 하는 코드에 편리합니다.

지원하려는 메서드만 반환하면 명확한 계약을 만들 수 있습니다. 사용하는 쪽은 방대한 DOM API가 아니라 작고 문서화된 작업 집합에 의존하게 되므로, 향후 리팩터링이 더 안전해집니다.

좁은 명령형 노출 범위는 테스트하기도 쉽고 동작을 추론하기도 쉬우며, 내부 구현을 변경할 때 깨질 가능성도 훨씬 낮습니다.

useImperativeHandle은 선택적인 세 번째 인수인 의존성 배열을 받을 수 있습니다. 의존성 중 하나라도 변경되면 팩토리가 다시 실행되고 핸들 객체가 새로 만들어집니다. 이는 useMemo와 useEffect의 동작 방식과 비슷합니다.

공개하는 메서드가 변경될 수 있는 값을 클로저로 참조한다면 해당 값을 의존성으로 나열하여, 부모가 항상 현재 상태에 연결된 핸들을 받도록 하십시오.

useImperativeHandle은 forwardRef로 감싼 컴포넌트 내부에서만 의미가 있습니다. 사용자 지정 핸들을 연결하려면 전달된 ref가 필요하기 때문입니다. useImperativeHandle만 단독으로 사용하면 채울 부모 ref가 없습니다.

따라서 두 가지를 함께 사용합니다. forwardRef가 ref를 받아들이고, useImperativeHandle이 그 ref가 최종적으로 가리킬 대상을 정의합니다.

핸들을 테스트하려면 ref와 함께 컴포넌트를 렌더링한 다음, act 블록 안에서 ref.current를 통해 메서드를 호출하고 그 결과로 발생한 동작이나 DOM 변경을 검증합니다.

공개된 범위가 작고 명확하므로 이러한 테스트의 검증 범위도 분명합니다. 내부 세부 사항을 확인하는 대신 문서화된 각 메서드가 계약대로 동작하는지 검증합니다.

TypeScript에서는 핸들을 설명하는 인터페이스를 정의합니다. 예를 들어 focus 및 clear 메서드를 포함하는 인터페이스를 정의한 다음, 이를 forwardRef 제네릭과 부모가 보관하는 ref의 형식을 지정하는 데 사용합니다.

이를 통해 호출 위치에서 자동 완성과 컴파일 시점 검사를 제공하므로, 사용하는 쪽에서 어떤 메서드가 존재하는지 정확히 확인할 수 있고 잘못된 사용은 런타임 전에 발견됩니다.

useImperativeHandle은 전달된 ref가 공개하는 내용을 사용자 지정하며, ref와 핸들 객체를 반환하는 팩토리를 받습니다. 이를 사용하여 focus와 clear 같은 작은 API를 공개하거나, 모달에서 open과 close를 공개할 수 있습니다.

항상 forwardRef와 함께 사용하고, 핸들을 새로 고칠 수 있도록 의존성 배열을 지원하며, TypeScript 인터페이스 및 범위가 명확한 테스트와 잘 어울립니다. 제한된 노출 범위는 의도된 것이며 좋은 설계입니다.