遮罩 · Overlay

遮罩用于浮层与提示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

遮罩 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
遮罩 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
遮罩 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Overlay

Overlay layers action or supporting content over media, cards, video, or other bounded surfaces with an optional scrim and reveal behavior.

属性	类型	默认值	说明
content *	ReactNode		Content rendered inside the overlay scrim.
children	ReactNode		Base content such as an image, video, card, or media surface that the overlay sits on top of.
showOn	'hover' \| 'always' \| 'focus' \| 'hover-or-focus'	'always'	Visibility trigger. Hover mode also reveals on focus for keyboard accessibility; hover-or-focus is an alias for hover.
isOpen	boolean		Controlled visibility override. When set, this takes precedence over showOn and touch toggle behavior.
scrim	'dark' \| 'light' \| false	'dark'	Scrim background mode. Set to false to render overlay content without a scrim background.
position	'fill' \| 'bottom' \| 'top'	'fill'	Where the scrim appears within the base surface.
align	'start' \| 'center' \| 'end'	'end'	Alignment of the overlay content within the scrim.
xstyle	StyleXStyles		StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.
className	string		CSS class name(s) appended to the root element. Prefer xstyle for styling when possible.
style	React.CSSProperties		Inline styles applied to the root element. Prefer xstyle for design-system styling.
ref	Ref<HTMLDivElement>		Ref forwarded to the overlay root element.

使用建议

Use overlays for short, contextual actions or labels that belong directly to the underlying media or surface.
Keep overlay content compact so it remains legible over the scrim and does not obscure important visual information.
避免：Do not use Overlay for floating content anchored outside the surface. Use Popover, Tooltip, or Dialog for those patterns.

主题 API

{
  "targets": [
    {
      "className": "astryx-overlay"
    },
    {
      "className": "astryx-overlay-scrim",
      "visualProps": [
        "position"
      ]
    }
  ]
}

组件结构

Base content: The media, card, or bounded surface that the overlay sits on top of.
Scrim: Optional dark or light overlay background that improves content contrast.
Overlay content: Actions, labels, or supporting content rendered above the base surface.