docs(ui): explain shared controls and canvas display adapters

This commit is contained in:
2026-11-12 01:51:59 +08:00
parent 1306df2b35
commit b51d78b47d
11 changed files with 115 additions and 0 deletions
+16
View File
@@ -1,3 +1,7 @@
/**
* 基于Radix的对话框展示封装:保留其开关、焦点管理和可访问语义,补项目统一的遮罩、布局与动画。
* 调用方通过Root的open/onOpenChange控制业务流程;保存中是否允许关闭等规则不由本模块决定。
*/
"use client";
import * as React from "react";
@@ -6,14 +10,19 @@ import { X } from "lucide-react";
import { cn } from "@/lib/utils";
/** Root提供受控或非受控开关上下文,本层不再复制一份open状态。 */
const Dialog = DialogPrimitive.Root;
/** Trigger接入同一Root,负责触发打开;可沿用Radix的asChild组合调用方控件。 */
const DialogTrigger = DialogPrimitive.Trigger;
/** Portal把浮层移出页面普通布局,避免受父容器裁切;挂载方式沿用Radix。 */
const DialogPortal = DialogPrimitive.Portal;
/** 暴露关闭原语,供业务在底部动作区等位置放额外关闭入口。 */
const DialogClose = DialogPrimitive.Close;
/** 转发遮罩ref与属性,铺满视口;开关动画由Radix的data-state驱动,className允许调用方补样式。 */
const DialogOverlay = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Overlay>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
@@ -29,6 +38,9 @@ const DialogOverlay = React.forwardRef<
));
DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
/** 组合Portal、遮罩与居中内容面板,并在children之后固定附带右上角关闭按钮。
* 面板ref和剩余属性交给Radix Content,保留焦点及外部交互事件;关闭按钮有读屏文字。
* 本封装没有单独隐藏默认关闭按钮的参数,业务若要阻止关闭应在受控开关/事件层处理。 */
const DialogContent = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Content>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
@@ -53,6 +65,7 @@ const DialogContent = React.forwardRef<
));
DialogContent.displayName = DialogPrimitive.Content.displayName;
/** 标题区只组织纵向间距与响应式文字对齐;原生div属性和children原样透传。 */
const DialogHeader = ({
className,
...props
@@ -67,6 +80,7 @@ const DialogHeader = ({
);
DialogHeader.displayName = "DialogHeader";
/** 动作区在窄屏使用反向纵排,在sm及以上改为靠右横排;不绑定提交或取消动作。 */
const DialogFooter = ({
className,
...props
@@ -81,6 +95,7 @@ const DialogFooter = ({
);
DialogFooter.displayName = "DialogFooter";
/** 转发Radix标题的ref/属性并统一字号;标题仍参与对话框的可访问命名关联。 */
const DialogTitle = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Title>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
@@ -96,6 +111,7 @@ const DialogTitle = React.forwardRef<
));
DialogTitle.displayName = DialogPrimitive.Title.displayName;
/** 转发Radix说明文字的ref/属性并使用弱化文字样式;说明关联由Radix上下文维护。 */
const DialogDescription = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Description>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>