useActionState

const [state, formAction, isPending] = useActionState(fn, initialState, permalink?);

• Справочник
  • useActionState(action, initialState, permalink?)
• Использование
  • Использование информации, возвращаемой действием формы
• Отладка
  • Моё действие больше не может читать данные отправленной формы

Справочник

useActionState(action, initialState, permalink?)

Вызовите useActionState на верхнем уровне вашего компонента, чтобы создать состояние компонента, которое обновляется при вызове действия формы. Вы передаёте useActionState существующую функцию действия формы, а также начальное состояние, и она возвращает новое действие, которое вы используете в своей форме, вместе с последним состоянием формы и тем, всё ещё ли действие ожидает. Последнее состояние формы также передаётся в функцию, которую вы предоставили.

import { useActionState } from "react";

async function increment(previousState, formData) {
  return previousState + 1;
}

function StatefulForm({}) {
  const [state, formAction] = useActionState(increment, 0);
  return (
    <form>
      {state}
      <button formAction={formAction}>Increment</button>
    </form>
  )
}

Состояние формы — это значение, возвращаемое действием, когда форма была в последний раз отправлена. Если форма ещё не отправлена, это начальное состояние, которое вы передаёте.

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

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

Параметры

• fn: Функция, которая вызывается при отправке формы или нажатии кнопки. При вызове функции она получит предыдущее состояние формы (изначально initialState , которое вы передаёте, впоследствии — её предыдущее возвращаемое значение) в качестве своего начального аргумента, а затем аргументы, которые обычно получает действие формы.
• initialState: Значение, которое вы хотите, чтобы состояние имело изначально. Это может быть любое сериализуемое значение. Этот аргумент игнорируется после первого вызова действия.
• необязательный permalink: Строка, содержащая уникальный URL страницы, которую изменяет эта форма. Для использования на страницах с динамическим контентом (например, ленты) в сочетании с поэтапным улучшением: если fn является серверной функцией, и форма отправляется до загрузки JavaScript-пакета, браузер перейдёт по указанному URL-адресу постоянной ссылки, а не по URL-адресу текущей страницы. Убедитесь, что на целевой странице отображается тот же компонент формы (включая то же действие fn и permalink ), чтобы React знал, как передать состояние. После гидратации формы этот параметр не оказывает никакого влияния.

Возвращаемое значение

useActionState возвращает массив со следующими значениями:

1. Текущее состояние. Во время первого рендеринга оно будет совпадать с initialState , которое вы передали. После вызова действия оно будет совпадать со значением, возвращаемым действием.
2. Новое действие, которое вы можете передать в качестве свойства action вашему компоненту form или свойства formAction любому компоненту button внутри формы.
3. Флаг isPending , который сообщает вам, есть ли ожидающее переход.

Ограничения

• При использовании с фреймворком, поддерживающим React Server Components, useActionState позволяет сделать формы интерактивными до выполнения JavaScript на клиенте. При использовании без Server Components, оно эквивалентно локальному состоянию компонента.
• Функция, переданная в useActionState , получает дополнительный аргумент — предыдущее или начальное состояние — в качестве своего первого аргумента. Это делает её сигнатуру другой, чем если бы она использовалась непосредственно как действие формы без использования useActionState.

Использование

Использование информации, возвращаемой действием формы

Вызовите useActionState на верхнем уровне вашего компонента, чтобы получить значение, возвращаемое действием, с последней отправки формы.

import { useActionState } from 'react';
import { action } from './actions.js';

function MyComponent() {
  const [state, formAction] = useActionState(action, null);
  // ...
  return (
    <form action={formAction}>
      {/* ... */}
    </form>
  );
}

useActionState возвращает массив со следующими элементами:

1. Текущее состояние состояния формы, которое изначально устанавливается в начальное состояние, которое вы предоставили, а после отправки формы устанавливается в возвращаемое значение действия, которое вы предоставили.
2. Новое действие, которое вы передаёте в <form> в качестве свойства action.
3. Состояние ожидания, которое вы можете использовать, пока ваше действие обрабатывается.

При отправке формы будет вызвана функция действия, которую вы предоставили. Её возвращаемое значение станет новым текущим состоянием формы.

Предоставленное вами действие также получит новый первый аргумент — текущее состояние формы. В первый раз при отправке формы это будет начальное состояние, которое вы предоставили, а при последующих отправках — возвращаемое значение с последнего вызова действия. Остальные аргументы остаются такими же, как если бы useActionState не использовался.

function action(currentState, formData) {
  // ...
  return 'next state';
}

import { useActionState, useState } from "react";
import { addToCart } from "./actions.js";

function AddToCartForm({itemID, itemTitle}) {
  const [message, formAction, isPending] = useActionState(addToCart, null);
  return (
    <form action={formAction}>
      <h2>{itemTitle}</h2>
      <input type="hidden" name="itemID" value={itemID} />
      <button type="submit">Add to Cart</button>
      {isPending ? "Loading..." : message}
    </form>
  );
}

export default function App() {
  return (
    <>
      <AddToCartForm itemID="1" itemTitle="JavaScript: The Definitive Guide" />
      <AddToCartForm itemID="2" itemTitle="JavaScript: The Good Parts" />
    </>
  )
}

Отладка

Моё действие больше не может читать данные отправленной формы

Когда вы оборачиваете действие с помощью useActionState, оно получает дополнительный аргумент в качестве первого аргумента. Поэтому данные отправленной формы становятся его вторым аргументом вместо первого, как это обычно бывает. Новый первый аргумент, который добавляется, — текущее состояние формы.

function action(currentState, formData) {
  // ...
}