---
title: "useControlled 用法与示例"
description: "`useControlled` 是一个自定义 hook，帮助你管理受控组件。它是 `useState` 的一个包装器，允许你从外部控制组件的值。"
canonical: https://reactuse.com/zh-Hans/state/usecontrolled/
---

# useControlled

`useControlled` 是一个自定义 hook，帮助你管理受控组件。它是 `useState` 的一个包装器，允许你从外部控制组件的值。

:::note
`useControlled` 组件不支持在受控和非受控之间切换，也不支持传递函数更新函数，可以参考这个讨论 https://github.com/adobe/react-spectrum/issues/2320
:::

`useControlled` 返回一个 `[value, setValue]` 元组，当第一个参数为 `undefined` 时表现为 `useState`（非受控模式），当值被定义时则镜像提供的值（受控模式）。可选的 `onChange` 回调在值变化时被调用。此模式对于构建需要同时支持受控和非受控输入的组件至关重要。

### 使用场景

- 构建必须同时支持受控和非受控用法的可复用表单组件（输入框、选择器、滑块）
- 封装需要受控接口的第三方组件，同时仍提供合理的非受控默认值
- 实现组件库，让使用者决定是自己管理状态还是让组件管理

### 注意事项

- **不支持模式切换**：hook 不支持在初始挂载后在受控和非受控模式之间切换。在创建时选择一种模式。
- **不支持函数更新器**：与 `useState` 不同，设置函数不接受 `(prev) => next` 函数形式。直接传递值。
- 参见 `useSetState` 了解类组件风格的部分状态更新器。

## Usage

```tsx live
function Demo() {
  const [state, setState] = useState<string>("");
  const [value, setValue] = useControlled(state, "");
  const [value1, setValue1] = useControlled(undefined, "unControlled value");

  const handleChange = (event) => {
    setState(event.target.value);
  };

  const handleChange1 = (event) => {
    setValue1(event.target.value);
  };

  return (
    <>
      <input value={value} onChange={handleChange} />
      <p>Controlled Value: {value}</p>
      <input value={value1} onChange={handleChange1} />
    </>
  );
}
```

%%API%%