Laravel Inertia - Forms

폼

폼 제출

전통적인 HTML 폼 제출 방식도 Inertia에서 사용할 수 있지만, 이는 전체 페이지를 새로고침하므로 권장되지 않습니다. 대신 폼 제출을 가로채고 Inertia를 사용하여 요청을 하는 것이 좋습니다.

<script setup>
import { reactive } from 'vue'
import { router } from '@inertiajs/vue3'

const form = reactive({
  first_name: null,
  last_name: null,
  email: null,
})

function submit() {
  router.post('/users', form)
}
</script>

<template>
  <form @submit.prevent="submit">
    <label for="first_name">First name:</label>
    <input id="first_name" v-model="form.first_name" />
    <label for="last_name">Last name:</label>
    <input id="last_name" v-model="form.last_name" />
    <label for="email">Email:</label>
    <input id="email" v-model="form.email" />
    <button type="submit">Submit</button>
  </form>
</template>

위 예제에서 볼 수 있듯이, Inertia를 사용할 때 클라이언트 측에서 폼 응답을 검사할 필요가 일반적으로 없습니다. 대신 서버 측 라우트/컨트롤러는 일반적으로 리다이렉트 응답을 발행합니다. 이 방식을 사용하면 Inertia 폼 제출을 처리하는 것이 전통적인 HTML 폼 제출을 처리하는 것과 매우 유사하게 느껴집니다.

class UsersController extends Controller
{
    public function index()
    {
        return Inertia::render('Users/Index', [
            'users' => User::all(),
        ]);
    }

    public function store(Request $request)
    {
        User::create($request->validate([
            'first_name' => ['required', 'max:50'],
            'last_name' => ['required', 'max:50'],
            'email' => ['required', 'max:50', 'email'],
        ]));

        return to_route('users.index');
    }
}

서버 측 유효성 검증

Inertia에서 서버 측 유효성 검증 오류를 처리하는 방법은 수동 XHR/fetch 요청에서 오류를 처리하는 방법과 약간 다릅니다. XHR/fetch 요청을 할 때는 일반적으로 응답에서 422 상태 코드를 검사하고 폼의 오류 상태를 수동으로 업데이트합니다.

그러나 Inertia를 사용할 때는 서버에서 422 응답을 반환하지 않습니다. 대신 위의 예제에서 보았듯이 라우트/컨트롤러는 일반적으로 리다이렉트 응답을 반환합니다. Inertia에서 유효성 검증 오류를 처리하고 표시하는 방법에 대한 전체적인 논의는 유효성 검증 문서를 참조하세요.

폼 도우미

폼 작업은 매우 흔하기 때문에, Inertia는 일반적인 폼 제출을 처리하는 데 필요한 보일러플레이트 코드의 양을 줄이는 데 도움이 되는 폼 도우미를 포함합니다.

<script setup>
import { useForm } from '@inertiajs/vue3'

const form = useForm({
  email: null,
  password: null,
  remember: false,
})
</script>

<template>
  <form @submit.prevent="form.post('/login')">
    <!-- email -->
    <input type="text" v-model="form.email">
    <div v-if="form.errors.email">{{ form.errors.email }}</div>
    <!-- password -->
    <input type="password" v-model="form.password">
    <div v-if="form.errors.password">{{ form.errors.password }}</div>
    <!-- remember me -->
    <input type="checkbox" v-model="form.remember"> Remember Me
    <!-- submit -->
    <button type="submit" :disabled="form.processing">Login</button>
  </form>
</template>

폼을 제출할 때는 get, post, put, patch, delete 메소드를 사용할 수 있습니다.

form.submit(method, url, options)
form.get(url, options)
form.post(url, options)
form.put(url, options)
form.patch(url, options)
form.delete(url, options)

제출 메소드는 preserveState, preserveScroll 및 이벤트 콜백과 같은 전형적인 방문 옵션을 모두 지원합니다. 예를 들어, onSuccess 콜백을 사용하여 성공적인 폼 제출 후 입력을 원래 상태로 재설정하는 작업을 수행할 수 있습니다.

form.post('/profile', {
  preserveScroll: true,
  onSuccess: () => form.reset('password'),
})

서버로 보내기 전에 폼 데이터를 수정해야 하는 경우, transform() 메소드를 통해 할 수 있습니다.

form
  .transform((data) => ({
    ...data,
    remember: data.remember ? 'on' : '',
  }))
  .post('/login')

폼이 현재 제출 중인지 추적하기 위해 processing 속성을 사용할 수 있습니다. 이는 폼 제출 버튼을 비활성화하여 중복 폼 제출을 방지하는 데 유용합니다.

<button type="submit" :disabled="form.processing">Submit</button>

폼이 파일을 업로드하는 경우, progress 속성을 통해 현재 진행 상황 이벤트를 사용할 수 있어, 업로드 진행 상황을 쉽게 표시할 수 있습니다.

<progress v-if="form.progress" :value="form.progress.percentage" max="100">
  {{ form.progress.percentage }}%
</progress>

폼 유효성 검증 오류가 있는 경우, errors 속성을 통해 사용할 수 있습니다. Laravel 기반 Inertia 애플리케이션을 구축할 때는 애플리케이션이 ValidationException의 인스턴스를 발생시키는 경우(예: $request->validate() 사용 시) 폼 오류가 자동으로 채워집니다.

<div v-if="form.errors.email">{{ form.errors.email }}</div>

폼 유효성 검증 및 오류에 대한 보다 철저한 논의는 유효성 검증 문서를 참조하세요.

폼에 오류가 있는지 확인하려면 hasErrors 속성을 사용할 수 있습니다. 폼 오류를 지우려면 clearErrors() 메소드를 사용하세요.

// 모든 오류 지우기...
form.clearErrors()

// 특정 필드의 오류 지우기...
form.clearErrors('field', 'anotherfield')

클라이언트 측 입력 유효성 검증 라이브러리를 사용하거나 수동으로 클라이언트 측 유효성 검증을 수행하는 경우, setErrors() 메소드를 사용하여 폼에 자체 오류를 설정할 수 있습니다.

// 단일 오류 설정...
form.setError('field', 'Your error message.');

// 한 번에 여러 오류 설정...
form.setError({
  foo: 'Your error message for the foo field.',
  bar: 'Some other error for the bar field.'
});

실제 폼 제출과 달리, 폼 인스턴스에 수동으로 오류를 설정하면 페이지의 props는 변경되지 않습니다.

폼이 성공적으로 제출되었을 때 wasSuccessful 속성은 true가 됩니다. 또한 폼은 recentlySuccessful 속성을 가지고 있는데, 이는 성공적인 폼 제출 후 2초 동안 true로 설정됩니다. 이 속성은 임시 성공 메시지를 표시하는 데 사용될 수 있습니다.

폼의 값을 기본값으로 다시 설정하려면 reset() 메소드를 사용하세요.

// 폼 초기화...
form.reset()

// 특정 필드 초기화...
form.reset('field', 'anotherfield')

폼의 기본값이 오래되었다면, defaults() 메소드를 사용하여 업데이트할 수 있습니다. 그러면 reset() 메소드를 호출할 때 폼이 올바른 값으로 다시 설정됩니다.

// 폼의 현재 값으로 새 기본값 설정...
form.defaults()

// 단일 필드의 기본값 업데이트...
form.defaults('email', 'updated-default@example.com')

// 여러 필드의 기본값 업데이트...
form.defaults({
  name: 'Updated Example',
  email: 'updated-default@example.com',
})

폼에 변경 사항이 있는지 확인하려면 isDirty 속성을 사용할 수 있습니다.

<div v-if="form.isDirty">There are unsaved form changes.</div>

폼 제출을 취소하려면 cancel() 메소드를 사용하세요.

form.cancel()

Inertia에 폼 데이터와 오류를 【34†기록 상태(history state)】에 저장하도록 지시하려면, 폼 인스턴스를 생성할 때 고유한 폼 키를 첫 번째 인자로 제공하세요.

import { useForm } from '@inertiajs/vue3'

const form = useForm('CreateUser', data)
const form = useForm(`EditUser:${user.id}`, data)

파일 업로드

파일을 포함하는 요청이나 폼 제출을 할 때, Inertia는 자동으로 요청 데이터를 FormData 객체로 변환합니다.

파일 업로드에 대한 보다 철저한 논의는 파일 업로드 문서를 참조하세요.

XHR/fetch 제출

Inertia를 사용하여 폼을 제출하는 것은 대부분의 상황에서 잘 작동하지만, 폼 제출에 대해 더 많은 제어가 필요한 경우 원하는 라이브러리를 사용하여 일반 XHR 또는 fetch 요청을 수행할 수 있습니다.