함수: useDebouncedValue()

function useDebouncedValue<TValue, TSelected>(
   value, 
   options, 
   selector?): [TValue, ReactDebouncer<Dispatch<SetStateAction<TValue>>, TSelected>];

정의 위치: react-pacer/src/debouncer/useDebouncedValue.ts:87

지정된 지연 시간이 지난 뒤에만 업데이트되는 디바운스된 값을 생성하는 React 훅입니다. useDebouncedState와 달리 입력 값의 변경을 자동으로 추적하고 이에 따라 디바운스된 값을 업데이트합니다.

디바운스된 값은 입력 값이 마지막으로 변경된 후 지정된 대기 시간이 경과해야 업데이트됩니다. 대기 시간이 끝나기 전에 입력 값이 다시 변경되면 타이머가 초기화되고 다시 대기하기 시작합니다.

검색 쿼리나 폼 입력처럼 자주 변경되는 props 또는 상태에서 디바운스된 값을 파생하면서 후속 이펙트나 계산의 실행 빈도를 제한하려는 경우 유용합니다.

훅은 현재 디바운스된 값과 내부 디바운서 인스턴스를 반환합니다. 디바운서 인스턴스로 취소, 실행 횟수 같은 추가 기능에 접근할 수 있습니다.

상태 관리와 셀렉터

훅은 내부 디바운서 인스턴스를 통해 반응형 상태 관리에 TanStack Store를 사용합니다. selector 매개변수를 사용하면 디바운서 상태의 어떤 변경이 재렌더링을 트리거할지 지정할 수 있으며, 관련 없는 상태가 변경될 때 불필요한 재렌더링을 방지하여 성능을 최적화합니다.

기본적으로 반응형 상태 구독은 없습니다. 상태 추적을 명시적으로 활성화하려면 셀렉터 함수를 제공해야 합니다. 이렇게 하면 불필요한 재렌더링을 방지하고 컴포넌트 업데이트 시점을 완전히 제어할 수 있습니다. 셀렉터를 제공한 경우에만 선택한 상태 값이 변경될 때 컴포넌트가 다시 렌더링됩니다.

사용 가능한 디바운서 상태 속성:

• canLeadingExecute: 디바운서가 선행 에지에서 실행될 수 있는지 여부
• executionCount: 완료된 함수 실행 횟수
• isPending: 디바운서가 실행을 트리거할 타임아웃을 기다리는지 여부
• lastArgs: 가장 최근 maybeExecute 호출의 인수
• status: 현재 실행 상태('disabled' | 'idle' | 'pending')

타입 매개변수

TValue

TValue

TSelected

TSelected = DebouncerState<Dispatch<SetStateAction<TValue>>>

매개변수

value

TValue

options

ReactDebouncerOptions<Dispatch<SetStateAction<TValue>>, TSelected>

selector?

(state) => TSelected

반환값

[TValue, ReactDebouncer<Dispatch<SetStateAction<TValue>>, TSelected>]

예시

// Default behavior - no reactive state subscriptions
const [searchQuery, setSearchQuery] = useState('');
const [debouncedQuery, debouncer] = useDebouncedValue(searchQuery, {
  wait: 500 // Wait 500ms after last change
});

// Opt-in to re-render when pending state changes (optimized for loading indicators)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({ isPending: state.isPending })
);

// Opt-in to re-render when execution count changes (optimized for tracking executions)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({ executionCount: state.executionCount })
);

// Opt-in to re-render when debouncing status changes (optimized for status display)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({
    status: state.status,
    canLeadingExecute: state.canLeadingExecute
  })
);

// debouncedQuery will update 500ms after searchQuery stops changing
useEffect(() => {
  fetchSearchResults(debouncedQuery);
}, [debouncedQuery]);

// Handle input changes
const handleChange = (e) => {
  setSearchQuery(e.target.value);
};

// Access the selected debouncer state (will be empty object {} unless selector provided)
const { isPending, executionCount } = debouncer.state;