React 表单失控警告：Warning 背后的问题与修复方案

在 React 开发中，你是否遇到过这样的黄色警告？

Warning: A component is changing an uncontrolled input of type ...

这条警告通常出现在 <input>、<textarea> 或 <select> 等表单元素上，提示你正在**「从非受控组件变为受控组件」**或反之。它不会阻断渲染，却会让表单行为变得难以预测：光标跳动、值丢失、校验失效……本文将带你快速定位原因，并给出 3 种常见场景的修复代码。

---

一、什么是「受控」与「非受控」？

• 受控组件（Controlled）：
  表单元素的 value 始终由 React state 控制，并通过 onChange 更新 state。

• 非受控组件（Uncontrolled）：
  表单元素的值由 DOM 自己管理，React 只通过 ref 读取。

React 期望组件在整个生命周期里保持同一种模式。若中途切换，就会抛出警告。

---

二、触发警告的 3 大高频场景

场景 1：初始值为 undefined 或 null

function NameField() {
  const [name, setName] = useState(); // ❌ 初始 undefined
  return <input value={name} onChange={e => setName(e.target.value)} />;
}

原因：首次渲染时 value={undefined}，React 认为这是「非受控」。随后 state 变为字符串，又变成「受控」，导致模式切换。

修复：给 state 一个字符串初始值。

const [name, setName] = useState(''); // ✅ 空字符串

---

场景 2：条件渲染时 value 类型不一致

function PriceInput({ editing }) {
  const [price, setPrice] = useState(0);
  return (
    <>
      {editing ? (
        <input
          type="number"
          value={price} // ✅ 数字
          onChange={e => setPrice(Number(e.target.value))}
        />
      ) : (
        <input type="number" value={null} /> // ❌ 变成 null
      )}
    </>
  );
}

原因：当 editing=false 时，value 变为 null，组件由受控 → 非受控。

修复：始终传递同类型值；不可用 null 或 undefined 占位。

<input type="number" value={editing ? price : ''} />

---

场景 3：checkbox / radio 的 checked 与 defaultChecked 混用

function Checkbox() {
  const [checked, setChecked] = useState(false);
  return (
    // ❌ 同时使用 defaultChecked 与 checked
    <input
      type="checkbox"
      defaultChecked={checked}
      checked={checked}
      onChange={e => setChecked(e.target.checked)}
    />
  );
}

原因：defaultChecked 只在首次渲染生效，后续由 checked 控制，两者并存会冲突。

修复：删除 defaultChecked，完全交给 state 管理。

<input
  type="checkbox"
  checked={checked}
  onChange={e => setChecked(e.target.checked)}
/>

---

三、快速自查清单

检查点	正确示例
state 初始值类型	useState('')
value 不为 null/undefined	value={text ?? ''}
不混用 defaultValue & value	二选一
checkbox/radio 统一使用 checked	checked={flag}

---

四、总结

出现「changing an uncontrolled input」警告时，99% 的原因是 value/checked 的值在受控与非受控之间切换。牢记：

• 永远给 state 字符串初始值（'' 而不是 undefined）。
• 永远保持 value 类型一致（数字、布尔或字符串）。
• 永远 二选一 使用 value 或 defaultValue，不要混用。

修复后，表单将恢复可预测、可测试、可维护的状态。祝你写表单不再踩坑！

---

最后问候亲爱的朋友们，并邀请你们阅读我的全新著作

📚 《 React开发实践：掌握Redux与Hooks应用 》