卡片组件在Zion中添加阴影需先启用uiEngine(harmony/web/hybrid)并安装@functorz/plugin-shadow插件;推荐用shadow属性配置,Web端可选CSS box-shadow或hoverShadow动画,但HarmonyOS不支持后两者。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

卡片组件在函子Zion里能加阴影,前提是项目已启用支持阴影渲染的底层能力——Zion本身不直接暴露box-shadow类名或ShadowOptions API,但通过其MCP(Model Context Protocol)自动注入的UI层契约,可将阴影逻辑映射到目标平台原生渲染引擎。
确认Zion项目是否具备阴影支持能力
打开项目根目录下的zion.config.ts,检查是否已启用uiEngine配置项:【必须存在且值为'harmony'、'web'或'hybrid'之一】。若为'none'或缺失该字段,则卡片无法渲染任何视觉阴影效果,后续所有操作均无效。
运行functorz doctor --ui,终端输出中需包含“Shadow: ✅ enabled”字样。若显示“Shadow: ❌ disabled (missing plugin)”则需执行functorz plugin install @functorz/plugin-shadow。
在Zion卡片组件中添加阴影的两种方式
方法一:使用Zion内置的shadow属性(推荐用于HarmonyOS与Web双端)
在卡片组件的TSX文件中,直接在Card标签上添加shadow属性:
{/* 卡片内容 */}
注意:color值必须为十六进制带透明度格式(如#00000020),不能用Color.Gray或rgba()字符串;否则Zion MCP在编译期会静默丢弃该参数。
方法二:透传CSS box-shadow(仅限Web端输出)
在组件样式文件中,为Card的className添加自定义类名,再在CSS中写入标准box-shadow:
.z-card-elevated {
box-shadow: 0 4px 12px -2px rgba(0, 0, 0, 0.15);
}
然后在TSX中:
⚠️ 此方式在HarmonyOS端会被完全忽略,且若同时使用了方法一的shadow属性,CSS规则将被Zion运行时注入的Canvas合成层覆盖,导致阴影不生效。
为卡片添加悬停阴影动画(Web端专属)
第一步:在zion.config.ts的plugins数组中确认已启用@functorz/plugin-hover:
plugins: ['@functorz/plugin-shadow', '@functorz/plugin-hover']
第二步:在组件内使用hoverShadow属性,Zion会自动注入:hover伪类及transition:
hoverShadow={{ radius: 14, color: '#00000025', offsetY: 6 }}
>
第三步:确保父容器未设置overflow: hidden——Zion生成的Web渲染节点默认使用relative定位,但若上层Layout组件(如Grid、Flex)被手动加了overflow: hidden,则阴影会被裁切,此时需在Layout组件上显式添加style={{ overflow: 'visible' }}。
这一步操作起来很简单,直接把style属性加到Layout标签上就行。


















