遮罩#

mask 修饰符使用另一个视图的 透明度（alpha 通道） 作为遮罩，将目标视图按形状进行裁剪。遮罩中不透明的区域会显示目标视图，透明区域则被隐藏。

该修饰符常用于图像裁剪、聚光灯效果、遮挡与图形渐显等视觉表现中。

类型定义#

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

使用方式#

1. 简洁形式（默认居中遮罩）#

直接传入一个视图作为遮罩，系统默认使用居中对齐。

1<Image
2  filePath="path/to/photo.png"
3  frame={{ width: 100, height: 100 }}
4  mask={<Circle />}
5/>

上例中，图像将被裁剪成一个圆形，仅圆形区域可见，其他部分被遮罩隐藏。

2. 对象形式（带对齐方式）#

如果需要控制遮罩的位置，可使用对象形式指定对齐方式。

对象结构：#

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

可选对齐方式（Alignment）：#

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

示例：顶部对齐的矩形遮罩#

1<Rectangle
2  fill="blue"
3  frame={{ width: 100, height: 100 }}
4  mask={{
5    alignment: "top",
6    content: <Rectangle frame={{ width: 100, height: 50 }} />
7  }}
8/>

上述示例中，蓝色矩形的顶部一半区域可见，底部部分被遮罩隐藏。

行为说明#

• 遮罩视图的 透明度 决定了显示区域：

  • 完全不透明（alpha = 1）区域将显示原始内容；
  • 完全透明（alpha = 0）区域将被遮挡。

• 遮罩不会影响布局，仅影响视图渲染效果；

• 为了确保遮罩尺寸与对齐正确，建议对遮罩和目标视图都设置 frame={{ width, height }}。

常见用途#

• 图像裁剪（如圆形头像）
• 创建局部显示或聚焦效果
• 与动画结合实现遮罩揭示
• 仅显示特定形状区域内容

总结#