本文详解 CSS mask-position 属性的语法规则、坐标逻辑与常见误区，结合 radial-gradient 和 linear-gradient 实战案例，帮助开发者实现如左对齐半圆镂空、边缘渐隐、聚光灯等精确可控的遮罩效果。
本文详解 css `mask-position` 属性的语法规则、坐标逻辑与常见误区，结合 `radial-gradient` 和 `linear-gradient` 实战案例，帮助开发者实现如左对齐半圆镂空、边缘渐隐、聚光灯等精确可控的遮罩效果。
CSS 遮罩（mask）是一种强大的视觉控制机制，它不像 clip-path 那样仅裁剪形状，而是通过“蒙版图像”（如渐变或位图）定义元素的透明度分布——其中不透明区域显示内容，透明区域隐藏内容。而 mask-position 正是决定该蒙版图像相对于元素边界如何摆放的关键属性。
但需注意一个关键前提：mask-position 仅对独立的遮罩图像生效；当遮罩由 mask: radial-gradient(...) 这类简写声明直接内联定义时，mask-position 将被忽略——因为此时渐变的定位信息已内嵌在函数参数中（即 at <position></position>）。这也是你原始示例未生效的根本原因：
/* ❌ 无效：mask-position 对内联 radial-gradient 无作用 */
div {
mask: radial-gradient(20px, transparent 100%, black);
mask-position: left center; /* 被忽略 */
}✅ 正确做法是将定位信息直接写入 radial-gradient() 的 at 参数中：
/* ✅ 有效：在渐变函数内指定位置 */
div {
background: green;
mask: radial-gradient(50px at left center, transparent 100%, black);
/* 等价于：50px 半径的圆形遮罩，中心点锚定在元素左边缘 + 垂直居中处 */
}
body { background: pink; }<div style="width: 300px; height: 200px;"></div>
? mask-position 的定位逻辑解析
mask-position 的值遵循与 background-position 相同的语法规范，其默认参照盒为 border-box（可通过 mask-origin 修改）。支持以下形式：
立即学习“前端免费学习笔记（深入）”；
| 写法 | 含义 | 示例 |
|---|---|---|
| 单关键字 | 水平+垂直均设为该值（center 默认补全） |
mask-position: top; → top center
|
| 关键字组合 | 第一值为水平（left/center/right），第二值为垂直（top/center/bottom） |
mask-position: left center; |
| 百分比/长度 | 第一值为 X 偏移（从左起），第二值为 Y 偏移（从上起） | mask-position: 20% 50%; |
| 混合写法 | 关键字 + 数值（顺序仍为 X Y） | mask-position: left 30px; |
⚠️ 注意事项：
- 若使用多个遮罩层（逗号分隔的
mask-image列表），mask-position也需用逗号对应提供多个位置值； - Safari 等旧版 WebKit 浏览器需添加
-webkit-mask-position前缀； -
mask-position仅在mask-image显式声明为独立值时才生效（例如mask-image: url(mask.png)或mask-image: linear-gradient(...)），否则应优先使用渐变函数内的at语法。
? 实用技巧：三种典型定位场景
1. 左侧半圆镂空（你的需求）
.masked-left-half {
width: 300px; height: 200px;
background: #2ecc71;
mask: radial-gradient(
80px at left center,
transparent 0%,
black 100%
);
}→ at left center 将渐变中心锚定在元素左边界中点，半径 80px 覆盖左侧约 1/3 区域，形成自然“挖空”效果。
2. 右侧聚光灯（动态聚焦）
.spotlight-right {
mask: radial-gradient(
circle at right 20px center,
black 0%,
transparent 60%
);
}→ at right 20px center 表示从右边缘向内偏移 20px、垂直居中，适合模拟右侧光源照射。
3. 全向边缘渐隐（平滑融合背景）
.soft-edge {
mask: linear-gradient(
90deg,
transparent 0%,
black 15%,
black 85%,
transparent 100%
);
/* 注意：此处无需 mask-position —— 线性渐变默认铺满，若需偏移可用： */
/* mask-position: 10% center; mask-size: 120% 100%; */
}✅ 总结：何时用 mask-position？何时用 at？
| 场景 | 推荐方案 | 原因 |
|---|---|---|
| 使用外部 PNG/SVG 遮罩图 | ✅ mask-image: url(...); mask-position: left top;
|
图像需独立定位 |
使用 linear-gradient 或 radial-gradient
|
✅ 渐变函数内写 at <position></position>
|
更直观、更可靠、兼容性更好 |
| 多层遮罩（如渐变+图片叠加） | ✅ 组合使用：mask-image: linear-gradient(...), url(...); mask-position: center, right top;
|
各层可独立控制位置 |
掌握 mask-position 与渐变 at 语法的分工与协作，是实现专业级 CSS 遮罩效果的基础。记住核心原则：定位信息越靠近数据源（即渐变函数本身），控制越精准、行为越可预测。
