# 遮罩 · Overlay

- 页面: https://jiguang132.com/zh/resources/astryx/docs/overlay
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

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

## 安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **遮罩 · 综合展示 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

```json
{
  "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.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt