表单与数据变更

表单使您能够在网页应用中创建和更新数据。Next.js 通过 API 路由 (API Routes) 提供了一种强大的方式来处理表单提交和数据变更。

须知：

我们即将推荐渐进式采用应用路由 (App Router) 并使用服务端操作 (Server Actions) 来处理表单提交和数据变更。服务端操作允许您定义异步服务端函数，这些函数可以直接从组件中调用，无需手动创建 API 路由。

API 路由默认不指定 CORS 头信息，这意味着它们默认仅支持同源请求。

由于 API 路由在服务端运行，我们可以通过环境变量 (Environment Variables) 使用敏感值（如 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 路由：

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

表单验证

我们推荐使用 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) // 请求开始时设置加载状态为 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>
  )
}

重定向

如果您想在数据变更后将用户重定向到其他路由，可以使用 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}`)
}

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

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 已设置。')
}

您可以在 API 路由中使用 cookies 请求辅助方法来读取 Cookie：

import type { NextApiRequest, NextApiResponse } from 'next'

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

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

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 已删除。')
}

On this page