Создание форм с использованием API Routes

Формы позволяют создавать и обновлять данные в веб-приложениях. Next.js предоставляет мощный способ обработки мутаций данных с использованием API Routes. Это руководство покажет вам, как обрабатывать отправку форм на сервере.

Серверные формы

Для обработки отправки форм на сервере создайте API-эндпоинт для безопасного изменения данных.

import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const data = req.body
  const id = await createItem(data)
  res.status(200).json({ id })
}

export default function handler(req, res) {
  const data = req.body
  // вызов вашей базы данных и т.д.
  // const id = await createItem(data)
  // ...
  res.status(200).json({ data })
}

Затем вызовите API Route из клиента с обработчиком событий:

import { FormEvent } from 'react'

export default function Page() {
  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()

    const formData = new FormData(event.currentTarget)
    const response = await fetch('/api/submit', {
      method: 'POST',
      body: formData,
    })

    // Обработка ответа при необходимости
    const data = await response.json()
    // ...
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit">Submit</button>
    </form>
  )
}

export default function Page() {
  async function onSubmit(event) {
    event.preventDefault()

    const formData = new FormData(event.target)
    const response = await fetch('/api/submit', {
      method: 'POST',
      body: formData,
    })

    // Обработка ответа при необходимости
    const data = await response.json()
    // ...
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit">Submit</button>
    </form>
  )
}

Полезно знать:

API Routes не указывают заголовки CORS, что означает, что по умолчанию они работают только в рамках одного источника.

Поскольку API Routes выполняются на сервере, мы можем использовать конфиденциальные значения (например, API-ключи) через Переменные окружения, не раскрывая их клиенту. Это критически важно для безопасности вашего приложения.

Валидация форм

Мы рекомендуем использовать HTML-валидацию, такую как required и type="email", для базовой клиентской валидации форм.

Для более сложной серверной валидации вы можете использовать библиотеку валидации схем, такую как zod, чтобы проверить поля формы перед изменением данных:

import type { NextApiRequest, NextApiResponse } from 'next'
import { z } from 'zod'

const schema = z.object({
  // ...
})

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const parsed = schema.parse(req.body)
  // ...
}

import { z } from 'zod'

const schema = z.object({
  // ...
})

export default async function handler(req, res) {
  const parsed = schema.parse(req.body)
  // ...
}

Обработка ошибок

Вы можете использовать состояние React для отображения сообщения об ошибке, если отправка формы не удалась:

import React, { useState, FormEvent } from 'react'

export default function Page() {
  const [isLoading, setIsLoading] = useState<boolean>(false)
  const [error, setError] = useState<string | null>(null)

  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    setIsLoading(true)
    setError(null) // Очистка предыдущих ошибок при новом запросе

    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })

      if (!response.ok) {
        throw new Error('Не удалось отправить данные. Пожалуйста, попробуйте снова.')
      }

      // Обработка ответа при необходимости
      const data = await response.json()
      // ...
    } catch (error) {
      // Захват сообщения об ошибке для отображения пользователю
      setError(error.message)
      console.error(error)
    } finally {
      setIsLoading(false)
    }
  }

  return (
    <div>
      {error && <div style={{ color: 'red' }}>{error}</div>}
      <form onSubmit={onSubmit}>
        <input type="text" name="name" />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Загрузка...' : 'Отправить'}
        </button>
      </form>
    </div>
  )
}

import React, { useState } from 'react'

export default function Page() {
  const [isLoading, setIsLoading] = useState(false)
  const [error, setError] = useState(null)

  async function onSubmit(event) {
    event.preventDefault()
    setIsLoading(true)
    setError(null) // Очистка предыдущих ошибок при новом запросе

    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })

      if (!response.ok) {
        throw new Error('Не удалось отправить данные. Пожалуйста, попробуйте снова.')
      }

      // Обработка ответа при необходимости
      const data = await response.json()
      // ...
    } catch (error) {
      // Захват сообщения об ошибке для отображения пользователю
      setError(error.message)
      console.error(error)
    } finally {
      setIsLoading(false)
    }
  }

  return (
    <div>
      {error && <div style={{ color: 'red' }}>{error}</div>}
      <form onSubmit={onSubmit}>
        <input type="text" name="name" />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Загрузка...' : 'Отправить'}
        </button>
      </form>
    </div>
  )
}

Отображение состояния загрузки

Вы можете использовать состояние React для отображения состояния загрузки, когда форма отправляется на сервер:

import React, { useState, FormEvent } from 'react'

export default function Page() {
  const [isLoading, setIsLoading] = useState<boolean>(false)

  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    setIsLoading(true) // Установка состояния загрузки при начале запроса

    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })

      // Обработка ответа при необходимости
      const data = await response.json()
      // ...
    } catch (error) {
      // Обработка ошибки при необходимости
      console.error(error)
    } finally {
      setIsLoading(false) // Сброс состояния загрузки при завершении запроса
    }
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Загрузка...' : 'Отправить'}
      </button>
    </form>
  )
}

import React, { useState } from 'react'

export default function Page() {
  const [isLoading, setIsLoading] = useState(false)

  async function onSubmit(event) {
    event.preventDefault()
    setIsLoading(true) // Установка состояния загрузки при начале запроса

    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })

      // Обработка ответа при необходимости
      const data = await response.json()
      // ...
    } catch (error) {
      // Обработка ошибки при необходимости
      console.error(error)
    } finally {
      setIsLoading(false) // Сброс состояния загрузки при завершении запроса
    }
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Загрузка...' : 'Отправить'}
      </button>
    </form>
  )
}

Перенаправление

Если вы хотите перенаправить пользователя на другой маршрут после мутации, вы можете использовать redirect на любой абсолютный или относительный URL:

import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const id = await addPost()
  res.redirect(307, `/post/${id}`)
}

export default async function handler(req, res) {
  const id = await addPost()
  res.redirect(307, `/post/${id}`)
}