Back to Details

syncfusion-winui-shadow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Shadow Control (SfShadow)

实现阴影控件（SfShadow）

The Syncfusion WinUI Shadow control (
SfShadow
) applies customizable shadow effects to any framework element, creating visual depth and helping users distinguish overlapping UI elements. Shadow effects enhance the user interface by adding dimension and visual hierarchy following modern design principles.
Syncfusion WinUI阴影控件（
SfShadow
）可为任意框架元素应用可自定义的阴影效果，创建视觉深度，帮助用户区分重叠的UI元素。阴影效果遵循现代设计原则，通过增加维度和视觉层级来优化用户界面。

When to Use This Skill

何时使用该技能

Use the Shadow control when you need to:
  • Add depth to UI elements - Apply shadows to buttons, cards, panels, or images
  • Create visual hierarchy - Differentiate layers and elevations in the interface
  • Enhance material design - Implement elevation effects for modern UI patterns
  • Improve UX clarity - Help users identify interactive or important elements
  • Add polish to designs - Create professional, appealing user interfaces
Trigger keywords: shadow, SfShadow, depth, elevation, drop shadow, blur effect, visual depth, layering, material design, overlapping elements
当你需要完成以下需求时可使用阴影控件：
  • 为UI元素添加深度 - 为按钮、卡片、面板或图片应用阴影
  • 创建视觉层级 - 区分界面中的不同层级和高度
  • 优化Material Design效果 - 为现代UI模式实现高度效果
  • 提升UX清晰度 - 帮助用户识别可交互或重要元素
  • 优化设计质感 - 打造专业、有吸引力的用户界面
触发关键词： shadow, SfShadow, depth, elevation, drop shadow, blur effect, visual depth, layering, material design, overlapping elements

Component Overview

组件概览

Control: 
SfShadow

Namespace: 
Syncfusion.UI.Xaml.Core

NuGet Package: 
Syncfusion.Core.WinUI

Platform: WinUI 3 Desktop (.NET 5+)
控件： 
SfShadow

命名空间： 
Syncfusion.UI.Xaml.Core

NuGet包： 
Syncfusion.Core.WinUI

支持平台： WinUI 3 桌面端（.NET 5+）

Key Capabilities

核心功能

  • Apply shadows to any framework element (buttons, images, shapes, paths)
  • Customize shadow color with alpha transparency
  • Control blur intensity for soft or sharp shadows
  • Adjust shadow position with X/Y offsets
  • Match shadow corners to element corner radius
  • Enable/disable shadows dynamically
  • Automatic theme support (light/dark modes)
  • 可为任意框架元素（按钮、图片、形状、路径）添加阴影
  • 支持自定义带透明度的阴影颜色
  • 可控制模糊强度，实现柔和或锐利的阴影效果
  • 可通过X/Y偏移量调整阴影位置
  • 可让阴影圆角与元素圆角匹配
  • 支持动态启用/禁用阴影
  • 自带主题适配能力（亮/暗模式）

Documentation and Navigation Guide

文档与导航指南

Getting Started and Basic Usage

入门与基础用法

📄 Read: references/getting-started.md
  • Installing Syncfusion.Core.WinUI NuGet package
  • Creating WinUI 3 desktop application
  • Importing Syncfusion.UI.Xaml.Core namespace
  • Initializing SfShadow control in XAML and C#
  • Applying shadows to buttons
  • Applying shadows to images
  • Applying shadows to shapes and paths
  • Complete code examples for each scenario
📄 阅读： references/getting-started.md
  • 安装Syncfusion.Core.WinUI NuGet包
  • 创建WinUI 3桌面应用
  • 导入Syncfusion.UI.Xaml.Core命名空间
  • 在XAML和C#中初始化SfShadow控件
  • 为按钮添加阴影
  • 为图片添加阴影
  • 为形状和路径添加阴影
  • 每个场景的完整代码示例

Customization Options

自定义选项

📄 Read: references/customization.md
  • Changing shadow color (Color property)
  • Adjusting blur radius (BlurRadius property)
  • Setting corner radius (ShadowCornerRadius property)
  • Positioning shadows (OffsetX, OffsetY properties)
  • Enabling/disabling shadows (EnableShadow property)
  • Default values for all properties
  • Combining multiple customizations
  • Advanced visual effects
📄 阅读： references/customization.md
  • 修改阴影颜色（Color属性）
  • 调整模糊半径（BlurRadius属性）
  • 设置阴影圆角（ShadowCornerRadius属性）
  • 调整阴影位置（OffsetX、OffsetY属性）
  • 启用/禁用阴影（EnableShadow属性）
  • 所有属性的默认值
  • 多项自定义效果组合
  • 高级视觉效果

Quick Start Example

快速入门示例

Basic Shadow for Button

为按钮添加基础阴影

XAML:
xml
<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#:
csharp
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;
XAML：
xml
<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#：
csharp
using Syncfusion.UI.Xaml.Core;

// 创建阴影控件
SfShadow shadow = new SfShadow();

// 创建按钮
Button button = new Button();
button.Height = 50;
button.Width = 100;
button.Content = "Click Me";

// 将按钮添加到阴影控件中
shadow.Content = button;

Common Patterns

常见使用模式

1. Elevated Button with Custom Shadow

1. 带自定义阴影的凸起按钮

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

2. Card with Soft Shadow

2. 带柔和阴影的卡片

xml
<syncfusion:SfShadow 
    BlurRadius="15" 
    OffsetX="0" 
    OffsetY="8"
    ShadowCornerRadius="8">
    <Border 
        Background="White" 
        CornerRadius="8" 
        Padding="20">
        <TextBlock Text="Card Content"/>
    </Border>
</syncfusion:SfShadow>
xml
<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. Image with Shadow Effect

3. 带阴影效果的图片

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

4. Circular Button with Matching Shadow

4. 圆角匹配的圆形按钮

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

5. Star Rating with Shadows

5. 带阴影的星级评分组件

xml
<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>
    <!-- Repeat for more stars -->
</StackPanel>
xml
<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. Conditionally Enabled Shadow

6. 可条件启用的阴影

xml
<syncfusion:SfShadow EnableShadow="{Binding IsElevated}">
    <Button Content="Toggle Shadow"/>
</syncfusion:SfShadow>
csharp
// Toggle shadow programmatically
shadow.EnableShadow = false; // Disable shadow
shadow.EnableShadow = true;  // Enable shadow
xml
<syncfusion:SfShadow EnableShadow="{Binding IsElevated}">
    <Button Content="Toggle Shadow"/>
</syncfusion:SfShadow>
csharp
// 编程方式切换阴影显示状态
shadow.EnableShadow = false; // 禁用阴影
shadow.EnableShadow = true;  // 启用阴影

Key Properties

核心属性

PropertyTypeDefaultDescription
Content
objectnullThe UI element to apply shadow to
Color
ColorBlack (25% alpha)Shadow color with transparency
BlurRadius
double8Blur intensity (higher = softer shadow)
ShadowCornerRadius
double0Corner radius of the shadow
OffsetX
double4Horizontal shadow offset (+ = right, - = left)
OffsetY
double4Vertical shadow offset (+ = down, - = up)
EnableShadow
booltrueShow or hide shadow effect
属性类型默认值描述
Content
objectnull需要添加阴影的UI元素
Color
Color黑色（25%透明度）带透明度的阴影颜色
BlurRadius
double8模糊强度（数值越高阴影越柔和）
ShadowCornerRadius
double0阴影的圆角半径
OffsetX
double4阴影水平偏移量（正值向右，负值向左）
OffsetY
double4阴影垂直偏移量（正值向下，负值向上）
EnableShadow
booltrue显示或隐藏阴影效果

Property Usage Tips

属性使用提示

Color:
  • Use semi-transparent colors for realistic shadows
  • Match shadow color to background for subtle effects
  • Use darker shadows for higher elevations
BlurRadius:
  • 0-5: Sharp, close shadows (low elevation)
  • 8-12: Standard elevation shadows
  • 15+: Soft, distant shadows (high elevation)
Offsets:
  • Equal X/Y: Diagonal shadow (balanced depth)
  • X=0, Y>0: Drop shadow (common pattern)
  • Negative values: Shadow above/left of element
ShadowCornerRadius:
  • Should match the content's CornerRadius
  • Creates seamless shadow appearance
  • Essential for rounded buttons/cards
Color：
  • 使用半透明颜色实现更真实的阴影效果
  • 可让阴影颜色与背景色匹配，实现柔和的效果
  • 更高的层级可使用更深的阴影
BlurRadius：
  • 0-5：锐利、贴近元素的阴影（低层级）
  • 8-12：标准层级阴影
  • 15+：柔和、距离远的阴影（高层级）
Offsets：
  • X/Y值相等：斜向阴影（平衡的深度效果）
  • X=0, Y>0：投影（常见设计模式）
  • 负值：阴影出现在元素的上方/左侧
ShadowCornerRadius：
  • 应该与内容的CornerRadius匹配
  • 可实现无缝的阴影效果
  • 对圆角按钮/卡片非常重要

Common Use Cases

常见用例

Material Design Elevation Levels

Material Design高度层级

Level 1 (Resting):
xml
<syncfusion:SfShadow OffsetX="0" OffsetY="2" BlurRadius="4">
    <Button Content="Resting"/>
</syncfusion:SfShadow>
Level 2 (Raised):
xml
<syncfusion:SfShadow OffsetX="0" OffsetY="4" BlurRadius="8">
    <Button Content="Raised"/>
</syncfusion:SfShadow>
Level 3 (Elevated):
xml
<syncfusion:SfShadow OffsetX="0" OffsetY="8" BlurRadius="16">
    <Button Content="Elevated"/>
</syncfusion:SfShadow>
层级1（默认状态）：
xml
<syncfusion:SfShadow OffsetX="0" OffsetY="2" BlurRadius="4">
    <Button Content="Resting"/>
</syncfusion:SfShadow>
层级2（凸起状态）：
xml
<syncfusion:SfShadow OffsetX="0" OffsetY="4" BlurRadius="8">
    <Button Content="Raised"/>
</syncfusion:SfShadow>
层级3（高亮状态）：
xml
<syncfusion:SfShadow OffsetX="0" OffsetY="8" BlurRadius="16">
    <Button Content="Elevated"/>
</syncfusion:SfShadow>

Hover Effect with Shadow

带阴影的悬停效果

xml
<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>
xml
<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>

Gallery with Image Shadows

带图片阴影的相册

xml
<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>
xml
<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>

Best Practices

最佳实践

Performance

性能

  • Use shadows sparingly on frequently updated elements
  • Consider disabling shadows during animations if performance is impacted
  • Reduce blur radius for better performance in lists with many items
  • 在频繁更新的元素上谨慎使用阴影
  • 如果动画过程中出现性能问题，可考虑在动画期间禁用阴影
  • 包含大量元素的列表中可降低模糊半径提升性能

Visual Design

视觉设计

  • Consistent elevation: Use the same shadow settings for elements at the same elevation level
  • Natural light source: Position shadows as if light comes from top-left (OffsetX=4, OffsetY=4)
  • Subtle shadows: Avoid harsh shadows; use transparency and blur
  • Theme adaptation: Test shadows in both light and dark themes
  • 高度层级统一： 相同层级的元素使用相同的阴影配置
  • 光源自然： 按照光从左上方向照射的逻辑设置阴影（OffsetX=4, OffsetY=4）
  • 阴影柔和： 避免使用生硬的阴影，优先使用透明度和模糊效果
  • 主题适配： 在亮/暗两种主题下测试阴影效果

Accessibility

可访问性

  • Don't rely solely on shadows to convey information
  • Ensure sufficient color contrast regardless of shadow
  • Provide alternative visual cues for shadow-based depth
  • 不要仅依赖阴影传递信息
  • 无论阴影效果如何，都要确保足够的颜色对比度
  • 为基于阴影实现的深度效果提供替代的视觉提示

Common Mistakes to Avoid

需要避免的常见错误

  • ❌ Setting 
    ShadowCornerRadius
    without matching content's 
    CornerRadius
  • ❌ Using opaque black shadows (always add transparency)
  • ❌ Excessive blur radius on many elements (performance impact)
  • ❌ Inconsistent shadow directions across the UI
  • ❌ Forgetting to import Syncfusion.UI.Xaml.Core namespace
  • ❌ 设置
    ShadowCornerRadius
    时没有匹配内容的
    CornerRadius
  • ❌ 使用不透明的黑色阴影（始终要添加透明度）
  • ❌ 大量元素使用过高的模糊半径（影响性能）
  • ❌ 整个UI中阴影方向不一致
  • ❌ 忘记导入Syncfusion.UI.Xaml.Core命名空间

Troubleshooting

问题排查

Shadow not visible:
  • Verify 
    EnableShadow
    is 
    true
  • Check if shadow offset is sufficient (try increasing OffsetX/OffsetY)
  • Ensure blur radius is greater than 0
  • Verify shadow isn't same color as background
  • Check if content has transparent background
Shadow appears clipped:
  • Add margin/padding around SfShadow
  • Increase parent container size
  • Verify ClipToBounds is not set to true on parent
Performance issues:
  • Reduce number of shadows in view
  • Decrease blur radius
  • Use EnableShadow to conditionally show shadows
  • Consider virtualization for lists with shadowed items
阴影不可见：
  • 确认
    EnableShadow
    设置为
    true
  • 检查阴影偏移量是否足够（可尝试增大OffsetX/OffsetY）
  • 确认模糊半径大于0
  • 确认阴影颜色与背景色不一致
  • 检查内容是否有透明背景
阴影被裁剪：
  • 为SfShadow添加外边距/内边距
  • 增大父容器的尺寸
  • 确认父容器没有将ClipToBounds设置为true
性能问题：
  • 减少可视区域内的阴影数量
  • 降低模糊半径
  • 使用EnableShadow属性条件性显示阴影
  • 包含大量带阴影元素的列表可考虑使用虚拟化

Related Components

相关组件

  • Border - Combine with SfShadow for card-like containers
  • Button - Common target for shadow effects
  • Image - Apply shadows to photos and icons
  • Shapes/Paths - Create custom shadowed graphics
Need more details? Read the reference files linked in the Navigation Guide above for comprehensive documentation and examples.
  • Border - 与SfShadow结合使用可实现卡片类容器
  • Button - 阴影效果的常见应用目标
  • Image - 可为照片和图标添加阴影
  • Shapes/Paths - 可创建自定义的带阴影图形
需要更多细节？ 阅读上方导航指南中链接的参考文件，获取完整的文档和示例。