<input>

<input />

• 参考
  • <input>
• 用法
  • 展示不同类型的输入框
  • 为输入框提供 label 属性
  • 为输入框提供初始值
  • 提交表单时读取输入框的值
  • 使用 state 控制输入框
  • 优化每次按键时的重新渲染
• 故障排除
  • 输入时文本框未更新
  • 点击时多选框未更新
  • 当我输入时，输入框光标会跳到开头
  • 收到错误：“A component is changing an uncontrolled input to be controlled”

参考

<input>

渲染 浏览器内置的 <input> 组件以展示输入框。

<input name="myInput" />

参见下面更多示例。

属性

<input> 支持所有 常见的元素属性。

你可以传递以下属性中的任意一个，以将其变为 受控输入框：

• checked：布尔值，控制复选框或单选按钮是否被选中。
• value：字符串，控制文本框的输入文本（如果是单选按钮，则为其表单数据）。

当你传递它们之一时，你必须同时传递 onChange 处理函数，用于更新传递的值。

以下 <input> 属性仅在非受控输入框中有效：

• defaultChecked：布尔值，指定 type="checkbox" 和 type="radio" 输入的 初始值。
• defaultValue：字符串，指定文本框的 初始值。

以下 <input> 属性均可用于受控与非受控输入框：

• accept：字符串，指定 type="file" 输入框所接受的文件类型。
• alt：字符串，指定 type="image" 输入框的替代图像文本。
• capture：字符串，指定 type="file" 输入框所捕获的媒体（麦克风、视频或摄像头）。
• autoComplete：字符串，指定可能的 自动填充行为 之一。
• autoFocus：布尔值。如果为 true，React 将在挂载时聚焦于此元素。
• dirname：字符串，指定元素的方向性的表单字段名称。
• disabled：布尔值。如果为true，输入框将无法交互并显示为不可用（dimmed）。
• children：<input> 不接受子元素。
• form：字符串，指定此输入框所属的 <form> 的 id。如果未指定，则为最近的父表单。
• formAction：字符串。输入框指定此值并指定 type="submit" 或 type="image" 后将覆盖父表单对应属性 <form action>。
• formEnctype：字符串。输入框指定此值并指定 type="submit" 或 type="image" 后将覆盖父表单对应属性 <form enctype>。
• formMethod：字符串。输入框指定此值并指定 type="submit" 或 type="image" 后将覆盖父表单对应属性 <form method>。
• formNoValidate：字符串。输入框指定此值并指定 type="submit" 或 type="image" 后将覆盖父表单对应属性 <form noValidate>。
• formTarget：字符串。输入框指定此值并指定 type="submit" 或 type="image" 后将覆盖父表单对应属性 <form target>。
• height：字符串，指定 type="image" 的图像高度。
• list：字符串，指定带有自动完成选项的 <datalist> 的 id。
• max：数字，指定数值和日期时间输入的最大值。
• maxLength：数字，指定文本和其他输入的最大长度。
• min：数字，指定数值和日期时间输入的最小值。
• minLength：数字，指定文本和其他输入的最小长度。
• multiple：布尔值，指定是否允许 <type="file" 和 type="email" 指定多个值。
• name：字符串，指定此输入框的名称，它将 随表单一起提交。
• onChange：一个 Event 处理函数。如果这是 受控输入框，则必须提供。在用户更改输入框的值时立即触发（例如，每次按键时触发）。行为类似于浏览器的 input 事件。
• onChangeCapture：与 onChange 类似，但是是在 捕获阶段 触发。
• onInput：一个 Event 处理函数。在用户更改值时立即触发。由于历史原因，在 React 中习惯于使用 onChange，工作方式类似。
• onInputCapture：与 onInput 类似，但是是在 捕获阶段 触发。
• onInvalid：一个 Event 处理函数。在表单提交时，如果输入框未通过验证将触发。与内置的 invalid 事件不同，React 的 onInvalid 事件可以进行冒泡。
• onInvalidCapture：与 onInvalid 类似，但是是在 捕获阶段 触发。
• onSelect：一个 Event 处理函数。在 <input> 内的选择更改后触发。React 扩展了 onSelect 事件，使其也能在选择为空和编辑时触发（可能会影响选择）。
• onSelectCapture：与 onSelect 类似，但是是在 捕获阶段 触发。
• pattern：字符串，指定 value 必须匹配的模式。
• placeholder：字符串，当输入值为空时，以暗淡的颜色显示的内容。
• readOnly：布尔值。如果为 true，用户无法编辑输入。
• required：布尔值。如果为 true，提交表单时必须提供此输入框的值。
• size：数字，类似于设置宽度，但单位取决于控件。
• src：字符串，指定 type="image" 输入框的图像源。
• step：正数或 'any' 字符串，指定有效值之间的距离。
• type：字符串，输入框类型 中的一个。
• width：字符串，指定 type="image" 输入框的图像宽度。

注意

• 复选框需要使用 checked 或 defaultChecked，而不是 value 或 defaultValue。
• 如果文本框接收到字符串类型的 value 属性，则会被 视为受控组件。
• 如果复选框或单选按钮接收到布尔类型的 checked 属性，则会被 视为受控组件。
• 一个输入框不能同时既是受控组件又是非受控组件。
• 一个输入框在其生命周期中不能在受控和非受控之间切换。
• 每个受控组件都需要一个 onChange 事件处理函数，用于同步更新其值。

用法

展示不同类型的输入框

渲染 input 组件展示输入框。默认情况下，这是一个文本框。你可以传递 type="checkbox" 将其指定为多选框；或者传递 type="radio" 将其指定为单选按钮；你也可以将其指定为其他类型。

为输入框提供 label 属性

一般而言，应该将每个 <input> 都放置在 <label> 内，表示此标签与该选择框相关联。当用户单击标签时，浏览器将自动聚焦选择框。这对于可访问性也非常重要：当用户聚焦选择框时，屏幕阅读器将宣布标签标题。

如果无法将 <input> 放置在 <label> 内，请通过将相同的 ID 传递给 <input id> 与 <label htmlFor> 来将它们关联起来。为了避免一个组件的多实例之间的冲突，使用 useId 生成这样的 ID。

为输入框提供初始值

你可以为任何输入框指定初始值。如果要为文本框指定初始值，传递字符串 defaultValue；如果要为复选框和单选按钮指定初始值，传递布尔值 defaultChecked。

提交表单时读取输入框的值

在输入框周围添加一个包含 <button type="submit"> 按钮的 <form> 组件。这将调用 <form onSubmit> 事件处理程序。默认情况下，浏览器将向当前 URL 发送表单数据并刷新页面。你可以通过调用 e.preventDefault() 取消此默认行为，并使用 new FormData(e.target) 读取表单数据。

使用 state 控制输入框

像 <input /> 这样的输入框是非受控的。即使你像 <input defaultValue="Initial text" /> 一样 传递了初始值，你的 JSX 也只是指定了初始值，而非当前时刻的值。

如果要渲染一个受控输入框，请传递 value 属性（或者向多选框和单选按钮传递 checked。React 将强制传递 value 属性给输入框。通常，你可以通过声明一个 state 来控制输入框。

function Form() {
  const [firstName, setFirstName] = useState(''); // 声明一个 state 变量...
  // ...
  return (
    <input
      value={firstName} // ...强制输入框的值与 state 相匹配...
      onChange={e => setFirstName(e.target.value)} // ... 并在每次改变（change）时更新 state！
    />
  );
}

当你需要 state 时，受控输入框都将非常有用——比如，每次编辑时都重新渲染 UI：

function Form() {
  const [firstName, setFirstName] = useState('');
  return (
    <>
      <label>
        你的名称：
        <input value={firstName} onChange={e => setFirstName(e.target.value)} />
      </label>
      {firstName !== '' && <p>你的名称是 {firstName}。</p>}
      ...

如果你想提供多种方式来调整输入框 state（例如，通过单击按钮），它也会很有用：

function Form() {
  // ...
  const [age, setAge] = useState('');
  const ageAsNumber = Number(age);
  return (
    <>
      <label>
        年龄：
        <input
          value={age}
          onChange={e => setAge(e.target.value)}
          type="number"
        />
        <button onClick={() => setAge(ageAsNumber + 10)}>
          增加 10 年
        </button>

传递给受控组件的 value 属性不能是 undefined 或 null。如果你需要初始值为空（例如，下面的 firstName 字段），请将你的 state 变量初始化为空字符串（''）。

优化每次按键时的重新渲染

当你使用受控输入框时，每次按键都会设置 state。如果包含 state 的组件重新渲染了大型树形结构，这可能会变得很慢。有几种方法可以优化重新渲染的性能。

例如，假设表单在每次按键时会重新渲染所有页面内容：

function App() {
  const [firstName, setFirstName] = useState('');
  return (
    <>
      <form>
        <input value={firstName} onChange={e => setFirstName(e.target.value)} />
      </form>
      <PageContent />
    </>
  );
}

由于 <PageContent /> 不依赖于输入框 state，因此可以将输入框 state 移入其自己的组件中：

function App() {
  return (
    <>
      <SignupForm />
      <PageContent />
    </>
  );
}

function SignupForm() {
  const [firstName, setFirstName] = useState('');
  return (
    <form>
      <input value={firstName} onChange={e => setFirstName(e.target.value)} />
    </form>
  );
}

这样可以显著提高性能，因为每次按键时只有 SignupForm 会重新渲染。

如果无法避免重新渲染（例如，如果 PageContent 依赖于搜索输入框的值），useDeferredValue 可以帮助你在大型重新渲染过程中保持受控输入框的响应性（responsive）。

故障排除

输入时文本框未更新

如果传递了 value 属性给输入框，而没有传递 onChange 属性，那么你将在控制台看到错误信息：

// 🔴 Bug：没有 onChange 事件处理程序的受控文本框
<input value={something} />

正如错误信息所提示的，如果你仅仅是想要 指定初始值，请传递 defaultValue：

// ✅ Good：有初始值的非受控输入框
<input defaultValue={something} />

如果你想要 使用 state 变量控制输入框，指定 onChange 事件处理程序：

// ✅ Good：具有 onChange 事件处理程序的受控输入框
<input value={something} onChange={e => setSomething(e.target.value)} />

如果输入框是只读的，额外传递 readOnly 属性：

// ✅ Good：没有 onChange 事件处理程序的受控只读输入框
<input value={something} readOnly={true} />

点击时多选框未更新

如果传递了 checked 属性给多选框，而没有传递 onChange 属性，那么你将在控制台看到错误信息：

// 🔴 Bug：没有 onChange 事件处理程序的受控多选框
<input type="checkbox" checked={something} />

正如错误信息所提示的，如果你仅仅是想要 指定初始值，请传递 defaultValue：

// ✅ Good：有初始值的非受控多选框
<input type="checkbox" defaultChecked={something} />

If you want to control this checkbox with a state variable, specify an onChange handler:

// ✅ Good：具有 onChange 事件处理程序的受控多选框
<input type="checkbox" checked={something} onChange={e => setSomething(e.target.checked)} />

如果多选框是只读的，额外传递 readOnly 属性：

// ✅ Good：没有 onChange 事件处理程序的受控只读输入框
<input type="checkbox" checked={something} readOnly={true} />

当我输入时，输入框光标会跳到开头

如果你想要 控制输入框，你应该在 onChange 期间将对应的 state 变量更新为来自 DOM 的输入框的值。

你不应该将它更新为 e.target.value（对于多选框应该是 e.target.checked）以外的值：

function handleChange(e) {
  // 🔴 Bug：将输入框更新为 e.target.value 以外的值
  setFirstName(e.target.value.toUpperCase());
}

你也不应该异步更新：

function handleChange(e) {
  // 🔴 Bug：异步更新输入框
  setTimeout(() => {
    setFirstName(e.target.value);
  }, 100);
}

将 state 同步更新为 e.target.value 以解决此问题：

function handleChange(e) {
  // ✅ 将受控输入框的值同步更新为 e.target.value
  setFirstName(e.target.value);
}

如果这不能解决问题，有可能是因为每次输入时输入框都从 DOM 中删除并重新添加。同样，如果在每次重新渲染时不小心 重置了 state，就会发生这种情况。例如，如果输入框或其祖先组件总是接收不同的 key，或者嵌套使用组件（这在 React 中是不允许的，并且会导致“内部”组件在每次渲染时重新挂载），就会发生这种情况。

收到错误：“A component is changing an uncontrolled input to be controlled”

提供的 value 属性必须在整个生命周期中都为字符串。

你不能一会传递 value={undefined} 一会传递 value="some string"，这会导致 React 不清楚你是想指定受控组件还是非受控组件。受控组件的 value 属性应该始终接收字符串，而不是 null 或 undefined。

如果 value 来自 API 或 state，它可能会被初始化为 null 或 undefined。在这种情况下，要么最初将其设置为空字符串（''），要么传递 value={someValue ?? ''} 以确保 value 是一个字符串。

类似的，如果传递 checked 属性给多选框，请确保它始终是布尔值。