Android View 阴影（Elevation）完整参数与效果说明

ChatGPT 5 Pro 输出

View 系统里“能动阴影”的所有开关：每个参数/方法是什么、调大/调小会发生什么、以及如何组合它们把设计稿（Figma/Sketch 的 X、Y 偏移、模糊半径、颜色/透明度）还原。示例默认 API 28+（Android 9 起支持彩色阴影）。

---

0) 心智模型：Android 硬件阴影由两部分组成

• Ambient（环境光阴影）：均匀、四周发散，用来“托起”元素。
• Spot（点光源阴影）：有方向性，会偏移，决定“朝哪边拉长”。

最终的阴影不透明度：

最终不透明度 = f(高度Z) × 阴影颜色的 Alpha × 主题里的 shadowAlpha（ambient/spot）。

---

1) 参数/方法字典（作用 + 调节方向）

A. 几何与强度

view.elevation = 8f       // 静态Z：越大阴影越大、越软、偏移更明显
view.translationZ = 4f    // 动态Z：动画/按压使用

• elevation/translationZ 越大 → 阴影更大、更软、更偏移。

B. 颜色与透明度

view.setOutlineAmbientShadowColor(Color.parseColor("#33000000"))
view.setOutlineSpotShadowColor(Color.parseColor("#33000000"))

• 颜色 alpha 越高 → 阴影越深。
• 颜色 alpha 越低 → 阴影越淡。

C. 主题全局参数

<item name="android:ambientShadowAlpha">0.08</item>
<item name="android:spotShadowAlpha">0.25</item>

• 调高值：全局阴影变深
• 调低值：全局阴影变浅

D. 形状与裁剪

view.outlineProvider = object : ViewOutlineProvider() {
    override fun getOutline(v: View, outline: Outline) {
        outline.setRoundRect(0, 0, v.width, v.height, 16f)
    }
}
(view.parent as ViewGroup).clipChildren = false
(view.parent as ViewGroup).clipToPadding = false

• Outline 决定阴影形状
• 关闭 clip 才能显示完整阴影

E. 系统级全局参数（仅系统可调）

renderer.setLightSourceAlpha(0.08f /*ambient*/, 0.28f /*spot*/);
renderer.setLightSourceGeometry(
    displayWidth / 2f - windowLeft,
    0f - windowTop,
    dp2px(600),    // 光源Z：越低，阴影越拉长
    dp2px(800)     // 半径：越大越软，越小越硬
);

---

2) 快速效果对照表

想要的效果	参数	调整方向	备注
更深	outline*ShadowColor alpha / shadowAlpha	↑	提高透明度或主题alpha
更浅	同上	↓	降低透明度
拉长	elevation / 光源z	↑ / ↓	Z高拉长、z低全局拉长
更软	光源radius	↑	阴影更模糊
更硬	光源radius	↓	阴影边缘锐利

---

3) UI 还原流程

1. 系统侧先设光源位置、radius、alpha（整体风格）。
2. 控件层用 outline 设形状。
3. 颜色层改 outlineAmbientShadowColor/SpotShadowColor。
4. 尺寸层用 elevation 调模糊与偏移。
5. 必要时主题 shadowAlpha 全局微调。

---

4) 典型代码示例

控件局部自定义（API 28+）

view.elevation = 12f
view.setOutlineAmbientShadowColor(0x33000000)
view.setOutlineSpotShadowColor(0x33000000)

系统级统一风格（有权限）

HardwareRenderer renderer = ...;
renderer.setLightSourceGeometry(
    displayWidth / 2f - windowLeft,
    0f - windowTop,
    dp2px(600),
    dp2px(800)
);
renderer.setLightSourceAlpha(0.04f, 0.19f);

---

5) 常见坑

• 阴影由父容器绘制，clipChildren/clipToPadding 要关。
• 没 Outline 就没硬件阴影。
• 按压态：用 translationZ 动画比调 alpha 更自然。
• 设计稿“偏移” ≈ 提高 elevation + 调光源Y。

---

6) 结论总结

场景	调整项	建议
单控件微调	outlineShadowColor alpha	局部控制强度
页面统一深浅	主题 shadowAlpha	全局调节
全系统统一风格	HardwareRenderer 参数	控全局方向感/软硬度
模糊半径效果	elevation	控控件自身大小与偏移

---