2025년 9월 2일한국어

React의 실험적 API인 experimental_useFormStatus 훅을 사용하여 폼 상태 관리를 간소화하는 방법을 알아보세요. 실제 예제를 통해 구현, 이점, 고급 사용법을 배울 수 있습니다.

React experimental_useFormStatus 구현: 향상된 폼 상태 관리

끊임없이 발전하는 React 생태계는 개발자 경험과 애플리케이션 성능을 개선하기 위한 도구와 기술을 지속적으로 선보이고 있습니다. 그중 하나인 실험적 기능 experimental_useFormStatus 훅은 특히 서버 액션(server actions) 및 점진적 향상(progressive enhancement) 시나리오에서 폼 상태 관리를 단순화하도록 설계되었습니다. 이 종합 가이드에서는 experimental_useFormStatus 훅을 상세히 살펴보고, 효과적인 활용을 위한 실용적인 예제와 통찰력을 제공합니다.

`experimental_useFormStatus`란 무엇인가?

experimental_useFormStatus 훅은 React 팀이 도입한 실험적 API로, 특히 서버 액션을 사용할 때 폼 제출 상태를 더 간단하게 추적할 수 있는 방법을 제공합니다. 이 훅이 등장하기 전에는 폼의 여러 상태(유휴, 제출 중, 성공, 오류)를 관리하기 위해 복잡한 상태 관리 로직이 필요한 경우가 많았습니다. experimental_useFormStatus는 이러한 복잡성의 상당 부분을 추상화하여 폼 제출 상태를 모니터링하고 이에 반응하는 간단하고 효율적인 방법을 제공하는 것을 목표로 합니다.

주요 이점:

간소화된 상태 관리: 폼 제출 상태를 관리하는 데 필요한 상용구 코드를 줄여줍니다.
향상된 사용자 경험: 폼의 상태에 따라 더 반응적인 UI 업데이트를 가능하게 합니다.
개선된 코드 가독성: 폼 관련 코드를 더 쉽게 이해하고 유지보수할 수 있도록 만듭니다.
서버 액션과의 원활한 통합: 특히 React 서버 컴포넌트 및 서버 액션과 잘 작동하도록 설계되었습니다.

기본 구현

experimental_useFormStatus의 기본 구현을 설명하기 위해 간단한 문의 양식 예제를 살펴보겠습니다. 이 양식은 사용자의 이름, 이메일, 메시지를 수집한 다음 서버 액션을 사용하여 제출합니다.

사전 준비 사항

코드를 살펴보기 전에 다음 사항이 포함된 React 프로젝트가 설정되어 있는지 확인하세요.

실험적 API를 지원하는 React 버전 (필요한 버전은 React 공식 문서에서 확인하세요).
React 서버 컴포넌트 활성화 (일반적으로 Next.js나 Remix와 같은 프레임워크에서 사용됨).

예제: 간단한 문의 양식

다음은 기본적인 문의 양식 컴포넌트입니다.

```jsx // app/actions.js (서버 액션) 'use server' export async function submitContactForm(formData) { // 데이터베이스 호출 또는 API 요청 시뮬레이션 await new Promise(resolve => setTimeout(resolve, 2000)); const name = formData.get('name'); const email = formData.get('email'); const message = formData.get('message'); if (!name || !email || !message) { return { success: false, message: '모든 필드는 필수입니다.' }; } try { // 실제 API 호출 또는 데이터베이스 작업으로 대체 console.log('폼 제출됨:', { name, email, message }); return { success: true, message: '폼이 성공적으로 제출되었습니다!' }; } catch (error) { console.error('폼 제출 오류:', error); return { success: false, message: '폼 제출에 실패했습니다.' }; } } // app/components/ContactForm.jsx (클라이언트 컴포넌트) 'use client' import { experimental_useFormStatus as useFormStatus } from 'react' import { submitContactForm } from '../actions' function SubmitButton() { const { pending } = useFormStatus() return ( ) } export default function ContactForm() { return (

이름:

이메일:

메시지:

</div>
      <SubmitButton />
    </form>
  );
}
```

<ul>
  <li><b>서버 액션 (<code>app/actions.js</code>):</b> 이 파일은 서버 액션인 <code>submitContactForm</code> 함수를 정의합니다. 폼 제출의 비동기적 특성을 보여주기 위해 2초 지연으로 API 요청을 시뮬레이션합니다. 또한 기본적인 유효성 검사 및 오류 처리도 담당합니다.</li>
  <li><b>클라이언트 컴포넌트 (<code>app/components/ContactForm.jsx</code>):</b> 이 파일은 클라이언트 컴포넌트인 <code>ContactForm</code> 컴포넌트를 정의합니다. <code>experimental_useFormStatus</code> 훅과 <code>submitContactForm</code> 액션을 가져옵니다.</li>
  <li><b><code>useFormStatus</code> 사용법:</b> <code>SubmitButton</code> 컴포넌트 내부에서 <code>useFormStatus</code>가 호출됩니다. 이 훅은 폼의 제출 상태에 대한 정보를 제공합니다.</li>
  <li><b><code>pending</code> 속성:</b> <code>useFormStatus</code>가 반환하는 <code>pending</code> 속성은 폼이 현재 제출 중인지 여부를 나타냅니다. 이 속성은 제출 버튼을 비활성화하고 "제출 중..." 메시지를 표시하는 데 사용됩니다.</li>
  <li><b>폼 바인딩:</b> <code>form</code> 요소의 <code>action</code> 속성은 <code>submitContactForm</code> 서버 액션에 바인딩됩니다. 이는 폼이 제출될 때 React가 해당 서버 액션을 호출하도록 지시합니다.</li>
</ul>

<p><code>experimental_useFormStatus</code>는 제출 상태 추적을 단순화하지만, 성공 및 오류 상태는 명시적으로 처리해야 하는 경우가 많습니다. 서버 액션은 성공 또는 실패를 나타내는 데이터를 반환할 수 있으며, 이를 사용하여 UI를 적절하게 업데이트할 수 있습니다.</p>

```jsx
// app/components/ContactForm.jsx (수정됨)
'use client'

import { experimental_useFormStatus as useFormStatus } from 'react'
import { submitContactForm } from '../actions'
import { useState } from 'react';

function SubmitButton() {
  const { pending } = useFormStatus()

return (
    <button type="submit" disabled={pending}>
      {pending ? '제출 중...' : '제출'}
    </button>
  )
}

export default function ContactForm() {
  const [message, setMessage] = useState(null);

async function handleSubmit(formData) {
    const result = await submitContactForm(formData);
    setMessage(result);
  }

return (
    <div>
      <form action={handleSubmit}>
        <div>
          <label htmlFor="name">이름:</label>
          <input type="text" id="name" name="name" required />
        </div>
        <div>
          <label htmlFor="email">이메일:</label>
          <input type="email" id="email" name="email" required />
        </div>
        <div>
          <label htmlFor="message">메시지:</label>
          <textarea id="message" name="message" required />
        </div>
        <SubmitButton />
      </form>
      {message && (
        <p className={message.success ? 'success' : 'error'}>
          {message.message}
        </p>
      )}
    </div>
  );
}
```

<ul>
  <li><b>메시지 상태:</b> 서버 액션에서 반환된 결과를 저장하기 위해 <code>message</code> 상태 변수가 도입되었습니다.</li>
  <li><b>결과 처리:</b> 폼이 제출된 후, <code>handleSubmit</code> 함수는 서버 액션의 결과로 <code>message</code> 상태를 업데이트합니다.</li>
  <li><b>메시지 표시:</b> 컴포넌트는 결과의 <code>success</code> 속성에 따라 메시지를 표시하며, 성공 및 오류 상태에 대해 다른 CSS 클래스를 적용합니다.</li>
</ul>

<h3>점진적 향상 (Progressive Enhancement)</h3>

<p><code>experimental_useFormStatus</code>는 점진적 향상 시나리오에서 특히 유용합니다. 표준 HTML 폼을 React로 점진적으로 향상시키면, JavaScript가 실패하더라도 기본 기능을 유지하면서 더 나은 사용자 경험을 제공할 수 있습니다.</p>

<p>기본 HTML 폼으로 시작합니다:</p>

```html

<form action="/submit-contact" method="post">
  <div>
    <label for="name">이름:</label>
    <input type="text" id="name" name="name" required />
  </div>
  <div>
    <label for="email">이메일:</label>
    <input type="email" id="email" name="email" required />
  </div>
  <div>
    <label for="message">메시지:</label>
    <textarea id="message" name="message" required>

```

그런 다음 React와 experimental_useFormStatus를 사용하여 점진적으로 향상시킬 수 있습니다.

```jsx // app/components/EnhancedContactForm.jsx 'use client' import { experimental_useFormStatus as useFormStatus } from 'react' import { submitContactForm } from '../actions' import { useState } from 'react'; import { useFormState } from 'react-dom'; function SubmitButton() { const { pending } = useFormStatus() return ( ) } export default function EnhancedContactForm() { const [message, setMessage] = useState(null); const [state, formAction] = useFormState(submitContactForm, null); // 초기 상태에 의존하지 않는 경우 null을 사용 return (

이름:

이메일:

메시지:

</div>
        <SubmitButton />
		{state?.message && (
        <p className={state.success ? 'success' : 'error'}>
          {state.message}
        </p>
      )}
      </form>
    </div>
  );
}
```

<ul>
  <li><b>초기 HTML 폼:</b> <code>public/contact.html</code> 파일에는 JavaScript 없이도 작동하는 표준 HTML 폼이 포함되어 있습니다.</li>
  <li><b>점진적 향상:</b> <code>EnhancedContactForm</code> 컴포넌트는 HTML 폼을 점진적으로 향상시킵니다. JavaScript가 활성화되면 React가 제어하여 더 풍부한 사용자 경험을 제공합니다.</li>
  <li><b><code>useFormState</code> 훅:</b> 폼 상태를 관리하고 서버 액션을 폼에 바인딩하기 위해 <code>useFormState</code>를 사용합니다.</li>
	<li> <b><code>state</code>:</b> <code>useFormState</code>에서 반환된 <code>state</code>는 이제 서버 액션의 반환 값을 담고 있으며, 이를 통해 성공 또는 오류 메시지를 확인할 수 있습니다.</li>
</ul>

<ul>
  <li><b>현지화:</b> 폼 레이블, 메시지, 오류 메시지가 다른 언어로 현지화되었는지 확인하세요. i18next와 같은 도구가 번역 관리에 도움이 될 수 있습니다.</li>
  <li><b>날짜 및 숫자 형식:</b> 사용자의 로케일에 따라 날짜 및 숫자 형식을 처리하세요. <code>Intl</code>이나 <code>moment.js</code>(현재는 레거시로 간주됨)와 같은 라이브러리를 사용하여 날짜와 숫자를 올바르게 형식화하세요.</li>
  <li><b>주소 형식:</b> 국가마다 주소 형식이 다릅니다. 여러 주소 형식을 지원하는 라이브러리를 사용하거나 사용자의 위치에 따라 맞춤형 폼 필드를 만드는 것을 고려하세요.</li>
  <li><b>전화번호 유효성 검사:</b> 국제 표준에 따라 전화번호의 유효성을 검사하세요. <code>libphonenumber-js</code>와 같은 라이브러리가 도움이 될 수 있습니다.</li>
  <li><b>오른쪽에서 왼쪽(RTL) 지원:</b> 폼 레이아웃이 아랍어나 히브리어와 같은 RTL 언어를 지원하는지 확인하세요. 더 나은 RTL 지원을 위해 CSS 논리적 속성(예: <code>margin-left</code> 대신 <code>margin-inline-start</code>)을 사용하세요.</li>
  <li><b>접근성:</b> WCAG(웹 콘텐츠 접근성 가이드라인)를 준수하여 사용자의 위치에 관계없이 장애가 있는 사람들도 폼을 사용할 수 있도록 하세요.</li>
</ul>

```jsx
// i18n/locales/en.json
{
  "contactForm": {
    "nameLabel": "이름",
    "emailLabel": "이메일",
    "messageLabel": "메시지",
    "submitButton": "제출",
    "successMessage": "폼이 성공적으로 제출되었습니다!",
    "errorMessage": "폼 제출에 실패했습니다."
  }
}

// i18n/locales/fr.json
{
  "contactForm": {
    "nameLabel": "이름",
    "emailLabel": "이메일",
    "messageLabel": "메시지",
    "submitButton": "제출",
    "successMessage": "폼이 성공적으로 제출되었습니다!",
    "errorMessage": "폼 제출에 실패했습니다."
  }
}

// app/components/LocalizedContactForm.jsx
'use client'

import { useTranslation } from 'react-i18next';
import { experimental_useFormStatus as useFormStatus } from 'react'
import { submitContactForm } from '../actions'
import { useState } from 'react';

function SubmitButton() {
  const { pending } = useFormStatus()
  const { t } = useTranslation();

return (
    <button type="submit" disabled={pending}>
      {pending ? t('contactForm.submitButton', {ns: 'contactForm'}) : t('contactForm.submitButton', {ns: 'contactForm'})}
    </button>
  )
}

export default function LocalizedContactForm() {
  const { t } = useTranslation();
  const [message, setMessage] = useState(null);

async function handleSubmit(formData) {
    const result = await submitContactForm(formData);
    setMessage(result);
  }

return (
    <div>
      <form action={handleSubmit}>
        <div>
          <label htmlFor="name">{t('contactForm.nameLabel', {ns: 'contactForm'})}:</label>
          <input type="text" id="name" name="name" required />
        </div>
        <div>
          <label htmlFor="email">{t('contactForm.emailLabel', {ns: 'contactForm'})}:</label>
          <input type="email" id="email" name="email" required />
        </div>
        <div>
          <label htmlFor="message">{t('contactForm.messageLabel', {ns: 'contactForm'})}:</label>
          <textarea id="message" name="message" required />
        </div>
        <SubmitButton />
      </form>
      {message && (
        <p className={message.success ? 'success' : 'error'}>
          {message.message}
        </p>
      )}
    </div>
  );
}
```

<ul>
  <li><b>번역 파일:</b> 이 예제는 <code>react-i18next</code>를 사용하여 번역을 관리합니다. 별도의 JSON 파일에 다른 언어에 대한 번역이 포함되어 있습니다.</li>
  <li><b><code>useTranslation</code> 훅:</b> <code>useTranslation</code> 훅은 번역 함수(<code>t</code>)에 대한 접근을 제공하며, 이는 현지화된 문자열을 가져오는 데 사용됩니다.</li>
  <li><b>현지화된 레이블:</b> 폼 레이블과 버튼 텍스트는 <code>t</code> 함수를 사용하여 검색되므로 사용자가 선호하는 언어로 표시됩니다.</li>
</ul>

<p>장애가 있는 사용자를 포함한 모든 사용자가 폼에 접근할 수 있도록 하는 것이 중요합니다. 다음은 주요 접근성 고려 사항입니다.</p>

<ul>
  <li><b>시맨틱 HTML:</b> <code><label></code>, <code><input></code>, <code><textarea></code>, <code><button></code>과 같은 시맨틱 HTML 요소를 올바르게 사용하세요.</li>
  <li><b>레이블:</b> <code><label></code>의 <code>for</code> 속성과 폼 컨트롤의 <code>id</code> 속성을 사용하여 레이블을 폼 컨트롤과 연결하세요.</li>
  <li><b>ARIA 속성:</b> 보조 기술에 추가 정보를 제공하기 위해 ARIA 속성을 사용하세요. 예를 들어, <code>aria-describedby</code>를 사용하여 폼 컨트롤을 설명에 연결하세요.</li>
  <li><b>오류 처리:</b> 오류를 명확하게 표시하고 유용한 오류 메시지를 제공하세요. <code>aria-invalid</code>와 같은 ARIA 속성을 사용하여 유효하지 않은 폼 컨트롤을 표시하세요.</li>
  <li><b>키보드 내비게이션:</b> 사용자가 키보드를 사용하여 폼을 탐색할 수 있도록 하세요. 필요한 경우 <code>tabindex</code> 속성을 사용하여 포커스 순서를 제어하세요.</li>
  <li><b>색상 대비:</b> 텍스트와 배경색 간의 충분한 색상 대비를 확보하세요.</li>
  <li><b>폼 구조:</b> 명확하고 일관된 폼 구조를 사용하세요. <code><fieldset></code>과 <code><legend></code> 요소를 사용하여 관련된 폼 컨트롤을 그룹화하세요.</li>
</ul>

```jsx
// app/components/AccessibleContactForm.jsx
'use client'

import { experimental_useFormStatus as useFormStatus } from 'react'
import { submitContactForm } from '../actions'
import { useState } from 'react';

function SubmitButton() {
  const { pending } = useFormStatus()

return (
    <button type="submit" disabled={pending}>
      {pending ? '제출 중...' : '제출'}
    </button>
  )
}

export default function AccessibleContactForm() {
  const [message, setMessage] = useState(null);
  const [errors, setErrors] = useState({});

async function handleSubmit(formData) {
    // 기본적인 클라이언트 측 유효성 검사
    const newErrors = {};
    if (!formData.get('name')) {
      newErrors.name = '이름은 필수입니다.';
    }
    if (!formData.get('email')) {
      newErrors.email = '이메일은 필수입니다.';
    }
    if (!formData.get('message')) {
      newErrors.message = '메시지는 필수입니다.';
    }

if (Object.keys(newErrors).length > 0) {
      setErrors(newErrors);
      return;
    }

setErrors({}); // 이전 오류 지우기
    const result = await submitContactForm(formData);
    setMessage(result);
  }

return (
    <div>
      <form action={handleSubmit}>
        <div>
          <label htmlFor="name">이름:</label>
          <input
            type="text"
            id="name"
            name="name"
            aria-invalid={!!errors.name}
            aria-describedby="name-error"
            required
          />
          {errors.name && (
            <p id="name-error" className="error">
              {errors.name}
            </p>
          )}
        </div>
        <div>
          <label htmlFor="email">이메일:</label>
          <input
            type="email"
            id="email"
            name="email"
            aria-invalid={!!errors.email}
            aria-describedby="email-error"
            required
          />
          {errors.email && (
            <p id="email-error" className="error">
              {errors.email}
            </p>
          )}
        </div>
        <div>
          <label htmlFor="message">메시지:</label>
          <textarea
            id="message"
            name="message"
            aria-invalid={!!errors.message}
            aria-describedby="message-error"
            required
          />
          {errors.message && (
            <p id="message-error" className="error">
              {errors.message}
            </p>
          )}
        </div>
        <SubmitButton />
      </form>
      {message && (
        <p className={message.success ? 'success' : 'error'}>
          {message.message}
        </p>
      )}
    </div>
  );
}
```

<ul>
  <li><b>오류 상태:</b> 컴포넌트는 유효성 검사 오류를 추적하기 위해 <code>errors</code> 상태를 유지합니다.</li>
  <li><b>클라이언트 측 유효성 검사:</b> <code>handleSubmit</code> 함수는 폼을 제출하기 전에 기본적인 클라이언트 측 유효성 검사를 수행합니다.</li>
  <li><b>ARIA 속성:</b> 특정 폼 컨트롤에 오류가 있는 경우 <code>aria-invalid</code> 속성이 <code>true</code>로 설정됩니다. <code>aria-describedby</code> 속성은 폼 컨트롤을 오류 메시지에 연결합니다.</li>
  <li><b>오류 메시지:</b> 오류 메시지는 해당 폼 컨트롤 옆에 표시됩니다.</li>
</ul>

<ul>
  <li><b>실험적 상태:</b> 실험적 API이므로 <code>experimental_useFormStatus</code>는 향후 React 버전에서 변경되거나 제거될 수 있습니다. React의 공식 문서를 최신 상태로 유지하고 필요한 경우 코드를 수정할 준비를 하는 것이 중요합니다.</li>
  <li><b>제한된 범위:</b> 이 훅은 주로 제출 상태 추적에 중점을 두며 유효성 검사나 데이터 처리와 같은 포괄적인 폼 관리 기능을 제공하지는 않습니다. 이러한 측면을 위해서는 추가적인 로직을 구현해야 할 수 있습니다.</li>
  <li><b>서버 액션 의존성:</b> 이 훅은 서버 액션과 함께 작동하도록 설계되었으므로 모든 사용 사례에 적합하지 않을 수 있습니다. 서버 액션을 사용하지 않는 경우 폼 상태 관리를 위한 다른 솔루션을 찾아야 할 수 있습니다.</li>
</ul>

<p><code>experimental_useFormStatus</code> 훅은 React에서 폼 제출 상태를 관리하는 데 있어, 특히 서버 액션 및 점진적 향상과 함께 작업할 때 상당한 개선을 제공합니다. 상태 관리를 단순화하고 명확하고 간결한 API를 제공함으로써 개발자 경험과 사용자 경험을 모두 향상시킵니다. 그러나 실험적인 특성을 고려할 때, 향후 React 버전의 업데이트 및 잠재적 변경 사항에 대한 정보를 계속 확인하는 것이 중요합니다. 이 훅의 이점, 한계, 모범 사례를 이해함으로써 React 애플리케이션에서 더 강력하고 사용자 친화적인 폼을 구축하기 위해 <code>experimental_useFormStatus</code>를 효과적으로 활용할 수 있습니다. 전 세계 사용자를 위한 포용적인 폼을 만들기 위해 국제화 및 접근성 모범 사례를 고려하는 것을 잊지 마세요.</p></div><footer class="mt-12 pt-8 border-t border-gray-200"><h3 class="text-sm font-semibold text-gray-900 mb-3 dark:text-white/90">Tags:</h3><div class="flex flex-wrap gap-2"><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">React</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">useFormStatus</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">폼 상태</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">React 폼</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">실험적 API</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">React 훅</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">폼 제출</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">비동기 폼</span><span class="inline-block bg-gray-100 text-gray-800 px-3 py-1 rounded-full text-sm hover:bg-gray-200 transition-colors dark:bg-neutral-800 dark:text-white dark:hover:bg-neutral-700">점진적 향상</span></div></footer></article></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:2","P:2")</script><script>$RC("B:1","S:1")</script></body></html>

React experimental_useFormStatus 구현: 향상된 폼 상태 관리

experimental_useFormStatus란 무엇인가?

기본 구현

사전 준비 사항

예제: 간단한 문의 양식

`experimental_useFormStatus`란 무엇인가?