Props

名称	类型	默认值	说明
showOn	OverlayShowOn	'always'	未绑定 isOpen 时遮罩的出现方式，完全由 CSS 驱动。always 一直可见；hover 在悬停或容器内获得焦点时出现；focus 只在容器内获得焦点时出现；hover-or-focus 是 hover 的别名。触屏设备上 hover 改成点按切换。
isOpen	boolean	-	由 JavaScript 控制的可见性，优先级高于 showOn 和点按切换。用 v-model:isOpen 绑定；不绑定时可见性交回 showOn。为 false 时遮罩不可见、并设为 inert，里面的按钮不会进入 Tab 顺序。
scrim	OverlayScrimMode	'dark'	遮罩的背景，同时决定遮罩内部内容使用哪一套表面语义。dark 和 light 分别让内部内容按深色、浅色表面取色；false 不画背景，内容保持页面当前主题。
position	OverlayPosition	'fill'	遮罩覆盖的范围。fill 铺满整块内容；bottom 和 top 是贴在一条边上的横条，出现和消失时从那条边滑进滑出。
align	OverlayAlign	'end'	内容在遮罩里的对齐方式。遮罩按列排布，所以这是水平方向：start 靠起始边，end 靠结束边，center 两轴居中。

插槽

名称	说明
default	底层内容：图片、视频、插画，或任何自带边界的区块。遮罩覆盖在它上面。
content	遮罩内部的内容。保持精简，一个按钮或一行标签就够了。不提供这个插槽时，组件只渲染底层内容，不会画出遮罩。

OverlayScrim

OverlayScrim 是遮罩本身的渲染组件，从 @astryx-vue/core/Overlay 导出，供 useOverlay 的使用者渲染遮罩。Overlay 内部用的就是它，属性含义与上表一致。

名称	类型	默认值	说明
scrim	OverlayScrimMode	'dark'	遮罩背景与内部内容使用的表面语义。
position	OverlayPosition	'fill'	遮罩覆盖的范围。
align	OverlayAlign	'end'	内容在遮罩里的对齐方式。
showOn	OverlayShowOn	'always'	未绑定 isOpen 时的出现方式。
isOpen	boolean	-	受控可见性。传入时忽略 showOn，并在为 false 时把遮罩设为 inert。

它的默认插槽就是遮罩内容，根元素上带有 data-position、data-align、data-scrim、data-visibility，主题可以据此定制；遮罩内部的内容包在一层 data-astryx-media="dark | light" 的代理元素里，它只负责切换表面语义，不影响布局。

useOverlay

useOverlay 给一个已经存在的容器加上同样的遮罩行为。选项与 Overlay 的属性同名，区别在于可以传 ref 或 computed 保持响应式。

名称	类型	说明
containerRef	Ref<HTMLElement | null>	挂到容器元素上，用 ref="containerRef"。
containerProps	ComputedRef<OverlayContainerProps>	容器需要的属性（作用域类名、点按切换处理），用 v-bind 挂上。它带来定位、裁剪，以及触屏下的点按切换。
scrimProps	ComputedRef<OverlayScrimProps>	传给渲染在容器内部的 OverlayScrim。
isOpen	ComputedRef<boolean | undefined>	遮罩实际使用的可见性：绑定的 isOpen、触屏点按的状态，或 undefined（此时由 CSS 决定）。
hasTouchToggle	ComputedRef<boolean>	当前是否处于"点按切换"状态（触屏设备 + hover 模式）。
toggle	() => void	翻转点按切换的状态。绑定 isOpen 时它不生效。

原生属性

根元素为 <div>。

以下内容传入根元素：

• HTML 属性。
• aria-* 属性。
• data-* 属性。
• class。
• style。

class 会与 astryx-overlay 合并，style 与组件自己写入的圆角合并。传入的点击处理与触屏点按切换会同时生效。