表单和数据变更
表单使你能够在 Web 应用程序中创建和更新数据。Next.js 提供了一种使用 API Routes 处理表单提交和数据变更的强大方式。
值得注意的是:
- 我们将很快推荐渐进式采用 App Router 并使用服务器操作来处理表单提交和数据变更。服务器操作允许你定义异步服务器函数,可以直接从组件中调用,无需手动创建 API Route。
- API Routes 不指定 CORS 标头,这意味着默认情况下它们仅限同源。
- 由于 API Routes 在服务器上运行,我们可以通过环境变量使用敏感值(如 API 密钥)而不将它们暴露给客户端。这对于应用程序的安全性至关重要。
示例
仅服务器端表单
使用 Pages Router,你需要手动创建 API 端点来安全地在服务器上变更数据。
pages/api/submit.ts
TypeScript
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 Route:
pages/index.tsx
TypeScript
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>
)
}
表单验证
我们建议使用 required
和 type="email"
等 HTML 验证进行基本的客户端表单验证。
对于更高级的服务器端验证,你可以使用像 zod 这样的架构验证库来在变更数据之前验证表单字段:
pages/api/submit.ts
TypeScript
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
TypeScript
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>
)
}
显示加载状态
你可以使用 React 状态在服务器上提交表单时显示加载状态:
pages/index.tsx
TypeScript
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>
)
}
重定向
如果你希望在数据变更后将用户重定向到其他路由,可以redirect
到任何绝对或相对 URL:
pages/api/submit.ts
TypeScript
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
你可以在 API Route 中使用响应的 setHeader
方法设置 Cookie:
pages/api/cookie.ts
TypeScript
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 已设置。')
}
读取 Cookie
你可以在 API Route 中使用 cookies
请求帮助程序读取 Cookie:
pages/api/cookie.ts
TypeScript
import type { NextApiRequest, NextApiResponse } from 'next'
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
const auth = req.cookies.authorization
// ...
}
删除 Cookie
你可以在 API Route 中使用响应的 setHeader
方法删除 Cookie:
pages/api/cookie.ts
TypeScript
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 已删除。')
}