# 更好的表格指南现代 Web 表单的特定 UX 模式、可访问性标准和实现技术的集合。本指南弥合了原始 HTML/CSS 技巧和基于组件的架构（React、Tailwind、Headless UI）之间的差距。 ## 1\.高影响力的用户体验模式（“为什么”和“如何”） ### 避免列表中的“死区” **概念**：可点击列表项之间的小间隙会造成挫败感。 **实现（Tailwind）** ：使用伪元素来扩大点击区域而不影响布局。 // 对列表项或单选组执行此操作

选项标签

### 范围滑块 > 最小/最大输入 **概念**：“从 10 美元到 1000 美元”的文本输入很乏味。 **实现**：使用双拇指滑块组件（如 Radix UI / Shadcn Slider）作为范围。 * **为什么**：认知负荷减轻和即时视觉反馈。 * **A11y** ：确保滑块支持箭头键导航。 ### “输出启发”设计 **概念**：表单输入在视觉上应类似于最终结果卡/页面。 * **层次结构** ：如果输出标题是“text-2xl font-bold”，则其输入应该是“text-2xl font-bold”。 * **放置** ：如果图像位于列表的左侧，则上传按钮位于表单的左侧。 * **空状态** ：在填充空卡时预览空卡的外观。 ### 描述性操作按钮 **概念**：切勿使用“提交”或“发送”。该按钮应完成句子“我想...” * 避免：`提交` * 首选：`创建帐户`、`发布列表`、`更新个人资料` **提示**：根据表单状态动态更新按钮文本（例如，“正在保存...”与“保存更改”）。 ### “可选”标签 > 星号 **概念**：红色星号 (*) 具有攻击性且不明确（有时表示“错误”）。 **实现** ：默认标记必填字段（无指示符）并显式标记可选字段。 <标签> 电话号码{" "} （可选） ### 显示/隐藏密码 **概念**：默认情况下屏蔽密码可防止错误更正。 **实现**：始终在输入包装器内包含一个切换按钮。 * **A11y** ：切换按钮必须具有 `type="button"` 和 `aria-label="Show password"`。 ### 场地大小作为可供性 **概念**：输入的宽度表明预期的数据长度。 * **邮政编码**：“w-20”或“w-24”（非全角）。 * **CVV** ：小宽度。 * **街道地址**：全角。 ## 2\.高级用户体验模式 ### 输入屏蔽和格式 **概念**：在用户键入时自动格式化数据，以减少错误和认知负担。 // 使用react-number-format格式化电话号码从“react-number-format”导入{PatternFormat}； <模式格式格式=“(###)###-####” 掩码=“_” 允许空格式 customInput={Input} // 您的样式输入组件 onValueChange={(值) => { //values.value =“1234567890”（原始） // 值.formattedValue = "(123) 456-7890" form.setValue(“电话”,values.value); }} />; // 具有自动间距的信用卡 <模式格式格式=“#### #### #### ####” 自定义输入={输入} onValueChange={(values) => form.setValue("cardNumber",values.value)} />; // 货币输入从“react-number-format”导入{ NumericFormat }； <数字格式千分隔符=“，” 前缀=“$” 小数刻度={2} 固定小数位自定义输入={输入} onValueChange={(values) => form.setValue("金额",values.floatValue)} />; **关键原理**：存储原始值，显示格式化值。切勿验证格式化字符串。 ### OTP / 2FA 代码输入 **概念**：6 位验证码需要特殊处理才能进行粘贴、自动对焦和键盘导航。从“react”导入{ useRef、useState、useCallback、ClipboardEvent、KeyboardEvent }；接口 OTPInputProps { 长度？：数量； onComplete: (代码: string) => void; } 导出函数 OTPInput({ length = 6, onComplete }: OTPInputProps) { const [values, setValues] = useState(Array(length).fill("")); const inputRefs = useRef<(HTMLInputElement | null)[]>([]); const focusInput = useCallback((索引：数字) => { const lampedIndex = Math.max(0, Math.min(索引, 长度 - 1)); inputRefs.current[clampedIndex]?.focus(); }, [长度]); const handleChange = (索引: 数字, 值: 字符串) => { if (!/^\d*$/.test(value)) 返回； // 仅限数字 const newValues = [...值]; newValues[index] = value.slice(-1); // 只取最后一位数字设置值（新值）； if (值 && 索引 < 长度 - 1) { focusInput(索引+1); } const 代码 = newValues.join(""); if (code.length === 长度) { onComplete(代码); } }; const handleKeyDown = (索引: number, e: KeyboardEvent) => { 开关（电子钥匙）{ 案例“退格键”： if (!values[index] && 索引 > 0) { focusInput(索引 - 1); } 休息; 案例“向左箭头”： e.preventDefault(); focusInput(索引 - 1); 休息; 案例“右箭头”： e.preventDefault(); focusInput(索引+1); 休息; } }; const handlePaste = (e: ClipboardEvent) => { e.preventDefault(); const PastedData = e.clipboardData.getData("text").replace(/\D/g, "").slice(0, length); 如果（粘贴数据）{ const newValues = [...值]; PastedData.split("").forEach((char, i) => { newValues[i] = 字符； }); 设置值（新值）； focusInput(pastedData.length - 1); if (pastedData.length === 长度) { onComplete(粘贴数据); } } }; 返回（

{values.map((值，索引) => ( <输入键={索引} ref={(el) => { inputRefs.current[index] = el; }} 类型=“文本” 输入模式=“数字” 最大长度={1} 值={值} onChange={(e) => handleChange(index, e.target.value)} onKeyDown={(e) => handleKeyDown(index, e)} onPaste={handlePaste} className="h-12 w-12 文本中心文本-lg 字体-半粗体边框圆形-md 焦点：ring-2 焦点：ring-ring 焦点：边框透明” aria-label={`${length} 的数字 ${index + 1}`} /> ))}

）； } ### 未保存的更改保护 **概念**：在远离脏表单时防止意外数据丢失。 **注意（React 19）**：不要将“react-hook-form”中的“useFormState”与React DOM的“useFormState”混淆，后者在React 19中已重命名为“useActionState”。 **警告**：猴子修补 `router.push` 很脆弱，可能会跨 Next.js 版本崩溃。没有稳定的 API 用于拦截 App Router 导航。 “beforeunload”方法是唯一可靠的部分。如果您的框架支持，请考虑使用“onBeforePopState”（页面路由器）或路由更改事件侦听器。从“反应”导入{useEffect}；从“react-hook-form”导入{ useFormState }；导出函数 useUnsavedChangesWarning(isDirty: boolean, message?: string) { 常量警告消息 = 消息 ?? “您有未保存的更改。您确定要离开吗？”； // 浏览器后退/刷新——这是可靠的方法使用效果（（）=> { const handleBeforeUnload = (e: BeforeUnloadEvent) => { if (!isDirty) 返回； e.preventDefault(); }; window.addEventListener("卸载前",handleBeforeUnload); return () => window.removeEventListener("beforeunload",handleBeforeUnload); }, [isDirty]); // 对于应用内导航，考虑触发确认模式 // 来自您的导航组件，而不是对路由器进行猴子修补。 } // 与 React Hook 表单一起使用函数 EditProfileForm() { const form = useForm(); const { isDirty } = useFormState({ control: form.control }); useUnsavedChangesWarning(isDirty); 返回<表单>...； } ### 多步骤表单（向导） **概念**：通过适当的状态持久性和焦点管理将复杂的形式分解为易于理解的步骤。从“react”导入{ useState、useEffect、useRef、useCallback }；从“react-hook-form”导入{ useForm，FormProvider }；从“@hookform/resolvers/zod”导入{zodResolver}； // 将状态保留到 URL 以实现刷新弹性 // 使用惰性状态 init 在第一次渲染时从 URL 读取（SSR 安全）函数 useStepFromURL() { const [步骤，setStep] = useState(() => { if (typeof window === "未定义") return 1; const params = new URLSearchParams(window.location.search); return parseInt(params.get("step") ?? "1", 10); }); const goToStep = useCallback((newStep: number) => { 设置步骤（新步骤）； const url = 新 URL(window.location.href); url.searchParams.set("step", String(newStep)); window.history.pushState({}, "", url); }, []); 返回{步骤，转到步骤}； } // 将管理重点放在步骤变更上函数 useStepFocus(步骤: 数字) { const headerRef = useRef(null); 使用效果（（）=> { // 聚焦屏幕阅读器公告的步骤标题 headerRef.current?.focus(); }, [步骤]); 返回标题参考； } // 多步骤表单示例接口向导表单数据{ // 步骤 1 名字：字符串；姓氏：字符串； // 步骤 2 电子邮件：字符串；电话：字符串； // 步骤 3 地址：字符串；城市：字符串； } const 步骤模式 = { 1: z.object({ 名字: z.string().min(1), 姓氏: z.string().min(1) }), 2: z.object({ 电子邮件: z.string().email(), 电话: z.string().可选() }), 3: z.object({ 地址: z.string().min(1), 城市: z.string().min(1) }), }; 导出函数 WizardForm() { const { 步骤，goToStep } = useStepFromURL(); const headerRef = useStepFocus(step); 常量总步骤= 3； const form = useForm({ 解析器：zodResolver(stepSchemas[step as keyof typeof stepSchemas]), 模式：“onBlur”， }); // 将草稿保存到 localStorage 使用效果（（）=> { const save = localStorage.getItem("向导草稿"); 如果（已保存）{ form.reset(JSON.parse(已保存)); } }, []); 使用效果（（）=> { const 订阅 = form.watch((data) => { localStorage.setItem("向导草稿", JSON.stringify(data)); }); return () => 订阅.取消订阅(); }, [表格]); const handleNext = async () => { const isValid = 等待 form.trigger(); if (isValid && 步骤 < 总步骤数) { 转到步骤（步骤+1）； } }; 常量handleBack = () => { 如果（步骤 > 1）转到步骤（步骤 - 1）； }; 返回（ {/* 进度指示器 */}

第 {step} 步（共 {totalSteps} 步）

{/* 步骤标题 - 专注于导航 */}

{步骤 === 1 && “个人信息”} {步骤=== 2 &&“联系方式”} {步骤 === 3 && "地址"}

{步骤 === 1 && } {步骤 === 2 && } {步骤=== 3 && <步骤三/>}

{步骤 > 1 && ( <按钮类型=“按钮”onClick={handleBack}> 返回 )} {步数<总步数？（ <按钮类型=“按钮”onClick={handleNext}> 继续 ) : ( )}

）； } ## 3\.后端集成模式 ### 服务器端错误映射 **概念**：将 API 验证错误映射回特定表单字段。从“react-hook-form”导入{ useForm，UseFormReturn }；接口API错误{ 字段：字符串；消息：字符串； } 接口API响应{ 成功：布尔值；错误？：APIError[]； } // 用法：传递表单实例并调用组件内部函数 useServerErrorHandler>(form: UseFormReturn) { 返回异步（数据：T）=> { const 响应 = 等待 fetch("/api/register", { 方法：“POST”，正文：JSON.stringify（数据）， }); const 结果：APIResponse =等待response.json(); if (!result.success && result.errors) { // 将服务器错误映射到表单字段结果.errors.forEach((错误) => { form.setError(error.field as keyof T & string, { 类型：“服务器”，消息：错误消息， }); }); // 聚焦第一个出错字段 const firstErrorField = result.errors[0]?.field; 如果（第一个错误字段）{ form.setFocus(firstErrorField as keyof T & string); } 返回; } // 成功处理 }; } // 对于嵌套错误（例如，“address.city”）函数mapNestedError（形式：UseFormReturn，路径：字符串，消息：字符串）{ form.setError(path as any, { type: "server", message }); } ### 去抖异步验证 **概念**：验证昂贵的字段（用户名可用性）而无需 API 过载。从“react”导入{ useEffect、useMemo、useRef、useState }；从“lodash.debounce”导入去抖； // 用于异步字段验证的自定义钩子 // 使用 validateFn 的 ref 来保持去抖动稳定并避免计时器重置。 // 取消卸载时进行中的去抖调用以防止内存泄漏。函数 useAsyncValidation( validateFn: (值: T) => Promise<字符串 |空>, 延迟 = 500 ）{ const [isValidating, setIsValidating] = useState(false); const [错误，setError] = useState<字符串|空>(空); const validateFnRef = useRef(validateFn); validateFnRef.current = validateFn; const debouncedValidate = useMemo( ()=> 去抖（异步（值：T）=> { setIsValidating(true); 尝试{ const 结果 = 等待 validateFnRef.current(value); 设置错误（结果）； }最后{ setIsValidating(假); } }，延迟）， [延迟] ）； // 卸载时清理反跳定时器 useEffect(() => () => debouncedValidate.cancel(), [debouncedValidate]); 返回 { 验证: debouncedValidate, isValidating, 错误 }; } // 与 React Hook 表单一起使用 // 验证在 onChange 处理程序中运行（不通过效果）以避免 // 竞争条件和不必要的重新渲染。函数用户名字段（）{ const { 注册、设置错误、清除错误 } = useFormContext(); const [isChecking, setIsChecking] = useState(false); const checkUsername = async (值: string): Promise => { if (!value || value.length < 3) 返回 null; 常量响应 = 等待获取（ `/api/check-username?username=${encodeURIComponent(value)}` ）； const { 可用 } = 等待响应.json(); 可以退货吗？ null : "该用户名已被占用"; }; const { validate, isValidating } = useAsyncValidation(checkUsername); // 导出组合检查状态 const showChecking = isChecking ||正在验证； const { onChange: rhfOnChange, ...rest } = register("用户名", { onChange: (e) => { const 值 = e.target.value; if (值 && value.length >= 3) { setIsChecking(true); 验证（值）； } 否则{ 清除错误（“用户名”）； } }, // 还通过 RHF 的内置异步验证提交时间进行验证验证：异步（值）=> { const 结果 = 等待 checkUsername(值); 返回结果？？真实； }, }); 返回（

{showChecking && 正在检查...}

）； } ### 乐观更新 **概念**：在请求进行时显示即时反馈。从“react”导入{useTransition，useState}；类型 SubmitState = "空闲" | “提交” | “成功” | “错误”; 函数 ProfileForm() { const [isPending, startTransition] = useTransition(); const [submitState, setSubmitState] = useState("idle"); const [optimisticData, setOptimisticData] = useState(空); 异步函数handleSubmit（数据：ProfileData）{ // 立即显示乐观更新设置乐观数据（数据）； setSubmitState("正在提交"); 开始转换（异步（）=> { 尝试{ 等待更新配置文件（数据）； setSubmitState("成功"); // 延迟后清除成功状态 setTimeout(() => setSubmitState("空闲"), 2000); } 捕获（错误）{ // 恢复乐观更新 setOptimisticData(null); setSubmitState("错误"); } }); } 返回（ {/* 显示乐观预览 */} {乐观数据 && (

预览：{optimisticData.name}

)} <按钮类型=“提交”禁用= {isPending}> {submitState ===“正在提交”&&“正在保存...”} {submitState ===“成功”&&“已保存！”} {submitState ===“错误”&&“再试一次”} {submitState ===“空闲”&&“保存更改”} ）； } ## 4\.复杂的组件模式 ### 可访问的文件上传（拖放） **概念**：拖放区域通常无法访问。确保键盘和屏幕阅读器支持。从“react”导入 { useCallback, useId, useState, useRef }; 接口 FileUploadProps { 接受？：字符串；最大尺寸？：数字； // 字节 onUpload: (文件: 文件[]) => void; } 导出函数 AccessibleFileUpload({ 接受, maxSize, onUpload }: FileUploadProps) { const [isDragOver, setIsDragOver] = useState(false); const [错误，setError] = useState<字符串|空>(空); const inputRef = useRef(null); const dropzoneId = useId(); const errorId = `${dropzoneId}-error`; const handleFiles = useCallback((文件: FileList | null) => { 设置错误（空）； if (!files?.length) 返回； const validFiles: 文件[] = []; Array.from(files).forEach((file) => { if (maxSize && file.size > maxSize) { setError(`${file.name} 超出最大大小`); 返回； } validFiles.push(文件); }); if (validFiles.length) { onUpload(有效文件); } }, [maxSize, onUpload]); const handleDrop = useCallback((e: React.DragEvent) => { e.preventDefault(); setIsDragOver(假); handleFiles(e.dataTransfer.files); }, [handleFiles]); const handleKeyDown = (e: React.KeyboardEvent) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); inputRef.current?.click(); } }; 返回（

{/* 隐藏但可访问的文件输入 */} <输入参考={输入参考} 类型=“文件” 接受={接受} onChange={(e) => handleFiles(e.target.files)} 类名=“仅限 sr” id={dropzoneId} 咏叹调描述={错误？错误ID：未定义} /> {/* 可点击且可通过键盘访问的拖放区 */} <标签 htmlFor={dropzoneId} 角色=“按钮” 标签索引={0} onKeyDown={handleKeyDown} onDragOver={(e) => { e.preventDefault(); setIsDragOver(true); }} onDragLeave={() => setIsDragOver(false)} onDrop={handleDrop} 类名={cn( "flex flex-col items-center justify-center p-8 border-2 border-dashed rounded-lg 光标指针", “悬停：边框-主焦点：轮廓-无焦点：环-2焦点：环-环”， isDragOver && "border-primary bg-primary/5", 错误&&“边界破坏性” )} > 将文件拖放到此处或单击浏览 {接受&&`已接受：${接受}`} {maxSize && `（最大值：${formatBytes(maxSize)}）`} {错误&&(

{错误}

)}

）； } ### 可访问的组合框（可搜索选择） **概念**：本机 ` <选项值="">日 {Array.from({ 长度: 31 }, (_, i) => ( <选项 key={i + 1} value={String(i + 1).padStart(2, "0")}>{i + 1} ))}

更好的形式

包含技能