跳转到内容

前端 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

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

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)。