[react 번역] useActionState

출처: https://react.dev/reference/react/useActionState

개요

useActionState는 폼 액션의 결과에 따라 state를 업데이트할 수 있게 해주는 Hook입니다.

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

참고: 초기 React Canary 버전에서는 이 API가 React DOM의 일부였으며 useFormState라는 이름이었습니다.

Reference

`useActionState(action, initialState, permalink?)`

컴포넌트의 최상위에서 useActionState를 호출하여 폼 액션이 실행될 때 업데이트되는 컴포넌트 state를 생성할 수 있습니다. 기존 폼 액션 함수와 초기 state를 인자로 전달하면, 폼에서 사용할 새로운 액션과 최신 폼 state, 그리고 액션이 진행 중인지 여부를 반환합니다. 최신 폼 state는 전달한 함수에도 인자로 전달됩니다.

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

폼 state는 폼이 마지막으로 제출되었을 때 액션이 반환한 값입니다. 아직 제출되지 않았다면, 전달한 초기 state가 사용됩니다.
Server Function과 함께 사용할 경우, hydration이 완료되기 전에도 서버의 응답을 보여줄 수 있습니다.

파라미터

fn: 폼이 제출되거나 버튼이 눌렸을 때 호출되는 함수. 첫 번째 인자로 이전 state(초기에는 initialState), 그 뒤로는 폼 액션이 받는 인자들이 전달됩니다.
initialState: state의 초기값. 직렬화 가능한 값이면 무엇이든 가능. 액션이 처음 실행된 이후에는 무시됩니다.
permalink(선택): 이 폼이 수정하는 고유 페이지 URL. 동적 콘텐츠(예: 피드)에서 progressive enhancement와 함께 사용. Server Function과 함께 사용 시, 자바스크립트 번들이 로드되기 전에 폼이 제출되면 브라우저가 이 URL로 이동합니다. hydration 이후에는 효과가 없습니다.

반환값

현재 state (초기에는 initialState, 이후에는 액션의 반환값)
폼이나 버튼의 action/formAction prop에 전달할 새로운 액션 함수
액션이 진행 중임을 나타내는 isPending 플래그

주의사항

React Server Components를 지원하는 프레임워크에서 사용하면, 자바스크립트가 클라이언트에서 실행되기 전에도 폼을 인터랙티브하게 만들 수 있습니다. Server Components 없이 사용하면 컴포넌트의 로컬 state와 동일하게 동작합니다.
전달하는 함수는 첫 번째 인자로 이전 state를 받으므로, 일반 폼 액션과 시그니처가 다릅니다.

사용법

폼 액션의 반환값 사용하기

컴포넌트의 최상위에서 useActionState를 호출하여, 폼이 마지막으로 제출되었을 때 액션의 반환값에 접근할 수 있습니다.

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

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

useActionState는 다음 3가지를 배열로 반환합니다:
1. 폼의 현재 state (초기값 → 제출 후에는 액션의 반환값)
2. <form>의 action prop 또는 startTransition에서 수동 호출에 사용할 새 액션
3. 액션이 처리 중임을 나타내는 pending state

폼이 제출되면, 전달한 액션 함수가 호출되고, 그 반환값이 폼의 새로운 state가 됩니다.

액션 함수는 첫 번째 인자로 현재 폼 state를 받습니다. 첫 제출 시에는 초기값, 이후에는 마지막 반환값이 전달됩니다. 나머지 인자는 일반 폼 액션과 동일합니다.

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로 액션을 감싸면, 첫 번째 인자로 이전 state가 추가로 전달됩니다. 따라서 제출된 폼 데이터는 두 번째 인자가 됩니다.

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