Dialog 对话框

浮在页面之上的一层，通常需要用户处理完成后才能回到页面。

HeadlessStylesVueReactWeb Components

用法

不传 open 即为非受控；Esc 或点击遮罩关闭，关闭后焦点回到触发按钮

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

组件结构

加粗的是必需部件。

data-scope="dialog"：trigger · backdrop · positioner · content · header · drag-trigger · indicator · title · description · body · footer · confirm-trigger · cancel-trigger · close-trigger

示例

受控

传入 open 后由宿主决定，组件自身不再修改状态；Esc、点击遮罩、按关闭按钮都只回写 open

当前：收起

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

警示对话框

role=alertdialog 交给读屏更强的语气；关闭 Esc 与点击遮罩后，只剩内部两个按钮可以离开

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

尺寸

size 写为 content 的 data-size，只改变面板的最大宽度；三档各自一个对话框，打开后才可见宽窄差异

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

头尾固定、正文滚动

header / body / footer 把面板切为三段：头与尾固定在原处，只有正文一段滚动

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

异步确认

提交期间按钮显示加载，Esc 与点击遮罩两条出口一并封闭，落定之后才把 open 写回 false

项目状态：未归档

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

命令式确认框

一次函数调用把描述符推入表中并展开对话框；返回的对象随后可修改标题、正文与按钮状态，表中即当前所有实例

描述符表：（空）

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

可拖动

draggable 让标题栏成为拖动区，面板始终夹在视口内；标题栏里的拖动把手让键盘也能挪：方向键挪一步，Enter 回到居中

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

命令式服务

createDialogService 的 confirm 与单按钮预设：一行调用弹出，onOk 返回 Promise 时确认按钮自动 pending 并阻止关闭；多次调用排队依次弹出

上次答复：（还没问过）

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

props 写法

不写结构时按标准结构铺：标题、说明与触发器文字三项写出一个确认对话框；确认动作返回 Promise 时等它落定才收起，期间确定钮转圈

项目状态：未归档

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

设计指引

何时使用

• 需要用户做出决定且不能忽略（确认删除、填写必要信息）。
• 一段独立的子任务，完成后回到原处。

何时不用

• 只提示一条结果时，使用通知的轻提示预设。
• 内容是页面主流程的一部分时，直接展开在页面内。
• 内容很长或是完整表单时，使用抽屉或单独页面。

特性

• modal 决定是否锁住下层：非模态不创建遮罩，页面仍可点击、聚焦和滚动；展开期间切换会同步更新这些约束。
• 焦点进入时落在 initialFocus；没给时落在内容里第一个可聚焦的控件上，越过关闭钮与拖动把手（除它们之外没有可聚焦的才落在关闭钮上），alertdialog 落在内容容器本身。关闭后归还触发器。
• role 写成 alertdialog 时内容是警示对话框：读屏用更强的语气，点外面不关。Web Components 侧的属性是 dialog-role：role 是 HTML 全局属性，写在宿主上宿主本身就成了对话框，连同里面的触发钮。
• closeOnEscape 与 closeOnInteractOutside 可分别关闭，避免填写中的表单因误点外部而丢失。
• 内容区可以内部滚动。Body 是模态滚动面：滚到头不带动页面，内容高度变化时保留稳定的滚动条空道。
• draggable 让面板可以挪走：指针按住标题栏（header，没写 header 时是 title）即跟手，落在标题栏里的按钮、链接与表单控件照常点；面板四边始终夹在视口内，每次打开都从居中落点起。键盘经 drag-trigger 挪：它是一块透明的把手，放在 header 里时铺满标题栏，焦点落在它上面时方向键挪一步（10px）、Shift 挪一大步（50px）、Enter / Space 回到居中；初始焦点越过它，落到第一个真正的控件上。位移写成 content 上的两个私有槽、按 transform 平移，与进出场的 translate / scale 叠加，拖过的面板从拖到的位置退场。Web Components 侧的属性是 panel-draggable：draggable 是 HTML 全局属性，写在宿主上会把它变成原生拖放源。
• 面板走 sheet 三件套（1px 描边、不透明底、lg 档投影），sheet 圆角 10px，不叠渐变与顶光。分三段时头部是一条 48px 的带（紧凑档 44px），横向内衬 20px；正文纵 24 横 20，尾段纵 16 横 20；头下、尾上各一条贴边的 1px 内部分隔线。不分三段时标题行同样落在顶上那条 48px 带的中线上。触发器与关闭按钮走 Action Control 家族配方：触发器为 text 档中性描边，关闭按钮为 icon 档 ghost 面，悬停与按下沿画布承载阶梯换底，Space / Enter 与触屏按住期间投影 data-pressed。关闭钮的叉 12px，距右 16px、落在头部带的中线上。标题取页面级面板标题档（heading-3）、正文色，说明文字为 13px 说明档。
• 关闭时内容立即失活并退出可访问树，内容与遮罩的有限退场动画全部完成后再释放模态资源，并发出 onExitComplete / exit-complete。重开撤销旧退出，卸载立即清理。
• 内容第一次打开才挂载，缺省在退场动画播完后卸载、下次打开重新挂载。反复开合而内容又重时（设置面板、长表单）把 unmountOnExit 设为 false：打开过之后收起只隐藏——定位层以内联 display: none 收起、遮罩不留、Portal 视觉桥断开——面板里的组件状态、输入与滚动位置都留着，再打开不必重挂。Web Components 的作者节点一向常驻；写进 content 里一个 <template> 的内容按同一规则挂卸：第一次打开克隆，缺省退场播完撤走，unmount-on-exit="false" 时克隆一次之后常驻。
• 不写子内容时按标准结构铺：title、description 与触发器文字给出页头与触发器（Vue 是 trigger-text，React 是 trigger，Web Components 是 title-text、description、trigger-text 三个属性），页脚铺取消与确定两颗钮；actions 换成只有确定（alert）或不铺（none），confirmText / cancelText 改字，缺省取语言包里 translations.dialog 的 ok / cancel。正文与整段页脚经 body、footer 插槽给出（React 是同名属性，Web Components 是 slot="body" / slot="footer" 的节点）。一个组件加三个 prop 就是一个确认对话框。
• 确定钮发 confirm：onConfirm 返回 Promise 时对话框等它兑现才收起、确定钮转圈，期间 Escape 与点外面关不掉，拒绝则留在原地并发 confirm-error（Web Components 把异步动作交给 confirmAction 属性，confirm 事件只作通知）。取消钮发 cancel-press 并收起；关闭钮随时收得起，挂起中的确认随之作废。手写部件时 XhDialogConfirmTrigger / XhDialogCancelTrigger 是同一对按钮，组合写法照旧。
• 另有命令式服务，业务代码一次调用即可弹出。
• 命令式服务与声明式组件共用 Header / Body / Footer 三段：标题和徽记在 Header，字符串、函数正文及取值表单在 Body，操作按钮在 Footer。长内容只滚动 Body，头尾保留在面板内。
• 命令式服务的 onOk 返回 false 只阻止关闭；同步抛错或 Promise 拒绝会保持对话框打开，设置独立 service.actionError 并触发 onActionError({ cause })。cause 保留原始异常，不直接转成用户提示。
• 失败提示与确定 / 取消钮缺省取语言包里 translations.dialog 的 actionError / ok / cancel（服务 config 里的语言包，自定义元素侧取宿主所在处的全局配置），个别服务用 actionErrorText / okText / cancelText 覆盖：Vue 支持字符串/ref/getter，React 支持字符串/getter，Web Components 使用字符串，与各端按钮文案合同一致；提示位于 Body 的 role=alert 实时区。重试先清理旧异常，关闭或切换请求后旧 Promise 不再写回。
• 服务宿主或函数正文渲染失败会拒绝所属请求，onActionError 通知自身失败也会拒绝所属请求；业务需要处理返回 Promise 的拒绝。显式 target 必须是当前文档中已经连接的元素，无法展示时不会解析为取消或永久等待。

组合

• 内容区放滚动区域；按钮行使用按钮组；轻量确认场景改用弹出确认。

最佳实践

• 标题说明本次要做什么，不写“提示”。
• 确认按钮的文字写具体动作（“删除”），不写“确定”。
• 破坏性操作使用危险语气，并让取消成为默认焦点。

反模式

• 在对话框内再打开对话框。
• 内部有未保存的输入却允许点击外部关闭。

API 参考

产物

层	值
自定义元素	<xh-dialog>
Vue 组件	XhDialogBody XhDialogCancelTrigger XhDialogCloseTrigger XhDialogConfirmTrigger XhDialogContent XhDialogDescription XhDialogDragTrigger XhDialogFooter XhDialogHeader XhDialogIndicator XhDialogRoot XhDialogTitle XhDialogTrigger
组合式函数	useDialog
状态机	dialogMachine
皮肤	@xihan-ui/styles/dialog.css

Props

属性	类型	必填	说明
open	boolean
defaultOpen	boolean
modal	boolean
role	'dialog' | 'alertdialog'
closeOnEscape	boolean
closeOnInteractOutside	boolean
restoreFocus	boolean
initialFocus	string		展开后先聚焦到 content 内匹配该选择器的元素；选择器不匹配时回退为默认聚焦顺序。
size	Size		尺寸：sm / md / lg。只影响 content 的最大宽度，写在 content 上（本组件没有 root 部件）。
variant	OverlayBackdropVariant		遮罩形态：opaque / blur / transparent。写在 backdrop 上，只影响该层的底色与模糊。
draggable	boolean		可拖动：指针按住标题栏（header，没有 header 时是 title）或 drag-trigger 把面板挪走， 键盘在 drag-trigger 上用方向键挪；面板始终夹在视口内。默认 false。每次打开都从居中落点起。
unmountOnExit	boolean		收起动画播完后卸载内容，默认 true。内容总是第一次打开才挂载；设为 false 时此后收起只隐藏、不卸载， 再打开不重挂：内容里的组件状态、输入与滚动位置都留着，重开也不再付一遍挂载开销。 适合反复开合、内容又重（设置面板、长表单）的浮层。
parts	TitleDescriptionParts		作者实际渲染了哪些部件，由适配器统计；省略即按都在场处理（服务端直出与挂载前）。 title 不在场时 content 不写 aria-labelledby，名字由作者在 content 上写 aria-label； description 不在场、或渲染了但读不出一句话（判断同 hasNamingContent）时不写 aria-describedby。
translations	Partial<DialogTranslations>
onOpenChange	(details: DialogOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。
onExitComplete	() => void		退出动画结束或取消，且本层资源全部释放后通知；卸载和重新打开不通知。

事件

自定义元素将载荷放在 detail；Vue 使用同名 emit。

事件	载荷	说明
confirm	CustomEvent	点了确定钮；随后收起。异步门经 confirmAction 属性：事件拿不到监听函数的返回值， 给元素赋 confirmAction = () => thenable 即挂起确认门，confirm 事件照发只作通知
confirm-error	CustomEvent	确认动作同步抛出或 thenable 拒绝；detail 为 { cause }，保留原始原因
cancel-press	CustomEvent	点了取消钮；随后收起。Escape、层外交互与关闭钮只发 open-change
exit-complete	CustomEvent	退出完成且本层资源已释放
open-change	DialogOpenChangeDetails	open 状态变化；detail 为 { open: boolean }

插槽

仅列出带载荷的插槽。

Vue 组件	插槽	载荷	说明
XhDialogRoot	default	DialogRootSlotProps
XhDialogRoot	trigger	—	触发按钮的内容，压过 trigger-text。
XhDialogRoot	title	—	标题，压过 title。
XhDialogRoot	description	—	说明，压过 description。
XhDialogRoot	body	—	正文：面板里唯一会滚动的段。
XhDialogRoot	footer	—	整段页脚：写了它，取消与确定两颗钮不再代铺。

React 适配器 props

只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。

React 组件	属性	类型	必填	说明
XhDialogContent	container	() => Element | null		浮层挂载的容器；未提供时按全局配置，再未提供时挂载到 body。
XhDialogRoot	trigger	ReactNode		触发按钮的内容。不给时不铺触发器，开合交给受控的 open。
XhDialogRoot	title	ReactNode		标题。
XhDialogRoot	description	ReactNode		标题下的说明。
XhDialogRoot	body	ReactNode		正文：面板里唯一会滚动的段。
XhDialogRoot	footer	ReactNode		整段页脚：给了它，取消与确定两颗钮不再代铺。
XhDialogRoot	actions	DialogStructureActions		页脚铺哪几颗钮：confirm（取消 + 确定，缺省）、alert（只有确定）、none。
XhDialogRoot	confirmText	string		确定钮的文字，缺省取语言包。
XhDialogRoot	cancelText	string		取消钮的文字，缺省取语言包。
XhDialogRoot	onConfirm	DialogActionIntents['onConfirm']		点了确定钮。返回 thenable 即挂起：面板等它兑现才收起、确定钮转圈， 拒绝则保持打开并经 onConfirmError 报告。同步返回照常立即收起。
XhDialogRoot	onConfirmError	DialogActionIntents['onConfirmError']		确认回调同步抛出或 thenable 拒绝；details.cause 是原始原因。
XhDialogRoot	onCancelPress	DialogActionIntents['onCancelPress']		点了取消钮，随后面板收起。Escape、层外交互与关闭钮不发它。
XhDialogRoot	children	SlotChildren<DialogRootSlotProps>

状态

公开状态写入 data-state。

部件	取值
trigger	'open' | 'closed'
backdrop	'open' | 'closed'
positioner	'open' | 'closed'
content	'open' | 'closed'

以下名称仅用于内部状态机。

状态：open · closed

事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · PRESS.START · PRESS.END · DRAG.START · DRAG.NUDGE · DRAG.RESET · GESTURE.MOVE · GESTURE.END

判据：isOpenControlled · canDrag

connect API

getXxxProps() 返回对应部件的宿主属性。

成员	类型	说明
open	boolean
offset	DialogOffset	当前的拖动位移。
dragging	boolean	正在被指针拖动。
pending	boolean	异步确认进行中：确认钮转圈、再次点击无效，Escape 与层外交互不收起面板。
actionError	DialogConfirmErrorDetails | null	最近一次确认动作的错误；新确认或取消时清空。
setOpen	(next: boolean) => void	确认异步挂起期间，收起只能经取消钮或关闭钮：程序与触发器的 setOpen(false) 无效。
confirm	() => void	发出确认意图，确认落定后收起；异步确认挂起期间再次调用无效。
cancel	() => void	发出取消意图并收起；挂起中的确认作废。
getTriggerProps	() => T['button']
getBackdropProps	() => T['element']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getHeaderProps	() => T['element']
getDragTriggerProps	() => T['button']	拖动把手：键盘挪动面板的入口；放在 header 里时铺满标题栏。
getIndicatorProps	() => T['element']
getTitleProps	() => T['element']
getDescriptionProps	() => T['element']
getBodyProps	() => T['element']
getFooterProps	() => T['element']
getConfirmTriggerProps	() => T['button']	确认钮：页脚的主动作，solid；异步确认挂起时转圈。
getCancelTriggerProps	() => T['button']	取消钮：页脚的次要出口，outline。
getCloseTriggerProps	() => T['button']
isContentMounted	(present: boolean) => boolean	浮层此刻该不该挂载。present 是适配器的退场闸门：打开中或收起动画还没播完为真。 没打开过恒为假；unmountOnExit 为 false 时打开过之后恒为真，闸门落下的那段由适配器隐藏而不卸载。

无障碍

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	focus in trigger	打开对话框并把焦点移入 content
Escape	open	关闭并把焦点还给 trigger
Tab	open	在 content 内向后循环焦点
Shift+Tab	open	在 content 内向前循环焦点
Enter / Space	held in trigger / close-trigger	按住期间该按钮投影 data-pressed，与指针 :active 同一副按压面；抬起、失焦或面板收起撤下
ArrowUp / ArrowDown / ArrowLeft / ArrowRight	focus in drag-trigger, draggable	按屏幕方向把面板挪一步（10px），夹在视口内；方向是物理键位，RTL 下不对调
Shift+ArrowUp / Shift+ArrowDown / Shift+ArrowLeft / Shift+ArrowRight	focus in drag-trigger, draggable	按大步长挪（50px）
Enter / Space	focus in drag-trigger, draggable	把面板送回居中落点

ARIA

以下属性由 connect 生成。

部件	属性	值
trigger	aria-controls	content 部件的 id
trigger	aria-expanded	'true' | 'false'
trigger	aria-haspopup	'dialog'
content	aria-describedby	description 部件的 id | undefined
content	aria-hidden	!open || undefined
content	aria-labelledby	title 部件的 id | undefined
content	aria-modal	'true' | 'false'
content	role	props.role
drag-trigger	aria-disabled	'false' | 'true'
drag-trigger	aria-label	translations.dragTrigger
indicator	aria-hidden	'true'
confirm-trigger	aria-busy	'true' | undefined
confirm-trigger	aria-disabled	'true' | undefined
close-trigger	aria-label	translations.close

样式参考

皮肤

@xihan-ui/styles/dialog.css 按 [data-scope="dialog"][data-part="trigger"] 部件选择器书写，发布产物以挂载类 .xh-scope-dialog 代替其中的 data-scope（特异性相同），位于 xihan.components 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。

forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。

数据属性

由 connect 生成；条件不成立时不输出无值属性。

部件	属性	值
trigger	data-pressed	''（条件成立时才出现）
trigger	data-state	'open' | 'closed'
trigger	data-xh-action-control	''
trigger	data-xh-action-display	'always'
trigger	data-xh-action-profile	'text'
trigger	data-xh-action-size	'md'
trigger	data-xh-action-variant	'outline'
backdrop	data-instant	''（条件成立时才出现）
backdrop	data-state	'open' | 'closed'
backdrop	data-variant	props.variant
positioner	data-positioned	''
positioner	data-state	'open' | 'closed'
content	data-draggable	''（条件成立时才出现）
content	data-dragging	''（条件成立时才出现）
content	data-instant	''（条件成立时才出现）
content	data-size	props.size
content	data-state	'open' | 'closed'
header	data-draggable	''（条件成立时才出现）
drag-trigger	data-disabled	''（条件成立时才出现）
drag-trigger	data-dragging	''（条件成立时才出现）
title	data-draggable	''（条件成立时才出现）
confirm-trigger	data-loading	''（条件成立时才出现）
confirm-trigger	data-pressed	''（条件成立时才出现）
confirm-trigger	data-xh-action-control	''
confirm-trigger	data-xh-action-display	'always'
confirm-trigger	data-xh-action-profile	'text'
confirm-trigger	data-xh-action-size	'md'
confirm-trigger	data-xh-action-variant	'solid'
confirm-trigger	data-xh-ink-surface	''
confirm-trigger	data-xh-loading-ring	'overlay'
cancel-trigger	data-pressed	''（条件成立时才出现）
cancel-trigger	data-xh-action-control	''
cancel-trigger	data-xh-action-display	'always'
cancel-trigger	data-xh-action-profile	'text'
cancel-trigger	data-xh-action-size	'md'
cancel-trigger	data-xh-action-variant	'outline'
close-trigger	data-pressed	''（条件成立时才出现）
close-trigger	data-xh-action-control	''
close-trigger	data-xh-action-display	'always'
close-trigger	data-xh-action-profile	'icon'
close-trigger	data-xh-action-size	'sm'
close-trigger	data-xh-action-variant	'ghost'

CSS 变量

本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。

变量	部件	CSS 属性	状态	默认来源	说明
--xh-dialog-backdrop-bg	backdrop	background	default	--xh-bg-overlay	dialog 的 backdrop 部件 background 覆盖槽。
--xh-dialog-backdrop-blur	backdrop	-webkit-backdrop-filter backdrop-filter	variant=blur	--xh-overlay-backdrop-blur	dialog 的 backdrop 部件 -webkit-backdrop-filter、backdrop-filter 覆盖槽。
--xh-dialog-backdrop-filter	backdrop content	-webkit-backdrop-filter backdrop-filter	default variant=blur	--xh-dialog-backdrop-blur --xh-material-elevated-backdrop	dialog 的 backdrop、content 部件 -webkit-backdrop-filter、backdrop-filter 覆盖槽。
--xh-dialog-backdrop-layer	backdrop	z-index	default	--xh-_layer	dialog 的 backdrop 部件 z-index 覆盖槽。
--xh-dialog-bg	content	background	default	--xh-material-elevated-bg	dialog 的 content 部件 background 覆盖槽。
--xh-dialog-body-px	body	padding-inline	default	--xh-overlay-sheet-px	dialog 的 body 部件 padding-inline 覆盖槽。
--xh-dialog-body-py	body	padding-block	default	--xh-overlay-sheet-body-py	dialog 的 body 部件 padding-block 覆盖槽。
--xh-dialog-border	content	border	default	--xh-material-elevated-border	dialog 的 content 部件 border 覆盖槽。
--xh-dialog-close-bg-active	close-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-bg-pressed	dialog 的 close-trigger 部件 background-color 覆盖槽。
--xh-dialog-close-bg-focus	close-trigger	background-color	focus-visible	--xh-_action-variant-bg-focus-visible	dialog 的 close-trigger 部件 background-color 覆盖槽。
--xh-dialog-close-bg-hover	close-trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-_action-variant-bg-hover	dialog 的 close-trigger 部件 background-color 覆盖槽。
--xh-dialog-close-fg	close-trigger	color	default	--xh-fg-muted	dialog 的 close-trigger 部件 color 覆盖槽。
--xh-dialog-close-fg-focus	close-trigger	color	focus-visible	--xh-dialog-close-fg-hover	dialog 的 close-trigger 部件 color 覆盖槽。
--xh-dialog-close-fg-hover	close-trigger	color	disabled focus-visible hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-fg-focus-visible --xh-_action-variant-fg-hover --xh-_action-variant-fg-pressed	dialog 的 close-trigger 部件 color 覆盖槽。
--xh-dialog-close-radius	close-trigger	border-radius	default	--xh-shape-control	dialog 的 close-trigger 部件 border-radius 覆盖槽。
--xh-dialog-close-size	close-trigger content title	block-size inline-size inset-block-start padding-inline-end	default has([data-scope='dialog'][data-part='close-trigger']) xh-action-profile=icon	--xh-_action-profile-visual-size --xh-control-h-sm	dialog 的 close-trigger、content、title 部件 block-size、inline-size、inset-block-start、padding-inline-end 覆盖槽。
--xh-dialog-content-backdrop-filter	content	-webkit-backdrop-filter backdrop-filter	default	--xh-dialog-backdrop-filter	dialog 的 content 部件 -webkit-backdrop-filter、backdrop-filter 覆盖槽。
--xh-dialog-description-fg	description	color	default	--xh-fg-muted	dialog 的 description 部件 color 覆盖槽。
--xh-dialog-description-font-size	description	font-size	default	--xh-text-secondary-size	dialog 的 description 部件 font-size 覆盖槽。
--xh-dialog-drag-trigger-min-h	drag-trigger	min-block-size	default	--xh-space-6	dialog 的 drag-trigger 部件 min-block-size 覆盖槽。
--xh-dialog-drag-trigger-radius	drag-trigger	border-radius	default	--xh-shape-control	dialog 的 drag-trigger 部件 border-radius 覆盖槽。
--xh-dialog-fg	content	color	default	--xh-material-elevated-fg	dialog 的 content 部件 color 覆盖槽。
--xh-dialog-footer-gap	footer	gap	default	--xh-control-gap-md	dialog 的 footer 部件 gap 覆盖槽。
--xh-dialog-footer-pt	footer	padding-block-start	default	--xh-space-2	dialog 的 footer 部件 padding-block-start 覆盖槽。
--xh-dialog-footer-px	content footer	padding-inline	has([data-scope='dialog'][data-part='body'])	--xh-overlay-sheet-px	dialog 的 content、footer 部件 padding-inline 覆盖槽。
--xh-dialog-footer-py	content footer	padding-block	has([data-scope='dialog'][data-part='body'])	--xh-overlay-sheet-footer-py	dialog 的 content、footer 部件 padding-block 覆盖槽。
--xh-dialog-gap	content	gap	default	--xh-stack-gap-md	dialog 的 content 部件 gap 覆盖槽。
--xh-dialog-header-gap	header	gap	default	--xh-stack-gap-sm	dialog 的 header 部件 gap 覆盖槽。
--xh-dialog-header-pb	content header	padding-block-end	default has([data-scope='dialog'][data-part='body'])	--xh-_dialog-header-pb --xh-space-2	dialog 的 content、header 部件 padding-block-end 覆盖槽。
--xh-dialog-header-pt	content header	padding-block-start	has([data-scope='dialog'][data-part='body'])	--xh-_dialog-header-pt	dialog 的 content、header 部件 padding-block-start 覆盖槽。
--xh-dialog-header-px	content header	padding-inline	has([data-scope='dialog'][data-part='body'])	--xh-overlay-sheet-px	dialog 的 content、header 部件 padding-inline 覆盖槽。
--xh-dialog-icon-size	close-trigger content trigger	--xh-icon-size	default	--xh-_action-profile-glyph-size --xh-glyph-size-md --xh-glyph-size-xs	dialog 的 close-trigger、content、trigger 部件 --xh-icon-size 覆盖槽。
--xh-dialog-indicator-bg	indicator	background	default	--xh-_tone-subtle	dialog 的 indicator 部件 background 覆盖槽。
--xh-dialog-indicator-fg	indicator	color	default	--xh-_tone-fg	dialog 的 indicator 部件 color 覆盖槽。
--xh-dialog-indicator-mark-size	indicator	--xh-icon-size	default	--xh-dialog-indicator-size	dialog 的 indicator 部件 --xh-icon-size 覆盖槽。
--xh-dialog-indicator-radius	indicator	border-radius	default	--xh-shape-circle	dialog 的 indicator 部件 border-radius 覆盖槽。
--xh-dialog-indicator-size	indicator	--xh-icon-size block-size inline-size	default	--xh-glyph-size-md	dialog 的 indicator 部件 --xh-icon-size、block-size、inline-size 覆盖槽。
--xh-dialog-layer	positioner	z-index	default	--xh-_layer	dialog 的 positioner 部件 z-index 覆盖槽。
--xh-dialog-max-w	content	max-inline-size	default	--xh-_dialog-max-w	dialog 的 content 部件 max-inline-size 覆盖槽。
--xh-dialog-positioner-padding	positioner	padding-block-end padding-block-start padding-inline	default	--xh-space-4	dialog 的 positioner 部件 padding-block-end、padding-block-start、padding-inline 覆盖槽。
--xh-dialog-px	content	padding-inline	default	--xh-overlay-sheet-px	dialog 的 content 部件 padding-inline 覆盖槽。
--xh-dialog-py	content	padding-block-end padding-block-start	default	--xh-_dialog-header-pt --xh-overlay-sheet-body-py	dialog 的 content 部件 padding-block-end、padding-block-start 覆盖槽。
--xh-dialog-radius	content	border-radius	default	--xh-shape-sheet	dialog 的 content 部件 border-radius 覆盖槽。
--xh-dialog-separator	content footer header	border-block-end border-block-start	has([data-scope='dialog'][data-part='body']) has([data-scope='dialog'][data-part='footer'])	--xh-material-elevated-separator	dialog 的 content、footer、header 部件 border-block-end、border-block-start 覆盖槽。
--xh-dialog-shadow	content	box-shadow	default	--xh-material-elevated-shadow	dialog 的 content 部件 box-shadow 覆盖槽。
--xh-dialog-title-fg	title	color	default	--xh-fg-default	dialog 的 title 部件 color 覆盖槽。
--xh-dialog-title-font-size	title	font-size	default	--xh-text-heading-3-size	dialog 的 title 部件 font-size 覆盖槽。
--xh-dialog-title-font-weight	title	font-weight	default	--xh-text-heading-3-weight	dialog 的 title 部件 font-weight 覆盖槽。

动效

动效角色：按压 · 状态 · 出现（面板） · 循环（见动效规范）。

共享关键帧 xh-fade-in · xh-fade-out · xh-sheet-in · xh-sheet-out 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立；状态切换走 transition，属性由 transition-* 分项给定。时长与缓动读动效令牌，改令牌即改全局节奏。

皮肤之外还有一段：退场由适配器的退场闸门把关，动画播完才真收起。

系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。

RTL

皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。