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>
  )
}

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

Если используется Server Action, 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) {
  // ...
}