syncfusion-winui-shadow

实现阴影控件（SfShadow）

Syncfusion WinUI 阴影控件（SfShadow）可为任意框架元素添加可自定义的阴影效果，营造视觉层次，并帮助用户区分相互重叠的 UI 元素。阴影效果遵循现代设计原则，为界面增添层次感和视觉层级。

何时使用此技能

在以下情况下使用阴影控件：

• 为 UI 元素增添层次感 - 为按钮、卡片、面板或图像添加阴影
• 创建视觉层级 - 区分界面中的不同层和高度
• 增强材质设计效果 - 为现代 UI 模式实现高度效果
• 提升 UX 清晰度 - 帮助用户识别可交互或重要的元素
• 为设计增添精致感 - 创建专业且美观的用户界面

触发关键词： shadow、SfShadow、depth、elevation、drop shadow、blur effect、visual depth、layering、material design、overlapping elements

组件概览

控件： SfShadow
命名空间： Syncfusion.UI.Xaml.Core
NuGet 包： Syncfusion.Core.WinUI
平台： WinUI 3 桌面版（.NET 5+）

主要功能

• 为任意框架元素（按钮、图像、形状、路径）添加阴影
• 使用 Alpha 透明度自定义阴影颜色
• 控制模糊强度，以生成柔和或锐利的阴影
• 使用 X/Y 偏移量调整阴影位置
• 使阴影圆角与元素圆角半径匹配
• 动态启用或禁用阴影
• 自动支持主题（浅色/深色模式）

文档与导航指南

入门与基本用法

📄 阅读： references/getting-started.md

• 安装 Syncfusion.Core.WinUI NuGet 包
• 创建 WinUI 3 桌面应用
• 导入 Syncfusion.UI.Xaml.Core 命名空间
• 在 XAML 和 C# 中初始化 SfShadow 控件
• 为按钮添加阴影
• 为图像添加阴影
• 为形状和路径添加阴影
• 各种场景的完整代码示例

自定义选项

📄 阅读： references/customization.md

• 更改阴影颜色（Color 属性）
• 调整模糊半径（BlurRadius 属性）
• 设置圆角半径（ShadowCornerRadius 属性）
• 设置阴影位置（OffsetX、OffsetY 属性）
• 启用或禁用阴影（EnableShadow 属性）
• 所有属性的默认值
• 组合多种自定义设置
• 高级视觉效果

快速入门示例

按钮的基本阴影

XAML：

<Page
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:syncfusion="using:Syncfusion.UI.Xaml.Core">
    
    <Grid>
        <syncfusion:SfShadow>
            <Button Height="50" Width="100" Content="Click Me"/>
        </syncfusion:SfShadow>
    </Grid>
</Page>

C#：

using Syncfusion.UI.Xaml.Core;

// Create shadow control
SfShadow shadow = new SfShadow();

// Create button
Button button = new Button();
button.Height = 50;
button.Width = 100;
button.Content = "Click Me";

// Add button to shadow
shadow.Content = button;

常见模式

1. 带自定义阴影的悬浮按钮

<syncfusion:SfShadow 
    Color="DarkBlue" 
    BlurRadius="10" 
    OffsetX="5" 
    OffsetY="5">
    <Button Height="50" Width="120" Content="Action"/>
</syncfusion:SfShadow>

2. 带柔和阴影的卡片

<syncfusion:SfShadow 
    BlurRadius="15" 
    OffsetX="0" 
    OffsetY="8"
    ShadowCornerRadius="8">
    <Border 
        Background="White" 
        CornerRadius="8" 
        Padding="20">
        <TextBlock Text="Card Content"/>
    </Border>
</syncfusion:SfShadow>

3. 带阴影效果的图像

<syncfusion:SfShadow 
    BlurRadius="12" 
    OffsetX="4" 
    OffsetY="4">
    <Image 
        Height="150" 
        Width="150" 
        Source="/Assets/photo.png"/>
</syncfusion:SfShadow>

4. 阴影与之匹配的圆形按钮

<syncfusion:SfShadow 
    ShadowCornerRadius="25"
    BlurRadius="8"
    OffsetX="3"
    OffsetY="3">
    <Button 
        Height="50" 
        Width="50" 
        CornerRadius="25"
        Content="+"
        FontSize="24"/>
</syncfusion:SfShadow>

5. 带阴影的星级评分

<StackPanel Orientation="Horizontal">
    <syncfusion:SfShadow>
        <Path Data="M44.5 4L54.0608 33.4114H85L59.9696 51.5886L69.5304 81L44.5 62.8228L19.4696 81L29.0304 51.5886L4 33.4114H34.9392L44.5 4Z" 
              Fill="#FFD700"/>
    </syncfusion:SfShadow>
    
</StackPanel>

6. 按条件启用的阴影

<syncfusion:SfShadow EnableShadow="{Binding IsElevated}">
    <Button Content="Toggle Shadow"/>
</syncfusion:SfShadow>

// Toggle shadow programmatically
shadow.EnableShadow = false; // Disable shadow
shadow.EnableShadow = true;  // Enable shadow

主要属性

属性	类型	默认值	说明
Content	object	null	要应用阴影的 UI 元素
Color	Color	Black (25% alpha)	带透明度的阴影颜色
BlurRadius	double	8	模糊强度（值越大，阴影越柔和）
ShadowCornerRadius	double	0	阴影的圆角半径
OffsetX	double	4	阴影的水平偏移量（+ = 向右，- = 向左）
OffsetY	double	4	阴影的垂直偏移量（+ = 向下，- = 向上）
EnableShadow	bool	true	显示或隐藏阴影效果

属性使用技巧

颜色：

• 使用半透明颜色，打造逼真的阴影
• 让阴影颜色与背景颜色一致，以获得微妙效果
• 海拔高度越高，使用的阴影颜色越深

模糊半径：

• 0-5：边缘清晰、距离较近的阴影（低海拔）
• 8-12：标准海拔高度的阴影
• 15+：边缘柔和、距离较远的阴影（高海拔）

偏移量：

• X/Y 相等：对角阴影（深度均衡）
• X=0，Y>0：投影（常见模式）
• 负值：阴影位于元素上方或左侧

阴影圆角半径：

• 应与内容的 CornerRadius 匹配
• 打造无缝的阴影效果
• 对圆角按钮/卡片至关重要

常见用例

Material Design 海拔层级

层级 1（静止）：

<syncfusion:SfShadow OffsetX="0" OffsetY="2" BlurRadius="4">
    <Button Content="Resting"/>
</syncfusion:SfShadow>

层级 2（抬起）：

<syncfusion:SfShadow OffsetX="0" OffsetY="4" BlurRadius="8">
    <Button Content="Raised"/>
</syncfusion:SfShadow>

层级 3（升高）：

<syncfusion:SfShadow OffsetX="0" OffsetY="8" BlurRadius="16">
    <Button Content="Elevated"/>
</syncfusion:SfShadow>

带阴影的悬停效果

<Button.Style>
    <Style TargetType="Button">
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="Button">
                    <syncfusion:SfShadow x:Name="ButtonShadow" OffsetY="2" BlurRadius="4">
                        <ContentPresenter/>
                    </syncfusion:SfShadow>
                    <ControlTemplate.Triggers>
                        <Trigger Property="IsMouseOver" Value="True">
                            <Setter TargetName="ButtonShadow" Property="OffsetY" Value="8"/>
                            <Setter TargetName="ButtonShadow" Property="BlurRadius" Value="16"/>
                        </Trigger>
                    </ControlTemplate.Triggers>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</Button.Style>

带图片阴影的图库

<ItemsControl ItemsSource="{Binding Photos}">
    <ItemsControl.ItemTemplate>
        <DataTemplate>
            <syncfusion:SfShadow 
                BlurRadius="10" 
                OffsetX="4" 
                OffsetY="4"
                Margin="10">
                <Image Source="{Binding ImagePath}" Height="150" Width="150"/>
            </syncfusion:SfShadow>
        </DataTemplate>
    </ItemsControl.ItemTemplate>
</ItemsControl>

最佳实践

性能

• 对频繁更新的元素谨慎使用阴影
• 如果性能受到影响，可考虑在动画期间禁用阴影
• 对包含许多项的列表，减小模糊半径以提升性能

视觉设计

• 海拔高度一致：同一海拔层级的元素使用相同的阴影设置
• 自然光源：将阴影设置为仿佛光线从左上方照来（OffsetX=4，OffsetY=4）
• 微妙的阴影：避免生硬的阴影；使用透明度和模糊效果
• 适配主题：在浅色和深色主题下测试阴影

无障碍

• 不要仅依赖阴影传递信息
• 无论阴影如何，都要确保足够的颜色对比度
• 为基于阴影的深度效果提供替代视觉提示

应避免的常见错误

• ❌ 设置 ShadowCornerRadius，却不让它与内容的 CornerRadius 匹配
• ❌ 使用不透明的黑色阴影（务必添加透明度）
• ❌ 在许多元素上使用过大的模糊半径（会影响性能）
• ❌ UI 中的阴影方向不一致
• ❌ 忘记导入 Syncfusion.UI.Xaml.Core 命名空间

故障排除

阴影不可见：

• 确认 EnableShadow 为 true
• 检查阴影偏移量是否足够（尝试增大 OffsetX/OffsetY）
• 确保模糊半径大于 0
• 确认阴影颜色与背景颜色不同
• 检查内容是否具有透明背景

阴影显示不完整：

• 在 SfShadow 周围添加边距/内边距
• 增大父容器的尺寸
• 确认父容器未将 ClipToBounds 设为 true

性能问题：

• 减少视图中的阴影数量
• 减小模糊半径
• 使用 EnableShadow 有条件地显示阴影
• 对带阴影的列表项考虑使用虚拟化

---

需要更多详情？ 请阅读上方导航指南中链接的参考文件，获取完整文档和示例。