如何使用服务器 Action 创建表单

React 服务器 Action 是在服务器上执行的服务器函数。它们可以在服务器和客户端组件中调用，以处理表单提交。本指南将引导您了解如何在 Next.js 中使用服务器 Action 创建表单。

工作原理

React 扩展了 HTML <form> 元素，允许通过 action 属性调用服务器 Action。

在表单中使用时，该函数会自动接收 FormData 对象。然后，您可以使用原生 FormData 方法提取数据。

export default function Page() {
  async function createInvoice(formData: FormData) {
    'use server'
 
    const rawFormData = {
      customerId: formData.get('customerId'),
      amount: formData.get('amount'),
      status: formData.get('status'),
    }
 
    // mutate data
    // revalidate the cache
  }
 
  return <form action={createInvoice}>...</form>
}

须知：处理包含多个字段的表单时，请使用 JavaScript 的 Object.fromEntries()。例如：const rawFormData = Object.fromEntries(formData)。请注意，此对象将包含以 $ACTION_ 为前缀的额外属性。

传递附加参数

除了表单字段，您还可以使用 JavaScript 的 bind 方法向服务器函数传递附加参数。例如，要将 userId 参数传递给 updateUser 服务器函数，可以这样做：

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

服务器函数将把 userId 作为附加参数接收。

'use server'
 
export async function updateUser(userId: string, formData: FormData) {}

须知:

另一种方法是将参数作为隐藏输入字段传递到表单中（例如 <input type="hidden" name="userId" value={userId} />）。但是，该值将成为渲染 HTML 的一部分，并且不会被编码。

bind 适用于服务器和客户端组件，并支持渐进增强。

表单验证

表单可以在客户端或服务器端进行验证。

对于客户端验证，您可以使用 HTML 属性（如 required 和 type="email"）进行基本验证。
对于服务器端验证，您可以使用像 zod 这样的库来验证表单字段。例如：

'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'),
  })
 
  // Return early if the form data is invalid
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
    }
  }
 
  // Mutate data
}

验证错误

要显示验证错误或消息，请将定义 <form> 的组件转换为客户端组件，并使用 React useActionState。

使用 useActionState 时，服务器函数的签名将更改，以接收一个新的 prevState 或 initialState 参数作为其第一个参数。

'use server'
 
import { z } from 'zod'
 
export async function createUser(initialState: any, formData: 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>
  )
}

待定状态

useActionState 钩子暴露了一个 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}>
      {/* Other form elements */}
      <button disabled={pending}>Sign up</button>
    </form>
  )
}

或者，您可以使用 useFormStatus 钩子在 Action 执行期间显示加载指示器。使用此钩子时，您需要创建一个单独的组件来渲染加载指示器。例如，要在 Action 待定时禁用按钮：

'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}>
      {/* Other form elements */}
      <SubmitButton />
    </form>
  )
}

须知：在 React 19 中，useFormStatus 返回的对象上包含附加键，例如 data、method 和 action。如果您未使用 React 19，则只有 pending 键可用。

乐观更新

您可以使用 React useOptimistic 钩子在服务器函数执行完成之前乐观地更新 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>
  )
}

嵌套表单元素

您可以在嵌套在 <form> 内部的元素中调用服务器 Action，例如 <button>、<input type="submit"> 和 <input type="image">。这些元素接受 formAction 属性或事件处理程序。

这在您希望在表单中调用多个服务器 Action 的情况下非常有用。例如，除了发布帖子之外，您还可以创建一个特定的 <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>
  )
}

这将触发最近的 <form> 祖先的提交，从而调用服务器函数。