表单和 Mutation

表单使您能够在 Web 应用程序中创建和更新数据。Next.js 提供了一种强大的方法来处理表单提交和使用**API 路由**进行数据变异。

需要了解

我们很快就会建议逐步采用 App Router 并使用服务器操作来处理表单提交和数据变异。服务器操作允许您定义可以直接从组件中调用的异步服务器函数，而无需手动创建 API 路由。

API 路由不指定 CORS 标头，这意味着它们默认情况下仅限同源。

由于 API 路由在服务器上运行，因此我们能够通过环境变量使用敏感值（如 API 密钥），而无需将其暴露给客户端。这对应用程序的安全至关重要。

示例

仅服务器端表单

使用 Pages Router，您需要手动创建 API 端点以安全地处理服务器上的数据变异。

pages/api/submit.ts

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

然后，使用事件处理程序从客户端调用 API 路由

pages/index.tsx

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,
    })
 
    // Handle response if necessary
    const data = await response.json()
    // ...
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit">Submit</button>
    </form>
  )
}

表单验证

我们建议使用 HTML 验证（如required和type="email"）进行基本的客户端表单验证。

对于更高级的服务器端验证，您可以使用像zod这样的模式验证库在变异数据之前验证表单字段

pages/api/submit.ts

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

错误处理

您可以使用 React 状态在表单提交失败时显示错误消息

pages/index.tsx

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) // Clear previous errors when a new request starts
 
    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })
 
      if (!response.ok) {
        throw new Error('Failed to submit the data. Please try again.')
      }
 
      // Handle response if necessary
      const data = await response.json()
      // ...
    } catch (error) {
      // Capture the error message to display to the user
      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 ? 'Loading...' : 'Submit'}
        </button>
      </form>
    </div>
  )
}

显示加载状态

您可以使用 React 状态在表单在服务器上提交时显示加载状态

pages/index.tsx

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) // Set loading to true when the request starts
 
    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })
 
      // Handle response if necessary
      const data = await response.json()
      // ...
    } catch (error) {
      // Handle error if necessary
      console.error(error)
    } finally {
      setIsLoading(false) // Set loading to false when the request completes
    }
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Loading...' : 'Submit'}
      </button>
    </form>
  )
}

重定向

如果您想在变异后将用户重定向到其他路由，您可以redirect到任何绝对或相对 URL

pages/api/submit.ts

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

设置 Cookie

您可以使用响应中的 setHeader 方法在 API 路由中设置 Cookie

pages/api/cookie.ts

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('Cookie has been set.')
}

读取 Cookie

您可以使用 cookies 请求助手在 API 路由中读取 Cookie

pages/api/cookie.ts

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

删除 Cookie

您可以使用响应中的 setHeader 方法在 API 路由中删除 Cookie

pages/api/cookie.ts

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('Cookie has been deleted.')
}