如何使用 Server Actions 创建表单
了解如何使用 React Server Actions 在 Next.js 中创建表单。
React Server Actions 是在服务端执行的 Server Functions。它们可以在 Server 和 Client Components 中调用,以处理表单提交。本指南将带你了解如何在 Next.js 中使用 Server Actions 创建表单。关于表单之外的 Server Action 行为(单次往返响应、顺序分发、安全性、部署),请参阅 Server Actions 与数据变更。
[!WARNING] 始终在每个 Server Action 内部验证身份验证与授权,即使表单仅在已通过身份验证的页面上渲染。有关更多详细信息,请参阅数据安全指南。
工作原理#
React 扩展了 HTML <form> 元素,允许通过 action 属性调用 Server Actions。
在表单中使用时,该函数会自动接收 FormData 对象。然后你可以使用原生 FormData 方法提取数据:
import { auth } from '@/lib/auth'
export default function Page() {
async function createInvoice(formData: FormData) {
'use server'
const session = await auth()
if (!session?.user) {
throw new Error('Unauthorized')
}
const rawFormData = {
customerId: formData.get('customerId'),
amount: formData.get('amount'),
status: formData.get('status'),
}
// 变更数据
// 重新验证缓存
}
return <form action={createInvoice}>...</form>
}import { auth } from '@/lib/auth'
export default function Page() {
async function createInvoice(formData) {
'use server'
const session = await auth()
if (!session?.user) {
throw new Error('Unauthorized')
}
const rawFormData = {
customerId: formData.get('customerId'),
amount: formData.get('amount'),
status: formData.get('status'),
}
// 变更数据
// 重新验证缓存
}
return <form action={createInvoice}>...</form>
}小知识: 处理包含多个字段的表单时,请使用 JavaScript 的
Object.fromEntries()。例如:const rawFormData = Object.fromEntries(formData)。请注意,该对象将包含以$ACTION_为前缀的额外属性。
传递额外参数#
在表单字段之外,你可以使用 JavaScript 的 bind 方法向 Server Function 传递额外参数。例如,将 userId 参数传递给 updateUser Server Function:
'use client'
import { updateUser } from './actions'
export function UserProfile({ userId }: { userId: string }) {
const updateUserWithId = updateUser.bind(null, userId)
return (
<form action={updateUserWithId}>
<input type="text" name="name" />
<button type="submit">Update User Name</button>
</form>
)
}'use client'
import { updateUser } from './actions'
export function UserProfile({ userId }) {
const updateUserWithId = updateUser.bind(null, userId)
return (
<form action={updateUserWithId}>
<input type="text" name="name" />
<button type="submit">Update User Name</button>
</form>
)
}Server Function 将接收 userId 作为额外参数:
'use server'
export async function updateUser(userId: string, formData: FormData) {}'use server'
export async function updateUser(userId, formData) {}小知识:
- 另一种方法是将参数作为表单中的隐藏输入字段传递(例如
<input type="hidden" name="userId" value={userId} />)。但是,该值将成为渲染后 HTML 的一部分,并且不会被编码。bind在 Server 和 Client Components 中都可用,并支持渐进增强。
表单验证#
表单可以在客户端或服务端进行验证。
'use server'
import { z } from 'zod'
const schema = z.object({
email: z.string({
invalid_type_error: 'Invalid Email',
}),
})
export default async function createUser(formData: FormData) {
const validatedFields = schema.safeParse({
email: formData.get('email'),
})
// 如果表单数据无效则提前返回
if (!validatedFields.success) {
return {
errors: validatedFields.error.flatten().fieldErrors,
}
}
// 变更数据
}'use server'
import { z } from 'zod'
const schema = z.object({
email: z.string({
invalid_type_error: 'Invalid Email',
}),
})
export default async function createUser(formData) {
const validatedFields = schema.safeParse({
email: formData.get('email'),
})
// 如果表单数据无效则提前返回
if (!validatedFields.success) {
return {
errors: validatedFields.error.flatten().fieldErrors,
}
}
// 变更数据
}验证错误#
要显示验证错误或消息,请将定义 <form> 的组件转换为 Client Component,并使用 React 的 useActionState。
使用 useActionState 时,Server 函数的签名将更改为接收一个新的 prevState 或 initialState 参数作为其第一个参数。
'use server'
import { z } from 'zod'
export async function createUser(initialState: any, formData: FormData) {
const validatedFields = schema.safeParse({
email: formData.get('email'),
})
// ...
}'use server'
import { z } from 'zod'
// ...
export async function createUser(initialState, formData) {
const validatedFields = schema.safeParse({
email: formData.get('email'),
})
// ...
}然后你可以根据 state 对象有条件地渲染错误消息。
'use client'
import { useActionState } from 'react'
import { createUser } from '@/app/actions'
const initialState = {
message: '',
}
export function Signup() {
const [state, formAction, pending] = useActionState(createUser, initialState)
return (
<form action={formAction}>
<label htmlFor="email">Email</label>
<input type="text" id="email" name="email" required />
<p aria-live="polite">{state?.message}</p>
<button disabled={pending}>Sign up</button>
</form>
)
}'use client'
import { useActionState } from 'react'
import { createUser } from '@/app/actions'
const initialState = {
message: '',
}
export function Signup() {
const [state, formAction, pending] = useActionState(createUser, initialState)
return (
<form action={formAction}>
<label htmlFor="email">Email</label>
<input type="text" id="email" name="email" required />
<p aria-live="polite">{state?.message}</p>
<button disabled={pending}>Sign up</button>
</form>
)
}待处理状态#
useActionState Hook 暴露了一个 pending 布尔值,可用于在 action 执行期间显示加载指示器或禁用提交按钮。
'use client'
import { useActionState } from 'react'
import { createUser } from '@/app/actions'
export function Signup() {
const [state, formAction, pending] = useActionState(createUser, initialState)
return (
<form action={formAction}>
<button disabled={pending}>Sign up</button>
</form>
)
}'use client'
import { useActionState } from 'react'
import { createUser } from '@/app/actions'
export function Signup() {
const [state, formAction, pending] = useActionState(createUser, initialState)
return (
<form action={formAction}>
<button disabled={pending}>Sign up</button>
</form>
)
}或者,你可以使用 useFormStatus Hook 在 action 执行期间显示加载指示器。使用此 Hook 时,你需要创建一个单独的组件来渲染加载指示器。例如,在 action 待处理时禁用按钮:
'use client'
import { useFormStatus } from 'react-dom'
export function SubmitButton() {
const { pending } = useFormStatus()
return (
<button disabled={pending} type="submit">
Sign Up
</button>
)
}'use client'
import { useFormStatus } from 'react-dom'
export function SubmitButton() {
const { pending } = useFormStatus()
return (
<button disabled={pending} type="submit">
Sign Up
</button>
)
}然后你可以将 SubmitButton 组件嵌套在表单中:
import { SubmitButton } from './button'
import { createUser } from '@/app/actions'
export function Signup() {
return (
<form action={createUser}>
<SubmitButton />
</form>
)
}import { SubmitButton } from './button'
import { createUser } from '@/app/actions'
export function Signup() {
return (
<form action={createUser}>
<SubmitButton />
</form>
)
}小知识: 在 React 19 中,
useFormStatus在返回的对象上包含额外的键,如 data、method 和 action。如果你没有使用 React 19,则只有pending键可用。小知识:启用 实验性
useOffline配置后,因网络中断而被打断的 Server Action 会保持待处理状态,并在网络恢复时完成,因此用户不会丢失其提交内容。
乐观更新#
你可以使用 React 的 useOptimistic Hook 在 Server Function 执行完成之前乐观地更新 UI,而无需等待响应:
'use client'
import { useOptimistic } from 'react'
import { send } from './actions'
type Message = {
message: string
}
export function Thread({ messages }: { messages: Message[] }) {
const [optimisticMessages, addOptimisticMessage] = useOptimistic<
Message[],
string
>(messages, (state, newMessage) => [...state, { message: newMessage }])
const formAction = async (formData: FormData) => {
const message = formData.get('message') as string
addOptimisticMessage(message)
await send(message)
}
return (
<div>
{optimisticMessages.map((m, i) => (
<div key={i}>{m.message}</div>
))}
<form action={formAction}>
<input type="text" name="message" />
<button type="submit">Send</button>
</form>
</div>
)
}'use client'
import { useOptimistic } from 'react'
import { send } from './actions'
export function Thread({ messages }) {
const [optimisticMessages, addOptimisticMessage] = useOptimistic(
messages,
(state, newMessage) => [...state, { message: newMessage }]
)
const formAction = async (formData) => {
const message = formData.get('message')
addOptimisticMessage(message)
await send(message)
}
return (
<div>
{optimisticMessages.map((m) => (
<div>{m.message}</div>
))}
<form action={formAction}>
<input type="text" name="message" />
<button type="submit">Send</button>
</form>
</div>
)
}嵌套的表单元素#
你可以在嵌套在 <form> 内部的元素中调用 Server Actions,例如 <button>、<input type="submit"> 和 <input type="image">。这些元素接受 formAction prop 或事件处理器。
这在你想要在一个表单中调用多个 Server Actions 的情况下很有用。例如,除了发布文章之外,你还可以创建一个专门的 <button> 元素用于保存文章草稿。有关更多信息,请参阅 React <form> 文档。
以编程方式提交表单#
你可以使用 requestSubmit() 方法以编程方式触发表单提交。例如,当用户使用 ⌘ + Enter 键盘快捷键提交表单时,你可以监听 onKeyDown 事件:
'use client'
export function Entry() {
const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
if (
(e.ctrlKey || e.metaKey) &&
(e.key === 'Enter' || e.key === 'NumpadEnter')
) {
e.preventDefault()
e.currentTarget.form?.requestSubmit()
}
}
return (
<div>
<textarea name="entry" rows={20} required onKeyDown={handleKeyDown} />
</div>
)
}'use client'
export function Entry() {
const handleKeyDown = (e) => {
if (
(e.ctrlKey || e.metaKey) &&
(e.key === 'Enter' || e.key === 'NumpadEnter')
) {
e.preventDefault()
e.currentTarget.form?.requestSubmit()
}
}
return (
<div>
<textarea name="entry" rows={20} required onKeyDown={handleKeyDown} />
</div>
)
}这将触发最近的 <form> 祖先元素的提交,从而调用 Server Function。