当前位置：首页 > news >正文

antd 的 usePropsValue 的使用场景和源码解析

news 2025/7/27 22:11:37

`usePropsValue` 是 Ant Design 提供的一个自定义 Hook，用于处理受控和非受控组件的值管理。它可以帮助开发者轻松地在受控模式和非受控模式之间切换，同时简化组件的状态管理逻辑。

功能

usePropsValue 的主要功能是：

支持受控模式：
- 如果传入了 value 和 onChange 属性，usePropsValue 会将组件视为受控组件，value 的值完全由外部控制，组件内部不会维护状态。
支持非受控模式：
- 如果没有传入 value，但传入了 defaultValue，usePropsValue 会将组件视为非受控组件，内部会维护状态。
简化逻辑：
- 自动处理受控和非受控模式的切换，避免开发者手动编写复杂的逻辑。

使用场景

usePropsValue 通常用于开发需要支持受控和非受控模式的组件，例如表单组件（Input、Select 等）。

示例代码

以下是一个使用 usePropsValue 的示例，展示如何在自定义组件中使用它：

示例：自定义输入框组件

import React from 'react';
import { usePropsValue } from 'ahooks';

interface CustomInputProps {
  value?: string; // 受控模式的值
  defaultValue?: string; // 非受控模式的默认值
  onChange?: (value: string) => void; // 值变化时的回调
}

const CustomInput: React.FC<CustomInputProps> = (props) => {
  // 使用 usePropsValue 管理受控和非受控模式
  const [value, setValue] = usePropsValue({
    value: props.value,
    defaultValue: props.defaultValue,
    onChange: props.onChange,
  });

  return (
    <input
      value={value}
      onChange={(e) => setValue(e.target.value)}
      placeholder="请输入内容"
    />
  );
};

export default CustomInput;

解释

受控模式：

如果父组件传入了 value 和 onChange，CustomInput 会完全受控，value 的值由父组件控制。
示例：

const App = () => {
    const [value, setValue] = React.useState('');
    return (
        <CustomInput value={value} onChange={setValue} />
    );
};

非受控模式：
- 如果父组件没有传入 value，但传入了 defaultValue，CustomInput 会在内部维护状态。
- 示例：
```
const App = () => {
    return (
        <CustomInput defaultValue="默认值" />
    );
};
```
usePropsValue 的返回值：
- usePropsValue 返回一个数组，包含当前值和更新值的方法：
  - value: 当前的值。
  - setValue: 更新值的方法。

参数

usePropsValue 接收一个配置对象，常见的参数包括：

value: 受控模式下的值。
defaultValue: 非受控模式下的默认值。
onChange: 值变化时的回调函数。

源码

示例源码

import { useState, useEffect, useCallback } from 'react';

interface UsePropsValueOptions<T> {
  value?: T; // 受控模式下的值
  defaultValue?: T; // 非受控模式下的默认值
  onChange?: (value: T) => void; // 值变化时的回调
}

/**
 * usePropsValue 用于处理受控和非受控组件的值管理
 */
export function usePropsValue<T>(options: UsePropsValueOptions<T>) {
  const { value, defaultValue, onChange } = options;

  // 如果是非受控模式，使用内部状态
  const [innerValue, setInnerValue] = useState<T | undefined>(defaultValue);

  // 当前值：优先使用受控值 `value`，否则使用内部状态 `innerValue`
  // value === undefined 时为非受控模式
  const mergedValue = value === undefined ? innerValue : value;

  // 更新值的方法
  const setValue = useCallback(
    (newValue: T) => {
      // 如果是非受控模式，更新内部状态
      if (value === undefined) {
        setInnerValue(newValue);
      }
      // 调用 `onChange` 回调
      onChange?.(newValue);
    },
    [value, onChange]
  );

  // 如果 `defaultValue` 或 `value` 发生变化，更新内部状态
  useEffect(() => {
    if (value === undefined && defaultValue !== undefined) {
      setInnerValue(defaultValue);
    }
  }, [defaultValue, value]);

  return [mergedValue, setValue] as const;
}

解释

参数:
- value: 受控模式下的值。如果传入了 value，组件会完全受控。
- defaultValue: 非受控模式下的默认值。如果没有传入 value，但传入了 defaultValue，组件会使用内部状态。
- onChange: 值变化时的回调函数。
内部状态:
- 使用 useState 来管理非受控模式下的内部状态。
合并值:
- mergedValue 是当前的值。如果传入了 value（受控模式），优先使用 value；否则使用内部状态 innerValue。
更新值:
- setValue 是更新值的方法。如果是非受控模式，会更新内部状态；同时会调用 onChange 回调。
同步默认值:
- 如果 defaultValue 或 value 发生变化，useEffect 会同步更新内部状态。
返回值:
- 返回一个数组，包含当前值 mergedValue 和更新值的方法 setValue。