Ordo UI
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*booleanfalse—
submitError*stringnull—
size*"wide" | "default"'default'—
fields*(form: UseFormReturn<T>) => ReactNode——
discardTitle*string——
discardDescription*string——
labels*Partial<FormDialogLabels>——

源码

packages/patterns/src/components/form-dialog.tsx
/**
 * 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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

标准化实体创建/编辑对话框:RHF+Zod 校验、字段段 render prop、提交态、脏表单关闭确认;labels 覆写文案。