写鸿蒙界面做得久了,你会发现一个很有意思的现象:同样是给卡片加阴影,有的开发者一行 .shadow() 就完事,出来的效果像贴了张灰纸片;有的开发者却能让组件真正“浮”在屏幕上,层次分明、过渡柔和。HarmonyOS 应用实例做到第 178 篇,这次聊的就是影子与投影模拟,而且我打算先把一个容易被忽略的事实讲清楚——.shadow() 不等于投影。真正让卡片“飘起来”的,往往是模糊、渐变、透明度、多层叠影组合出来的视觉结果。
这篇文章不是 API 文档搬运,我会把 shadow、boxShadow、blur 模拟投影、渐变造影这几种方式拆开讲,配合可直接复制的代码和参数表,说清楚各自的适用边界,也会把阴影被裁剪、列表掉帧、动画抖动这些我在实际项目里踩过的问题一并翻出来。适合刚接触 ArkUI 的开发者,也适合做组件库时和阴影死磕的初级工程师。
1. 为什么“卡片投影”不等于一行 shadow 属性
1.1 shadow 到底在画什么
ArkUI 的 .shadow() 做的事情并不复杂:它先把组件最终的形状渲染到一张离屏纹理上,对这张纹理做高斯模糊,再按照偏移量画到组件背后。你可以把它理解成 CSS box-shadow 的简化版,但它有几个特性需要注意。
第一,阴影是沿组件的不透明区域轮廓生成的,并不是只能画在矩形四边。组件有圆角、有背景色、有自绘内容时,阴影形状都会跟着变化。第二,阴影是在组件外部扩展绘制的,所以父容器一旦开启裁剪,阴影就会少一块。第三,它的模糊是均匀模糊,不会区分“靠近接触面的地方实、远处虚”。
看一段最基础的代码:
typescript复制Column()
.width(200)
.height(200)
.backgroundColor(Color.White)
.borderRadius(16)
.shadow({
radius: 20,
color: 'rgba(15, 23, 42, 0.10)',
offsetX: 0,
offsetY: 8
})
这段代码生成的效果,就是在卡片下方 8vp 的位置多出一块半径为 20 的半透明模糊区域。想让阴影更实,要加的是 color 的 alpha;想让阴影更柔和,要加 radius,但通常还得同步降低 alpha,否则阴影会发黑发脏。
1.2 真实投影的物理规律与 UI 表现的差异
真实世界里,影子是光源、遮挡物、支撑面三者共同作用的结果。光源离物体越近,影子越实、边缘越清晰;光源越远,影子越虚、边缘越散,整体颜色也越淡。落到手机 UI 里,设计师其实大量参考了 Material Design 的“海拔”概念,把投影拆成了两层:
一层是接触阴影(contact shadow),负责表现卡片紧贴底部的位置关系,短、实、近;另一层是环境阴影(ambient shadow),负责表现卡片整体对环境光的遮挡,宽、虚、远。设计稿里那些看起来柔和且高级的阴影,几乎都是这两层叠加出来的。而 .shadow() 一次只能画一层均匀模糊,所以期望用一行属性还原整个设计稿,本身就是不现实的。
1.3 设计稿里的阴影经常不是一个属性
用 Figma 或 Sketch 的开发者应该都有印象,设计稿里一种阴影效果可能包含 X/Y 位移、Blur、Spread、颜色透明度这么多参数,有些卡片甚至会叠三四层。ArkUI 里对应的能力并不全在 shadow 上。
| 设计稿参数 | ArkUI 对应 | 说明 |
|---|---|---|
| X / Y 位移 | offsetX / offsetY | Y 为正表示阴影向下 |
| Blur 模糊 | radius | 数值越大越柔和 |
| Spread 扩展 | boxShadow 的 spread | shadow 没有扩展能力 |
| 颜色 + 透明度 | color 中的 rgba | 透明度写在 color 里 |
| 多层阴影 | 分层组件叠加 | 单属性不支持多阴影列表 |
理解了这一层,再去看各种“为什么阴影不像设计稿”的问题,思路就会清晰很多:不是参数填得不对,而是方案本身选得不对。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. shadow 与 boxShadow:差异、用法和适用边界
2.1 shadow 的轻量用法与预置 ShadowStyle
shadow 适合日常 80% 的场景。它的参数非常少,只有 radius、color、offsetX、offsetY,心智负担低,也容易调。绝大多数默认状态下的卡片悬浮效果,用这一个属性就够了。
除了自定义选项,ArkUI 还提供了一批预置阴影样式,例如:
typescript复制.shadow(ShadowStyle.OUTER_DEFAULT_MD)
ShadowStyle 枚举里有从 XS 到 LG 几档预设值,适合快速搭原型。但它的颜色、偏移和模糊半径已经固定,没法跟着设计稿微调,所以正式版本我不太推荐用。自己写 ShadowOptions 其实也就多几行代码,灵活性完全不一样。
