PatternsSemantic
FormDialog
@mox-hub/patterns 模式 · Semantic · canonical
form-dialog@mox-hub/patternsSemanticcanonicalsrc/components/form-dialog.tsx变体演示form-dialog
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| open* | boolean | — | — |
| onOpenChange* | (open: boolean) => void | — | — |
| title* | ReactNode | — | — |
| description* | string | — | — |
| schema* | ZodType<T, unknown, $ZodTypeInternals<T, unknown>> | — | — |
| defaultValues* | DefaultValues<T> | — | — |
| onSubmit* | (values: T) => void | Promise<void> | — | — |
| submitLabel* | string | — | — |
| submitting* | boolean | false | — |
| submitError* | string | null | — |
| size* | "wide" | "default" | 'default' | — |
| fields* | (form: UseFormReturn<T>) => ReactNode | — | — |
| discardTitle* | string | — | — |
| discardDescription* | string | — | — |
| labels* | Partial<FormDialogLabels> | — | — |
源码
/**
* FormDialog - 标准化实体创建/编辑对话框(统一创建面板优化批四·第 0 步)
*
* 面板之外 13+ 处各自为政的创建对话框的收敛承载件:把「Dialog 骨架 + RHF+Zod
* 校验(§13.1)+ Field 结构 + 提交态(disabled+内联 Spinner,§10.6)+ 脏表单
* 关闭确认(§20.1 同层 AlertDialog)+ §10.8 尺寸档」一次封死,消费方只声明
* schema、字段段与提交回调,不再手写任何骨架。
*
* 层规则(semantic/README):内部组合 ui/ 原子(Button/Dialog/Spinner),不反向
* 依赖业务模块;props 面封闭(G8)——不接 className、不透传样式、不 extends
* HTMLAttributes;字段段经 render prop 注入(消费方持 RHF 实例渲染 FormField)。
*/
import { useEffect, useState, type ReactNode } from 'react';
import { useForm, type DefaultValues, type FieldValues, type UseFormReturn } from 'react-hook-form';
// Form = FormProvider:FormLabel/FormMessage 等经 useFormContext 取状态,必须包裹(缺它即 null 崩)
import { Form } from '@mox-hub/ui/components/form';
import { zodResolver } from '@hookform/resolvers/zod';
import type { ZodType } from 'zod';
import { usePatternLabels } from '../lib/i18n';
import { AlertCircle } from 'lucide-react';
import {
Dialog,
DialogContent,
DialogDescription,
DialogFooter,
DialogTitle,
} from '@mox-hub/ui/components/dialog';
import {
AlertDialog,
AlertDialogAction,
AlertDialogCancel,
AlertDialogContent,
AlertDialogDescription,
AlertDialogFooter,
AlertDialogTitle,
} from '@mox-hub/ui/components/alert-dialog';
import { Alert, AlertDescription } from '@mox-hub/ui/components/alert';
import { Button } from '@mox-hub/ui/components/button';
import { Spinner } from '@mox-hub/ui/components/spinner';
/** 组件内文案缺省(中文常量;消费方经 labels 覆写接入 i18n)。 */
export interface FormDialogLabels {
cancel: string;
saving: string;
unsavedTitle: string;
unsavedDesc: string;
keepEditing: string;
discard: string;
}
export const FORM_DIALOG_DEFAULT_LABELS: FormDialogLabels = {
cancel: '取消',
saving: '保存中…',
unsavedTitle: '有未保存的更改',
unsavedDesc: '关闭后已填内容将丢失。',
keepEditing: '继续编辑',
discard: '放弃更改',
};
export interface FormDialogProps<T extends FieldValues> {
open: boolean;
onOpenChange: (open: boolean) => void;
/** DialogTitle 必给(§8.5);同时承担 DialogDescription 缺省;可传图标+文案节点 */
title: ReactNode;
description?: string;
/** Zod schema:唯一校验真相源,错误文案由 schema 提供(§13.4/13.5) */
schema: ZodType<T>;
defaultValues: DefaultValues<T>;
/** 提交回调:抛错由消费方自行 toast;返回即视为成功关窗 */
onSubmit: (values: T) => Promise<void> | void;
submitLabel: string;
/** 外部提交中态(mutation isPending);与内部 submitting 取或 */
submitting?: boolean;
/** 服务端错误呈现(Alert destructive,置字段区上方) */
submitError?: string | null;
/** §10.8 尺寸轴:default(实体表单基线)/ wide(多卡并排才升档) */
size?: 'default' | 'wide';
/** 字段段:消费方经 render prop 持 RHF 实例渲染(Field/FormField 套件) */
fields: (form: UseFormReturn<T>) => ReactNode;
/** 关窗前脏确认文案(缺省给通用「未保存更改」口径) */
discardTitle?: string;
discardDescription?: string;
/** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
labels?: Partial<FormDialogLabels>;
}
export function FormDialog<T extends FieldValues>({
open,
onOpenChange,
title,
description,
schema,
defaultValues,
onSubmit,
submitLabel,
submitting: externalSubmitting = false,
submitError = null,
size = 'default',
fields,
discardTitle,
discardDescription,
labels,
}: FormDialogProps<T>) {
const D = usePatternLabels('formDialog', FORM_DIALOG_DEFAULT_LABELS);
const text = {
cancel: labels?.cancel ?? D.cancel,
saving: labels?.saving ?? D.saving,
unsavedTitle: labels?.unsavedTitle ?? D.unsavedTitle,
unsavedDesc: labels?.unsavedDesc ?? D.unsavedDesc,
keepEditing: labels?.keepEditing ?? D.keepEditing,
discard: labels?.discard ?? D.discard,
};
const [confirmDiscard, setConfirmDiscard] = useState(false);
const form = useForm<T>({
// zod v4 + resolvers v6:schema 声明为 ZodType<T> 时输入侧推为 unknown,
// resolver 落型 Resolver<unknown>——单点断言对齐(schema 契约由消费方保证)
resolver: zodResolver(schema) as unknown as import('react-hook-form').Resolver<T>,
defaultValues,
mode: 'onBlur',
});
// 打开即重置(创建态复用同一挂载;编辑态由消费方经 key 重挂载换 defaultValues)
useEffect(() => {
if (open) form.reset(defaultValues);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [open]);
// 渲染期解构以订阅 formState(RHF 的 formState 是 Proxy:未订阅的字段在
// 事件回调里可能读到旧值——isDirty 必须在此显式读取)
const { isSubmitting: internalSubmitting, isDirty } = form.formState;
const submitting = externalSubmitting || internalSubmitting;
/** 脏表单守卫:有未提交更改先弹确认(§20.1——AlertDialog 与 Dialog 同层串行) */
const requestClose = (next: boolean) => {
if (!next && isDirty) {
setConfirmDiscard(true);
return;
}
onOpenChange(next);
};
return (
<>
<Dialog open={open} onOpenChange={requestClose}>
<DialogContent size={size}>
<DialogTitle>{title}</DialogTitle>
{description ? (
<DialogDescription>{description}</DialogDescription>
) : (
<DialogDescription className="sr-only">{title}</DialogDescription>
)}
<Form {...form}>
<form
onSubmit={form.handleSubmit(async (values) => {
await onSubmit(values);
onOpenChange(false);
})}
className="flex flex-col gap-4"
noValidate
>
{submitError && (
<Alert variant="destructive" className="py-2 text-xs">
<AlertCircle className="size-3.5 shrink-0" />
<AlertDescription className="text-xs">{submitError}</AlertDescription>
</Alert>
)}
<div className="flex flex-col gap-4">{fields(form)}</div>
<DialogFooter className="gap-2">
<Button
type="button"
variant="ghost"
onClick={() => requestClose(false)}
disabled={submitting}
>
{text.cancel}
</Button>
<Button type="submit" disabled={submitting} data-ai-action="form-dialog-submit">
{submitting && <Spinner className="size-3 text-inherit" />}
{submitting ? text.saving : submitLabel}
</Button>
</DialogFooter>
</form>
</Form>
</DialogContent>
</Dialog>
<AlertDialog open={confirmDiscard} onOpenChange={setConfirmDiscard}>
<AlertDialogContent>
<AlertDialogTitle>
{discardTitle ?? text.unsavedTitle}
</AlertDialogTitle>
<AlertDialogDescription>
{discardDescription ?? text.unsavedDesc}
</AlertDialogDescription>
<AlertDialogFooter>
<AlertDialogCancel>{text.keepEditing}</AlertDialogCancel>
<AlertDialogAction
onClick={() => {
setConfirmDiscard(false);
form.reset(defaultValues);
onOpenChange(false);
}}
>
{text.discard}
</AlertDialogAction>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialog>
</>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
标准化实体创建/编辑对话框:RHF+Zod 校验、字段段 render prop、提交态、脏表单关闭确认;labels 覆写文案。