前端 SDK 导出:DialogHeader – DialogsService
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/frontend/extension-api。
DialogHeader · DialogHostApi · DialogHostSnapshot · DialogIconButton · DialogIconButtonProps · DialogInstance · DialogMediaWorkspace · DialogRegistration · DialogRenderer · DialogRendererProps · DialogSection · DialogSize · DialogStage · DialogSurface · DialogSurfaceContext · DialogSurfaceContextValue · DialogSurfaceProps · DialogSurfaceRadixContentProps · DialogSurfaceRoot · DialogSurfaceRootProps · DialogTitle · DialogToolbar · DialogVariant · DialogsService
DialogHeader
Header:标题行 + 可选关闭按钮(图标语言,不再是 ✕ 字符)。
export function DialogHeader(props: { children: ReactNode; onClose?: () => void; closeLabel?: string; }): React.JSX.Element;DialogHostApi
Host 对外 API(store 实现,renderer/业务使用)。
export type DialogHostApi = { open(request: OpenDialogRequest): OpenDialogResult; replace(payload: unknown, instanceId?: string): boolean; close(instanceId?: string): boolean; closeTop(): boolean; requestClose(instanceId?: string): DialogCloseResult; setBusy(instanceId: string, busy: boolean): boolean;};关联类型:OpenDialogRequest · OpenDialogResult · DialogCloseResult
成员说明:
replace:替换指定实例(缺省为顶部)的 payload;instanceId 不匹配时不动作。close:关闭指定实例及其显式子孙;缺省关闭顶部。requestClose:请求关闭(缺省顶部):统一走 dismissible / busy / close guard 判定, 不绕过 guard 直接关闭。setBusy:更新 busy;已关闭实例的迟到调用被忽略(返回 false)。
DialogHostSnapshot
export type DialogHostSnapshot = DialogHostSnapshot;DialogIconButton
紧凑图标按钮(共享 neutral/icon variant)。
统一 focus ring、禁用态与命中尺寸;业务弹窗不得再用字体字符实现关闭/缩放/播放/移除控件
这里保留原生 title 作为可见提示而不包共享 Tooltip:弹窗打开时会 autofocus 首个可聚焦
控件(通常是关闭按钮),若该控件触发 Radix Tooltip,其 dismissable layer 会成为最高层并
抢占 Escape。关闭/缩放这类熟悉操作的名称已由 label 表达,无需额外 popup tooltip。
export function DialogIconButton(props: DialogIconButtonProps): React.JSX.Element;DialogIconButtonProps
export type DialogIconButtonProps = { label: string; tooltip?: string; icon: ReactNode; onClick: () => void; disabled?: boolean; pressed?: boolean; className?: string; testId?: string;};成员说明:
label:可访问名称(必填:icon-only 按钮必须有名称)。tooltip:非显而易见操作的补充提示。pressed:切换类操作的按下态(如静音、选帧)。testId:测试/定位用标识。
DialogInstance
一个已入栈弹窗实例的描述符(纯数据,可序列化)。
export type DialogInstance = { instanceId: string; dialogId: string; payload: unknown; parentInstanceId: string | null; dismissible: boolean; busy: boolean;};成员说明:
instanceId:稳定实例身份;异步回调据此忽略迟到结果。dialogId:注册的 dialog 类型。payload:通过 validator 的 payload。parentInstanceId:打开时 stack 顶部的实例;根弹窗为null。dismissible:是否允许 Escape / 遮罩 / 关闭按钮关闭。busy:busy 时禁止隐式关闭与重复确认。
DialogMediaWorkspace
共享媒体工作区 composition。
桌面为稳定的主媒体区 + 可选辅助区;窄屏降为单列。只负责结构与框高,不提升业务 state、 不读写媒体 intrinsic size,因此 Content 外框不随素材比例跳动。
export function DialogMediaWorkspace(props: { children: ReactNode; aside?: ReactNode; className?: string; }): React.JSX.Element;DialogRegistration
export type DialogRegistration = { definition: DialogDefinition; renderer?: DialogRenderer;};关联类型:DialogDefinition · DialogRenderer
DialogRenderer
export type DialogRenderer = ComponentType<DialogRendererProps>;关联类型:DialogRendererProps
DialogRendererProps
renderer 可用的关闭/busy 能力(由 Host 注入)。
export type DialogRendererProps = { instance: DialogInstance; requestClose: () => void; setBusy: (busy: boolean) => void; replace: (payload: unknown) => void;};关联类型:DialogInstance
成员说明:
requestClose:请求关闭当前实例(遵循 close policy)。setBusy:标记 busy。replace:替换当前实例 payload。
DialogSection
分区标题/内容。
export function DialogSection(props: { children: ReactNode; className?: string; }): React.JSX.Element;DialogSize
export type DialogSize = "sm" | "md" | "lg" | "fullscreen";DialogStage
媒体舞台:中性高对比 surface 上按 contain 呈现图片/视频,自身裁切平移/缩放。
label 提供可访问组名;媒体 token 只允许出现在此舞台与其叠层内(design D1)。
export function DialogStage(props: { children: ReactNode; className?: string; label?: string; }): React.JSX.Element;DialogSurface
单个弹窗 surface。
结构稳定是硬约束:
嵌套确认打开后父层从 top 退化为非 top;Radix Root 的 modal 变化会重挂内容,父弹窗的
草稿与滚动随之丢失。因此 Host 内始终渲染同一个 Radix Content(forceMount 保证父层
也留在 DOM),只由 aria-modal、遮罩点击与 dismiss 判定表达「是否为当前活动层」。
export function DialogSurface(props: DialogSurfaceProps): React.JSX.Element;关联类型:DialogSurfaceProps
DialogSurfaceContext
export const DialogSurfaceContext: React.Context<DialogSurfaceContextValue | null>;关联类型:Context · DialogSurfaceContextValue
DialogSurfaceContextValue
export type DialogSurfaceContextValue = { modal: boolean; dismissible: boolean; busy: boolean; requestClose: () => void; onOpenAutoFocus?: (event: Event) => void; onCloseAutoFocus?: (event: Event) => void;};成员说明:
requestClose:向 Host 发出一次 close request(是否真正关闭由 Host policy 决定)。onOpenAutoFocus:打开时把焦点移入(Host 按既有 initial-target 顺序)。onCloseAutoFocus:关闭后恢复焦点(Host 按 opener map / 画布 owner)。
DialogSurfaceProps
export type DialogSurfaceProps = { ariaLabel?: string; labelledBy?: string; describedBy?: string; className?: string; overlayClassName?: string; instanceId?: string; busy?: boolean; onOverlayClick?: () => void; children: ReactNode;};成员说明:
ariaLabel:可访问名称来源(至少 ariaLabel/labelledBy 之一,由上层校验)。className:Content(.dlg)class。overlayClassName:Overlay class(缺省.dlg__overlay)。instanceId:测试/定位用实例标识。busy:busy:aria-busy且禁止隐式关闭。onOverlayClick:standalone(无 Host)时点击遮罩的 close 回调。
DialogSurfaceRadixContentProps
type DialogSurfaceRadixContentProps = ComponentPropsWithoutRef<typeof DialogPrimitive.Content>;DialogSurfaceRoot
Host 侧的每个 stack layer Root。onOpenChange(false) 仅表示一次 close request;
Host 传入的实现负责 top identity/dismissible/busy 判定。
export function DialogSurfaceRoot(props: DialogSurfaceRootProps): React.JSX.Element;DialogSurfaceRootProps
export type DialogSurfaceRootProps = { open: boolean; onOpenChange: (open: boolean) => void; modal: boolean; dismissible?: boolean; busy?: boolean; onOpenAutoFocus?: (event: Event) => void; onCloseAutoFocus?: (event: Event) => void; children: ReactNode;};成员说明:
modal:只有 stack top 启用 modal/focus/dismiss 能力。
DialogTitle
可访问标题。
export function DialogTitle(props: { id?: string; children: ReactNode; }): React.JSX.Element;DialogToolbar
工具条(媒体缩放/播放等紧凑控件)。
export function DialogToolbar(props: { children: ReactNode; className?: string; label?: string; }): React.JSX.Element;DialogVariant
export type DialogVariant = "standard" | "alert" | "media" | "sheet";DialogsService
Dialog Service facade:stack/focus/busy/modal gate 与 owner-scoped registry。
export interface DialogsService extends DialogHostApi { getSnapshot(): DialogHostSnapshot; subscribe(listener: (snapshot: DialogHostSnapshot) => void): () => void; top(): DialogInstance | null; find(instanceId: string): DialogInstance | null; requestCloseTop(): DialogCloseResult; requestClose(instanceId?: string): DialogCloseResult; registerCloseGuard(dialogId: string, guard: DialogCloseGuard): () => void; getDiagnostic(): string | null; resolveRenderer(dialogId: string): DialogRenderer | null; resolveAlertAction(key: string | undefined): (() => Promise<{ ok: true; } | { ok: false; error: string; }>) | null; isModalActive(): boolean; registerDialog(dialogId: string, registration: DialogRegistration): () => void; registerAlertAction(key: string, action: () => Promise<{ ok: true; } | { ok: false; error: string; }>): () => void; registeredDialogIds(): string[]; registerOpenParticipant(participant: DialogOpenParticipant): () => void;}关联类型:DialogHostApi · DialogHostSnapshot · DialogInstance · DialogCloseResult · DialogCloseGuard · DialogRenderer · DialogRegistration · DialogOpenParticipant
成员说明:
requestClose:请求关闭(缺省顶部):统一走 dismissible / busy / close guard 判定, 不绕过 guard 直接关闭。registerCloseGuard:注册某类 Dialog 的关闭请求 guard(instance-scoped 调用);返回注销函数。registerDialog:注册 definition + 可选 renderer;重复 ID 抛错并要求调用方回滚。registerAlertAction:注册一个异步 alert action;返回注销函数。registerOpenParticipant:注册 Dialog open pre-commit participant。 在纯校验通过、stack 提交前同步运行;返回 false 时拒绝打开。返回注销函数。replace:替换指定实例(缺省为顶部)的 payload;instanceId 不匹配时不动作。close:关闭指定实例及其显式子孙;缺省关闭顶部。setBusy:更新 busy;已关闭实例的迟到调用被忽略(返回 false)。