NNext.js 中文网 GitHub

如何使用 API Routes 创建表单

了解如何使用 Next.js 处理表单提交和数据变更。

表单使你能够在 Web 应用中创建和更新数据。Next.js 提供了一种强大的方式,使用 API Routes 来处理数据变更。本指南将带你了解如何在服务端处理表单提交。

服务端表单#

要在服务端处理表单提交,需要创建一个安全地变更数据的 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 })
}
pages/api/submit.js
export default function handler(req, res) {
  const data = req.body
  // 调用你的数据库等
  // const id = await createItem(data)
  // ...
  res.status(200).json({ data })
}

然后,使用事件处理器从客户端调用该 API Route:

pages/index.tsx
import { SubmitEvent } from 'react'

export default function Page() {
  async function onSubmit(event: SubmitEvent<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>
  )
}
pages/index.jsx
export default function Page() {
  async function onSubmit(event) {
    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>
  )
}

小知识:

  • API Routes 未指定 CORS 头,这意味着它们默认仅限同源。
  • 由于 API Routes 在服务端运行,我们可以通过环境变量使用敏感值(如 API 密钥),而不会将它们暴露给客户端。这对应用的安全性至关重要。

表单验证#

我们建议使用像 required 和 type="email" 这样的 HTML 验证来进行基本的客户端表单验证。

对于更高级的服务端验证,你可以使用像 Zod 或 Valibot 这样的 schema 验证库,在变更数据之前验证表单字段:

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)
  // ...
}
pages/api/submit.js
import { z } from 'zod'

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

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

错误处理#

当表单提交失败时,你可以使用 React state 来显示错误消息:

pages/index.tsx
import React, { useState, SubmitEvent } from 'react'

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

  async function onSubmit(event: SubmitEvent<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('Failed to submit the data. Please try again.')
      }

      // 根据需要处理响应
      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" required />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Loading...' : 'Submit'}
        </button>
      </form>
    </div>
  )
}
pages/index.jsx
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('Failed to submit the data. Please try again.')
      }

      // 根据需要处理响应
      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" required />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Loading...' : 'Submit'}
        </button>
      </form>
    </div>
  )
}

显示加载状态#

当表单正在提交到服务端时,你可以使用 React state 来显示加载状态:

pages/index.tsx
import React, { useState, SubmitEvent } from 'react'

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

  async function onSubmit(event: SubmitEvent<HTMLFormElement>) {
    event.preventDefault()
    setIsLoading(true) // 请求开始时将 loading 设为 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) // 请求完成时将 loading 设为 false
    }
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Loading...' : 'Submit'}
      </button>
    </form>
  )
}
pages/index.jsx
import React, { useState } from 'react'

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

  async function onSubmit(event) {
    event.preventDefault()
    setIsLoading(true) // 请求开始时将 loading 设为 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) // 请求完成时将 loading 设为 false
    }
  }

  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}`)
}
pages/api/submit.js
export default async function handler(req, res) {
  const id = await addPost()
  res.redirect(307, `/post/${id}`)
}
Next.js 中文网