Формы и мутации данных

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

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

Вскоре мы будем рекомендовать постепенный переход на маршрутизатор приложения (App Router) и использование Server Actions для обработки отправки форм и мутаций данных. Server Actions позволяют определять асинхронные серверные функции, которые можно вызывать напрямую из компонентов без необходимости вручную создавать API Route.

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

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

Примеры

Формы только для сервера

В маршрутизаторе страниц (Pages Router) вам нужно вручную создавать 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({ id })
}

Затем вызовите 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">Отправить</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">Отправить</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}`)
}

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

Мы рекомендуем использовать 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)

  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    setIsLoading(true) // Установите загрузку в 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) // Установите загрузку в 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) // Установите загрузку в 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) // Установите загрузку в false при завершении запроса
    }
  }

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

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

Вы можете использовать состояние 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>
  )
}

Установка куки

Вы можете установить куки внутри API Route, используя метод setHeader для ответа:

import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  res.setHeader('Set-Cookie', 'username=lee; Path=/; HttpOnly')
  res.status(200).send('Куки были установлены.')
}

Чтение куки

Вы можете читать куки внутри API Route, используя хелпер запроса cookies:

import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const auth = req.cookies.authorization
  // ...
}

Удаление куки

Вы можете удалить куки внутри API Route, используя метод setHeader для ответа:

import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  res.setHeader('Set-Cookie', 'username=; Path=/; HttpOnly; Max-Age=0')
  res.status(200).send('Куки были удалены.')
}

Формы и мутации данных

On this page