<input />

• Ссылка
  • <input>
• Использование
  • Отображение входных данных разных типов
  • Добавление метки к элементу ввода
  • Указание начального значения для элемента ввода
  • Чтение значений входных данных при отправке формы
  • Управление элементом ввода с помощью переменной состояния
  • Оптимизация перерисовки при каждом нажатии клавиши
• Отладка
  • Ввод текста не обновляется при вводе
  • Чекбокс не обновляется при нажатии
  • Курсор ввода перескакивает в начало при каждом нажатии клавиши
  • Ошибка: «Компонент изменяет неконтролируемый элемент ввода на контролируемый»

Ссылка

<input>

Для отображения элемента ввода используйте компонент встроенного браузера <input>.

<input name="myInput" />

См. дополнительные примеры ниже.

Свойства

<input> поддерживает все общие свойства элементов.

• formAction: Строка или функция. Переопределяет родительское <form action> для type="submit" и type="image". При передаче URL в action форма будет вести себя как стандартная HTML-форма. При передаче функции в formAction функция обработает отправку формы. См. <form action>.

Вы можете сделать элемент ввода управляемым, передав одно из этих свойств:

• 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, поле ввода будет неактивным и отображаться серым.
• children: <input> не принимает дочерние элементы.
• form: Строка. Указывает форму, к которой относится данное поле ввода <form>. Если опущен, используется ближайшая родительская форма.
• formAction: Строка. Переопределяет родительское <form action> для type="submit" и type="image".
• formEnctype: Строка. Переопределяет родительский <form enctype> для type="submit" и type="image".
• formMethod: Строка. Переопределяет родительский <form method> для type="submit" и type="image".
• formNoValidate: Строка. Переопределяет родительский <form noValidate> для type="submit" и type="image".
• formTarget: Строка. Переопределяет родительский <form target> для type="submit" и type="image".
• height: Строка. Указывает высоту изображения для type="image".
• list: Строка. Указывает список id <datalist> с опциями автозаполнения.
• 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" для радиокнопки или один из других типов ввода.

export default function MyForm() {
  return (
    <>
      <label>
        Text input: <input name="myInput" />
      </label>
      <hr />
      <label>
        Checkbox: <input type="checkbox" name="myCheckbox" />
      </label>
      <hr />
      <p>
        Radio buttons:
        <label>
          <input type="radio" name="myRadio" value="option1" />
          Option 1
        </label>
        <label>
          <input type="radio" name="myRadio" value="option2" />
          Option 2
        </label>
        <label>
          <input type="radio" name="myRadio" value="option3" />
          Option 3
        </label>
      </p>
    </>
  );
}

Предоставление метки для поля ввода

Обычно каждое <input> помещается внутри тега <label>. Это сообщает браузеру, что эта метка связана с этим полем ввода. Когда пользователь нажимает на метку, браузер автоматически фокусируется на поле ввода. Это также важно для доступности: средство чтения с экрана объявляет текст метки, когда пользователь фокусируется на связанном поле ввода.

Если вы не можете вложить <input> в <label>, свяжите их, передав один и тот же идентификатор в <input id> и <label htmlFor>. Чтобы избежать конфликтов между несколькими экземплярами одного компонента, сгенерируйте такой идентификатор с помощью useId.

import { useId } from 'react';

export default function Form() {
  const ageInputId = useId();
  return (
    <>
      <label>
        Your first name:
        <input name="firstName" />
      </label>
      <hr />
      <label htmlFor={ageInputId}>Your age:</label>
      <input id={ageInputId} name="age" type="number" />
    </>
  );
}

Указание начального значения для поля ввода

Вы можете указать начальное значение для любого поля ввода. Передайте его как строку defaultValue для текстовых полей. Для флажков и радиокнопок начальное значение должно быть задано как булево значение defaultChecked.

export default function MyForm() {
  return (
    <>
      <label>
        Text input: <input name="myInput" defaultValue="Some initial value" />
      </label>
      <hr />
      <label>
        Checkbox: <input type="checkbox" name="myCheckbox" defaultChecked={true} />
      </label>
      <hr />
      <p>
        Radio buttons:
        <label>
          <input type="radio" name="myRadio" value="option1" />
          Option 1
        </label>
        <label>
          <input
            type="radio"
            name="myRadio"
            value="option2"
            defaultChecked={true} 
          />
          Option 2
        </label>
        <label>
          <input type="radio" name="myRadio" value="option3" />
          Option 3
        </label>
      </p>
    </>
  );
}

Чтение значений ввода при отправке формы

Окружите ваши поля ввода тегом <form> и поместите внутри <button type="submit">. Это вызовет обработчик события <form onSubmit>. По умолчанию браузер отправит данные формы на текущий URL и обновит страницу. Вы можете изменить это поведение, вызвав e.preventDefault(). Прочитайте данные формы с помощью new FormData(e.target).

export default function MyForm() {
  function handleSubmit(e) {
    // Prevent the browser from reloading the page
    e.preventDefault();

    // Read the form data
    const form = e.target;
    const formData = new FormData(form);

    // You can pass formData as a fetch body directly:
    fetch('/some-api', { method: form.method, body: formData });

    // Or you can work with it as a plain object:
    const formJson = Object.fromEntries(formData.entries());
    console.log(formJson);
  }

  return (
    <form method="post" onSubmit={handleSubmit}>
      <label>
        Text input: <input name="myInput" defaultValue="Some initial value" />
      </label>
      <hr />
      <label>
        Checkbox: <input type="checkbox" name="myCheckbox" defaultChecked={true} />
      </label>
      <hr />
      <p>
        Radio buttons:
        <label><input type="radio" name="myRadio" value="option1" /> Option 1</label>
        <label><input type="radio" name="myRadio" value="option2" defaultChecked={true} /> Option 2</label>
        <label><input type="radio" name="myRadio" value="option3" /> Option 3</label>
      </p>
      <hr />
      <button type="reset">Reset form</button>
      <button type="submit">Submit form</button>
    </form>
  );
}

Управление полем ввода с помощью переменной состояния

Поле ввода, например, <input />, является неуправляемым. Даже если вы передаете начальное значение, например, <input defaultValue="Initial text" />, ваш JSX только определяет начальное значение. Он не контролирует текущее значение.

Чтобы отобразить управляемое поле ввода, передайте в него свойство value (или checked для флажков и радиокнопок). React заставит поле ввода всегда иметь значение value, которое вы передали. Обычно это делается путем объявления переменной состояния с помощью

function Form() {
  const [firstName, setFirstName] = useState(''); // Declare a state variable...
  // ...
  return (
    <input
      value={firstName} // ...force the input's value to match the state variable...
      onChange={e => setFirstName(e.target.value)} // ... and update the state variable on any edits!
    />
  );
}

Управляемое поле ввода имеет смысл, если вам нужна переменная состояния — например, для повторного отображения пользовательского интерфейса при каждом изменении:

function Form() {
  const [firstName, setFirstName] = useState('');
  return (
    <>
      <label>
        First name:
        <input value={firstName} onChange={e => setFirstName(e.target.value)} />
      </label>
      {firstName !== '' && <p>Your name is {firstName}.</p>}
      ...

Это также полезно, если вы хотите предложить несколько способов изменения состояния поля ввода (например, нажав кнопку):

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

Значение value, которое вы передаёте управляемым компонентам, не должно быть undefined или null. Если вам нужно, чтобы начальное значение было пустым (например, для поля firstName ниже), инициализируйте переменную состояния пустой строкой ('').

import { useState } from 'react';

export default function Form() {
  const [firstName, setFirstName] = useState('');
  const [age, setAge] = useState('20');
  const ageAsNumber = Number(age);
  return (
    <>
      <label>
        First name:
        <input
          value={firstName}
          onChange={e => setFirstName(e.target.value)}
        />
      </label>
      <label>
        Age:
        <input
          value={age}
          onChange={e => setAge(e.target.value)}
          type="number"
        />
        <button onClick={() => setAge(ageAsNumber + 10)}>
          Add 10 years
        </button>
      </label>
      {firstName !== '' &&
        <p>Your name is {firstName}.</p>
      }
      {ageAsNumber > 0 &&
        <p>Your age is {ageAsNumber}.</p>
      }
    </>
  );
}

Оптимизация повторного рендеринга при каждом вводе символа

Когда вы используете управляемое поле ввода, вы устанавливаете состояние при каждом вводе символа. Если компонент, содержащий состояние, перерисовывает большой фрагмент, это может быть медленно. Есть несколько способов оптимизировать производительность повторного рендеринга.

Например, предположим, что вы начинаете с формы, которая перерисовывает всё содержимое страницы при каждом вводе символа:

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

Поскольку <PageContent /> не зависит от состояния поля ввода, вы можете перенести состояние поля ввода в свой собственный компонент:

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 позволяет поддерживать отзывчивость управляемого поля ввода даже во время большого перерисовывания.

Отладка

Моё текстовое поле не обновляется при вводе

Если вы отображаете поле ввода с value, но без onChange, в консоли появится ошибка:

// 🔴 Bug: controlled text input with no onChange handler
<input value={something} />

Как предполагает сообщение об ошибке, если вы хотели только указать начальное значение, передайте defaultValue вместо этого:

// ✅ Good: uncontrolled input with an initial value
<input defaultValue={something} />

Если вы хотите управлять этим полем с помощью переменной состояния, укажите обработчик onChange:

// ✅ Good: controlled input with onChange
<input value={something} onChange={e => setSomething(e.target.value)} />

Если значение предназначается для только для чтения, добавьте свойство readOnly для подавления ошибки:

// ✅ Good: readonly controlled input without on change
<input value={something} readOnly={true} />

Мой флажок не обновляется при нажатии

Если вы отображаете флажок с checked, но без onChange, в консоли появится ошибка:

// 🔴 Bug: controlled checkbox with no onChange handler
<input type="checkbox" checked={something} />

Как предполагает сообщение об ошибке, если вы хотели только указать начальное значение, передайте defaultChecked вместо этого:

// ✅ Good: uncontrolled checkbox with an initial value
<input type="checkbox" defaultChecked={something} />

Если вы хотите управлять этим флажком с помощью переменной состояния, укажите обработчик onChange:

// ✅ Good: controlled checkbox with onChange
<input type="checkbox" checked={something} onChange={e => setSomething(e.target.checked)} />

Если флажок предназначается для только для чтения, добавьте свойство readOnly для подавления ошибки:

// ✅ Good: readonly controlled input without on change
<input type="checkbox" checked={something} readOnly={true} />

Курсор моего поля ввода перемещается в начало при каждом вводе символа

Если вы управляете полем ввода, вы должны обновить его переменную состояния до значения поля из DOM во время onChange.

Вы не можете обновить его на что-то отличное от e.target.value (или e.target.checked для флажков):

function handleChange(e) {
  // 🔴 Bug: updating an input to something other than e.target.value
  setFirstName(e.target.value.toUpperCase());
}

Вы также не можете обновить его асинхронно:

function handleChange(e) {
  // 🔴 Bug: updating an input asynchronously
  setTimeout(() => {
    setFirstName(e.target.value);
  }, 100);
}

Чтобы исправить код, обновите его синхронно до e.target.value:

function handleChange(e) {
  // ✅ Updating a controlled input to e.target.value synchronously
  setFirstName(e.target.value);
}

Если это не решит проблему, возможно, поле ввода удаляется и добавляется повторно из DOM при каждом вводе символа. Это может произойти, если вы случайно сбрасываете состояние при каждом перерисовке, например, если поле ввода или один из его родителей всегда получает другое значение атрибута key, или если вы вкладываете определения функций компонентов (что не поддерживается и приводит к тому, что «внутренний» компонент всегда считается другим деревом).

Получаю ошибку: «Компонент изменяет неуправляемый ввод на управляемый»

Если вы предоставляете свойство value компоненту, оно должно оставаться строкой на протяжении всего своего существования.

Вы не можете передать value={undefined} сначала, а затем передать value="some string", потому что React не будет знать, хотите ли вы, чтобы компонент был неуправляемым или управляемым. Управляемый компонент всегда должен получать строку value, а не null или undefined.

Если value поступает из API или переменной состояния, оно может быть инициализировано как null или undefined. В этом случае либо установите его в пустую строку ('') изначально, либо передайте value={someValue ?? ''}, чтобы убедиться, что value является строкой.

Аналогично, если вы передаёте checked флажку, убедитесь, что это всегда булево значение.