overlay#

overlay 修饰符用于在当前视图的上方叠加一个额外视图，形成层叠的视觉效果。这在添加装饰元素（如徽章）、加载指示器、半透明遮罩或交互按钮等场景中非常有用。

类型定义#

1overlay?: VirtualNode | {
2  alignment: Alignment
3  content: VirtualNode
4}

参数说明#

1. 简洁形式：直接传入 VirtualNode#

直接将一个视图叠加在当前视图之上，默认对齐方式为 居中（center）。

1<Image
2  imageUrl="https://example.com/avatar.png"
3  overlay={<Circle fill="black" opacity={0.2} />}
4/>

该例会在头像图上方添加一个半透明黑色圆形遮罩。

2. 对象形式：带对齐方式的 Overlay#

提供 content 和 alignment，用于指定叠加视图的内容与对齐方式。

对象结构：#

1{
2  alignment: Alignment
3  content: VirtualNode
4}

Alignment 可选值包括：#

• "top" | "bottom" | "leading" | "trailing"
• "topLeading" | "topTrailing" | "bottomLeading" | "bottomTrailing"
• "center"

示例：右上角徽章叠加#

1<Image
2  imageUrl="https://example.com/avatar.png"
3  overlay={{
4    alignment: "topTrailing",
5    content: <Circle
6      fill="red"
7      frame={{
8        width: 10,
9        height: 10
10      }}
11    />
12  }}
13/>

该例会在图像右上角叠加一个红色圆形小徽章。

行为说明#

• overlay 的内容会绘制在目标视图之上。
• 叠加内容不会改变原始视图的尺寸与布局。
• 若未设置 clip，叠加内容可能超出边界。

常见用途#

• 添加通知角标或状态徽章
• 显示加载指示器或遮罩层
• 高亮视图特定区域
• 显示动画图标或文字提示

示例：居中文字叠加#

1<Rectangle
2  fill="blue"
3  frame={{
4    width: 100,
5    height: 100
6  }}
7  overlay={{
8    alignment: "center",
9    content: <Text foregroundColor="white">你好</Text>
10  }}
11/>

该示例会在一个蓝色矩形中央叠加白色文字“你好”。

总结#

overlay 是构建多层 UI、实现状态标记、视觉效果叠加等的核心修饰符之一，可灵活组合使用，适配各种视觉需求。