alang.ai

009 server-side form validation ​

目录

本文对应 Next.js Learn 入门教程的第 14 章。

In the previous chapter, we looked at how to catch errors (including 404 errors) and display a fallback to the user. However, we still need to discuss another piece of the puzzle: form validation. Let's see how to implement server-side validation with Server Actions, and how you can show form errors using the useFormState hook - while keeping accessibility in mind!

How to use eslint-plugin-jsx-a11y with Next.js to implement accessibility best practices.

How to implement server-side form validation.

How to use the React useFormState hook to handle form errors, and display them to the user.

accessibility ​

What is accessibility?

Accessibility refers to designing and implementing web applications that everyone can use, including those with disabilities. It's a vast topic that covers many areas, such as keyboard navigation, semantic HTML, images, colors, videos, etc.

While we won't go in-depth into accessibility in this course, we'll discuss the accessibility features available in Next.js and some common practices to make your applications more accessible.

ESLint accessibility plugin ​

By default, Next.js includes the eslint-plugin-jsx-a11y plugin to help catch accessibility issues early. For example, this plugin warns if you have images without alt text, use the aria-* and role attributes incorrectly, and more.

json
"scripts": {
    "build": "next build",
    "dev": "next dev",
    "seed": "node -r dotenv/config ./scripts/seed.js",
    "start": "next start",
    "lint": "next lint"
},

（略）

Improving form accessibility ​

https://nextjs.org/learn/dashboard-app/improving-accessibility#improving-form-accessibility

Form validation ​

Client-Side validation ​

tsx
<input
  id="amount"
  name="amount"
  type="number"
  step="0.01"
  required
/>

在HTML中，required属性是一个布尔属性，用于指定输入字段（<input>）是否必须填写才能提交表单。

在你的代码中，required属性被添加到了一个<input>元素上，这意味着用户必须在这个输入字段中输入一些内容才能提交表单。如果用户尝试在没有填写这个字段的情况下提交表单，浏览器会显示一个错误消息，并阻止表单的提交。

Server-Side validation ​

https://nextjs.org/learn/dashboard-app/improving-accessibility#server-side-validation

By validating forms on the server, you can:

  • Ensure your data is in the expected format before sending it to your database.
  • Reduce the risk of malicious users bypassing client-side validation.
  • Have one source of truth for what is considered valid data.

通过在服务器上对表单进行验证，你可以：

  • 在将数据发送到数据库之前，确保数据是按照预期的格式。
  • 减少恶意用户绕过客户端验证的风险。
  • 有一个关于何谓“有效”数据的唯一真义来源。

服务端验证的具体实现 ​

In your create-form.tsx component, import the useFormState hook from react-dom. Since useFormState is a hook, you will need to turn your form into a Client Component using "use client" directive:

/app/ui/invoices/create-form.tsx

  1. Import the useFormState hook from react-dom.
tsx
'use client';

// ...
import { useFormState } from 'react-dom';
  1. use

Inside your Form Component, the useFormState hook:

  • Takes two arguments: (action, initialState).
  • Returns two values: [state, dispatch] - the form state, and a dispatch function (similar to useReducer)

Pass your createInvoice action as an argument of useFormState, and inside your <form action={}> attribute, call dispatch.

tsx
// ...
import { useFormState } from 'react-dom';

export default function Form({ customers }: { customers: CustomerField[] }) {
  const [state, dispatch] = useFormState(createInvoice, initialState);

  return <form action={dispatch}>...</form>;
}
  1. actions.ts
ts
const FormSchema = z.object({
  id: z.string(),
  customerId: z.string({
    invalid_type_error: 'Please select a customer.',
  }),
  amount: z.coerce
    .number()
    .gt(0, { message: 'Please enter an amount greater than $0.' }),
  status: z.enum(['pending', 'paid'], {
    invalid_type_error: 'Please select an invoice status.',
  }),
  date: z.string(),
});
ts
// This is temporary until @types/react-dom is updated
export type State = {
  errors?: {
    customerId?: string[];
    amount?: string[];
    status?: string[];
  };
  message?: string | null;
};

export async function createInvoice(prevState: State, formData: FormData) {
  // ...
}
  • formData - same as before.
  • prevState - contains the state passed from the useFormState hook. You won't be using it in the action in this example, but it's a required prop.

Then, change the Zod parse() function to safeParse():

safeParse() will return an object containing either a success or error field. This will help handle validation more gracefully without having put this logic inside the try/catch block.

……

（注意 actions.ts 的更新）

ts
export async function createInvoice(prevState: State, formData: FormData) {
  // Validate form using Zod
  const validatedFields = CreateInvoice.safeParse({
    customerId: formData.get('customerId'),
    amount: formData.get('amount'),
    status: formData.get('status'),
  });

  // If form validation fails, return errors early. Otherwise, continue.
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
      message: 'Missing Fields. Failed to Create Invoice.',
    };
  }

  // Prepare data for insertion into the database
  const { customerId, amount, status } = validatedFields.data;
  const amountInCents = amount * 100;
  const date = new Date().toISOString().split('T')[0];

  // Insert data into the database
  try {
    await sql`
      INSERT INTO invoices (customer_id, amount, status, date)
      VALUES (${customerId}, ${amountInCents}, ${status}, ${date})
    `;
  } catch (error) {
    // If a database error occurs, return a more specific error.
    return {
      message: 'Database Error: Failed to Create Invoice.',
    };
  }

  // Revalidate the cache for the invoices page and redirect the user.
  revalidatePath('/dashboard/invoices');
  redirect('/dashboard/invoices');
}
  1. 界面
tsx
<form action={dispatch}>
  <div className="rounded-md bg-gray-50 p-4 md:p-6">
    {/* Customer Name */}
    <div className="mb-4">
      <label htmlFor="customer" className="mb-2 block text-sm font-medium">
        Choose customer
      </label>
      <div className="relative">
        <select
          id="customer"
          name="customerId"
          className="peer block w-full rounded-md border border-gray-200 py-2 pl-10 text-sm outline-2 placeholder:text-gray-500"
          defaultValue=""
          aria-describedby="customer-error"
        >
          <option value="" disabled>
            Select a customer
          </option>
          {customers.map((name) => (
            <option key={name.id} value={name.id}>
              {name.name}
            </option>
          ))}
        </select>
        <UserCircleIcon className="pointer-events-none absolute left-3 top-1/2 h-[18px] w-[18px] -translate-y-1/2 text-gray-500" />
      </div>
      <div id="customer-error" aria-live="polite" aria-atomic="true">
        {state.errors?.customerId &&
          state.errors.customerId.map((error: string) => (
            <p className="mt-2 text-sm text-red-500" key={error}>
              {error}
            </p>
          ))}
      </div>
    </div>
    // ...
  </div>
</form>

In the code above, you're also adding the following aria labels:

  • aria-describedby="customer-error": This establishes a relationship between the select element and the error message container. It indicates that the container with id="customer-error" describes the select element. Screen readers will read this description when the user interacts with the select box to notify them of errors.
  • id="customer-error": This id attribute uniquely identifies the HTML element that holds the error message for the select input. This is necessary for aria-describedby to establish the relationship.
  • aria-live="polite": The screen reader should politely notify the user when the error inside the div is updated. When the content changes (e.g. when a user corrects an error), the screen reader will announce these changes, but only when the user is idle so as not to interrupt them.

在上面的代码中，你还添加了以下 aria 标签：

  • aria-describedby="customer-error"：这建立了 select 元素和错误消息容器之间的关系。它指出带有 id="customer-error" 的容器对 select 元素进行了描述。当用户与 select 框交互时，屏幕阅读器将阅读此描述以通知他们错误。
  • id="customer-error"：这个 id 属性唯一地识别了包含 select 输入错误信息的 HTML 元素。这对于 aria-describedby 建立关系是必要的。
  • aria-live="polite"：当 div 内的错误更新时，屏幕阅读器应当礼貌地通知用户。当内容发生变化时（例如，当用户更正错误时），屏幕阅读器会宣布这些变化，但只有在用户空闲时才这样做，以避免打断他们。

解释 aria-describedby

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby

Accessible Rich Internet Applications (ARIA)

Warning: Many of these widgets are fully supported in modern browsers. Developers should prefer using the correct semantic HTML element over using ARIA, if such an element exists. For instance, native elements have built-in keyboard accessibility, roles and states. However, if you choose to use ARIA, you are responsible for mimicking the equivalent browser behavior in script.

警告：许多此类小部件在现代浏览器中得到了完全支持。如果存在相应的语义HTML元素，开发者应当优先使用正确的语义HTML元素，而非使用ARIA（可访问性丰富的互联网应用）。例如，原生元素具有内置的键盘可访问性、角色（roles）和状态（states）。然而，如果你选择使用ARIA，你需要负责在脚本中模拟相当的浏览器行为。

The first rule of ARIA use is "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so."

ARIA（Accessible Rich Internet Applications）使用的第一条规则是："如果你可以使用一个具有所需语义和行为内置的原生HTML元素或属性，而不是重新指定一个元素并添加ARIA角色、状态或属性来达到可访问性要求，那么就应该这么做。"

aria-describedby 是一个常用于增强无障碍访问性的 HTML 属性。它提供了一种方法来建立元素和其他元素之间的描述关系，这些元素提供了关于对象的额外信息。

在你的代码中，aria-describedby="customer-error" 表示当前元素（可能是一个输入框）的描述由 id 为 "customer-error" 的元素提供。这通常用于关联错误消息和它们对应的表单输入。

例如，如果你有一个输入框和一个错误消息，你可以这样使用 aria-describedby：

html
<input id="username" aria-describedby="username-error" />
<span id="username-error">Username is required</span>

在这个例子中，当用户的屏幕阅读器聚焦到输入框时，它会读出输入框的标签，然后读出 "Username is required"。这样，视障用户就能知道他们需要填写用户名。

（练习见原文最后）

Alang.AI - Make Great AI Applications

Copyright © 2025