syncfusion-winui-shimmer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing WinUI Shimmer

实现WinUI Shimmer

When to Use This Skill

何时使用本指南

Use this skill when the user needs to:

Display skeleton screens during content loading
Show shimmer effects as loading placeholders
Enhance perceived performance during data fetching
Create loading animations for lists, profiles, articles, or videos
Provide visual feedback during async content loading
Implement modern loading UX patterns (skeleton loaders)

Always apply this skill when the user mentions: shimmer effects, skeleton screens, loading placeholders, content loading animations, shimmer loaders, or skeleton UI in WinUI applications.

当用户需要完成以下操作时使用本指南：

在内容加载期间展示骨架屏
显示shimmer效果作为加载占位符
提升数据获取过程中的感知性能
为列表、个人资料、文章或视频创建加载动画
在异步内容加载期间提供视觉反馈
实现现代化加载UX模式（骨架加载器）

当用户提及WinUI应用中的shimmer效果、骨架屏、加载占位符、内容加载动画、shimmer加载器或骨架UI时，务必使用本指南。

Component Overview

组件概览

SfShimmer is a Syncfusion WinUI control that displays animated placeholder content (skeleton screens) during loading operations. It provides 7 built-in shimmer types and supports custom layouts to match any content structure.

Namespace:

Syncfusion.UI.Xaml.Core

NuGet Package:

Syncfusion.Core.WinUI

Platform: WinUI 3 Desktop (.NET 5+, Windows App SDK 1.0+)

Key Advantage: Improves perceived performance by showing content structure while data loads, reducing user frustration during wait times.

SfShimmer 是Syncfusion推出的WinUI控件，用于在加载操作期间展示动画占位符内容（骨架屏）。它提供7种内置shimmer类型，支持自定义布局以匹配任意内容结构。

命名空间：

Syncfusion.UI.Xaml.Core

NuGet包：

Syncfusion.Core.WinUI

支持平台： WinUI 3 桌面端（.NET 5+，Windows App SDK 1.0+）

核心优势： 在数据加载时展示内容结构，提升感知性能，减少用户等待过程中的烦躁感。

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and NuGet package setup
Namespace imports and basic initialization
Default shimmer type (CirclePersona)
License registration requirements
First complete example

📄 阅读： references/getting-started.md

安装与NuGet包设置
命名空间导入与基础初始化
默认shimmer类型（CirclePersona）
许可证注册要求
首个完整示例

Built-in Shimmer Types

内置Shimmer类型

📄 Read: references/built-in-types.md

7 built-in shimmer types (CirclePersona, SquarePersona, Profile, Article, Video, Feed, Shopping)
Type property usage
Visual descriptions and comparisons
Choosing the right type for your content
Switching between types

📄 阅读： references/built-in-types.md

7种内置shimmer类型（CirclePersona、SquarePersona、Profile、Article、Video、Feed、Shopping）
Type属性用法
视觉描述与对比
为你的内容选择合适的类型
类型切换方法

Custom Layouts

自定义布局

📄 Read: references/custom-layouts.md

CustomLayout property for creating custom shimmer designs
Using Grid, StackPanel, Rectangle elements
Complex layout examples
Matching shimmer to actual content structure
Best practices and performance

📄 阅读： references/custom-layouts.md

用于创建自定义shimmer设计的CustomLayout属性
使用Grid、StackPanel、Rectangle元素
复杂布局示例
让shimmer匹配实际内容结构
最佳实践与性能优化

Customization Options

自定义选项

📄 Read: references/customization.md

Fill property (background color)
WaveColor property (animation color)
WaveWidth property (wave width control)
WaveDuration property (animation speed)
RepeatCount property (repeat views)
Combining customizations

📄 阅读： references/customization.md

Fill属性（背景色）
WaveColor属性（动画颜色）
WaveWidth属性（波浪宽度控制）
WaveDuration属性（动画速度）
RepeatCount属性（重复视图数）
组合多种自定义配置

Quick Start Example

快速开始示例

xaml

<Page
    xmlns:syncfusion="using:Syncfusion.UI.Xaml.Core">
    <Grid>
        <syncfusion:SfShimmer 
            x:Name="shimmer"
            Type="Article"
            Fill="#F6F6F6"
            WaveColor="#E0E0E0"
            RepeatCount="3"/>
    </Grid>
</Page>

csharp

using Syncfusion.UI.Xaml.Core;
using Microsoft.UI;

// Create and configure Shimmer
SfShimmer shimmer = new SfShimmer
{
    Type = ShimmerType.Article,
    Fill = Colors.LightGray,
    WaveColor = Colors.White,
    RepeatCount = 3
};

// Add to UI
this.Content = shimmer;

xaml

<Page
    xmlns:syncfusion="using:Syncfusion.UI.Xaml.Core">
    <Grid>
        <syncfusion:SfShimmer 
            x:Name="shimmer"
            Type="Article"
            Fill="#F6F6F6"
            WaveColor="#E0E0E0"
            RepeatCount="3"/>
    </Grid>
</Page>

csharp

using Syncfusion.UI.Xaml.Core;
using Microsoft.UI;

// Create and configure Shimmer
SfShimmer shimmer = new SfShimmer
{
    Type = ShimmerType.Article,
    Fill = Colors.LightGray,
    WaveColor = Colors.White,
    RepeatCount = 3
};

// Add to UI
this.Content = shimmer;

Common Patterns

常见使用模式

1. Simple Profile Loading Shimmer

1. 简单个人资料加载Shimmer

xaml

<syncfusion:SfShimmer Type="Profile"/>

When to use: User profile pages, account screens, contact details loading.

xaml

<syncfusion:SfShimmer Type="Profile"/>

适用场景： 用户个人资料页、账户页面、联系人详情加载。

2. Article/Blog Loading with Repeat

2. 文章/博客加载（带重复效果）

xaml

<Grid>
    <syncfusion:SfShimmer 
        Type="Article"
        RepeatCount="5"
        Fill="#F5F5F5"
        WaveColor="#E0E0E0"/>
</Grid>

When to use: Blog feeds, news articles, text-heavy content loading.

xaml

<Grid>
    <syncfusion:SfShimmer 
        Type="Article"
        RepeatCount="5"
        Fill="#F5F5F5"
        WaveColor="#E0E0E0"/>
</Grid>

适用场景： 博客信息流、新闻文章、大文本内容加载。

3. Shopping/Product Grid Shimmer

3. 电商/商品网格Shimmer

xaml

<syncfusion:SfShimmer 
    Type="Shopping"
    RepeatCount="6"
    WaveDuration="1500"/>

When to use: E-commerce product grids, shopping catalogs, item galleries.

xaml

<syncfusion:SfShimmer 
    Type="Shopping"
    RepeatCount="6"
    WaveDuration="1500"/>

适用场景： 电商商品网格、购物目录、商品画廊。

4. Video/Media Feed Shimmer

4. 视频/媒体信息流Shimmer

xaml

<syncfusion:SfShimmer 
    Type="Video"
    RepeatCount="4"
    Fill="#000000"
    WaveColor="#333333"/>

When to use: Video streaming apps, media galleries, YouTube-like feeds.

xaml

<syncfusion:SfShimmer 
    Type="Video"
    RepeatCount="4"
    Fill="#000000"
    WaveColor="#333333"/>

适用场景： 视频流应用、媒体画廊、类YouTube信息流。

5. Conditional Shimmer Display

5. 条件式Shimmer展示

xaml

<Grid>
    <!-- Shimmer while loading -->
    <syncfusion:SfShimmer 
        x:Name="shimmer"
        Type="Feed"
        Visibility="{x:Bind IsLoading, Mode=OneWay}"/>
    
    <!-- Actual content when loaded -->
    <ListView 
        x:Name="contentListView"
        Visibility="{x:Bind IsLoaded, Mode=OneWay}"
        ItemsSource="{x:Bind Items}"/>
</Grid>

csharp

private bool isLoading = true;
public bool IsLoading
{
    get => isLoading;
    set
    {
        isLoading = value;
        OnPropertyChanged();
    }
}

public bool IsLoaded => !IsLoading;

private async void LoadContentAsync()
{
    IsLoading = true;
    
    try
    {
        var data = await FetchDataAsync();
        contentListView.ItemsSource = data;
    }
    finally
    {
        IsLoading = false;
    }
}

When to use: Toggle between shimmer and actual content based on loading state.

xaml

<Grid>
    <!-- Shimmer while loading -->
    <syncfusion:SfShimmer 
        x:Name="shimmer"
        Type="Feed"
        Visibility="{x:Bind IsLoading, Mode=OneWay}"/>
    
    <!-- Actual content when loaded -->
    <ListView 
        x:Name="contentListView"
        Visibility="{x:Bind IsLoaded, Mode=OneWay}"
        ItemsSource="{x:Bind Items}"/>
</Grid>

csharp

private bool isLoading = true;
public bool IsLoading
{
    get => isLoading;
    set
    {
        isLoading = value;
        OnPropertyChanged();
    }
}

public bool IsLoaded => !IsLoading;

private async void LoadContentAsync()
{
    IsLoading = true;
    
    try
    {
        var data = await FetchDataAsync();
        contentListView.ItemsSource = data;
    }
    finally
    {
        IsLoading = false;
    }
}

适用场景： 根据加载状态在shimmer和实际内容之间切换。

6. Custom Layout for Specific UI

6. 特定UI的自定义布局

xaml

<syncfusion:SfShimmer>
    <syncfusion:SfShimmer.CustomLayout>
        <Grid RowSpacing="10" ColumnSpacing="15">
            <Grid.RowDefinitions>
                <RowDefinition Height="60"/>
                <RowDefinition Height="Auto"/>
                <RowDefinition Height="Auto"/>
            </Grid.RowDefinitions>
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="60"/>
                <ColumnDefinition Width="*"/>
            </Grid.ColumnDefinitions>
            
            <!-- Profile image placeholder -->
            <Ellipse Grid.Row="0" Grid.RowSpan="2" Width="60" Height="60"/>
            
            <!-- Name placeholder -->
            <Rectangle Grid.Row="0" Grid.Column="1" 
                      Height="15" RadiusX="3" RadiusY="3"
                      HorizontalAlignment="Left" Width="200"/>
            
            <!-- Description placeholder -->
            <Rectangle Grid.Row="1" Grid.Column="1" 
                      Height="12" RadiusX="3" RadiusY="3"
                      HorizontalAlignment="Left" Width="250"/>
            
            <!-- Content placeholder -->
            <Rectangle Grid.Row="2" Grid.ColumnSpan="2" 
                      Height="100" RadiusX="5" RadiusY="5"/>
        </Grid>
    </syncfusion:SfShimmer.CustomLayout>
</syncfusion:SfShimmer>

When to use: Custom content structure not matching built-in types.

xaml

<syncfusion:SfShimmer>
    <syncfusion:SfShimmer.CustomLayout>
        <Grid RowSpacing="10" ColumnSpacing="15">
            <Grid.RowDefinitions>
                <RowDefinition Height="60"/>
                <RowDefinition Height="Auto"/>
                <RowDefinition Height="Auto"/>
            </Grid.RowDefinitions>
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="60"/>
                <ColumnDefinition Width="*"/>
            </Grid.ColumnDefinitions>
            
            <!-- Profile image placeholder -->
            <Ellipse Grid.Row="0" Grid.RowSpan="2" Width="60" Height="60"/>
            
            <!-- Name placeholder -->
            <Rectangle Grid.Row="0" Grid.Column="1" 
                      Height="15" RadiusX="3" RadiusY="3"
                      HorizontalAlignment="Left" Width="200"/>
            
            <!-- Description placeholder -->
            <Rectangle Grid.Row="1" Grid.Column="1" 
                      Height="12" RadiusX="3" RadiusY="3"
                      HorizontalAlignment="Left" Width="250"/>
            
            <!-- Content placeholder -->
            <Rectangle Grid.Row="2" Grid.ColumnSpan="2" 
                      Height="100" RadiusX="5" RadiusY="5"/>
        </Grid>
    </syncfusion:SfShimmer.CustomLayout>
</syncfusion:SfShimmer>

适用场景： 与内置类型不匹配的自定义内容结构。

Key Properties

核心属性

Property	Type	Default	Description
`Type`	ShimmerType	CirclePersona	The built-in shimmer layout type. Options: CirclePersona, SquarePersona, Profile, Article, Video, Feed, Shopping.
`CustomLayout`	UIElement	null	Custom layout for creating shimmer designs that match your specific content structure.
`Fill`	Brush	#F6F6F6	Background color of the shimmer view (placeholder color).
`WaveColor`	Brush	White	Color of the animated wave that moves across the shimmer.
`WaveWidth`	double	200	Width of the animated wave in pixels. Larger values = wider wave.
`WaveDuration`	int	1000	Duration of the wave animation in milliseconds. Higher values = slower animation.
`RepeatCount`	int	1	Number of times the built-in shimmer view is repeated vertically. Useful for lists.

属性	类型	默认值	描述
`Type`	ShimmerType	CirclePersona	内置shimmer布局类型。可选值：CirclePersona, SquarePersona, Profile, Article, Video, Feed, Shopping。
`CustomLayout`	UIElement	null	用于创建与特定内容结构匹配的shimmer设计的自定义布局。
`Fill`	Brush	#F6F6F6	shimmer视图的背景色（占位符颜色）。
`WaveColor`	Brush	White	划过shimmer的动画波浪颜色。
`WaveWidth`	double	200	动画波浪的宽度（单位：像素），值越大波浪越宽。
`WaveDuration`	int	1000	波浪动画的持续时间（单位：毫秒），值越大动画越慢。
`RepeatCount`	int	1	内置shimmer视图垂直重复的次数，适用于列表场景。

Common Use Cases

常见使用场景

List/Feed Loading

列表/信息流加载

Social media feeds
News article lists
Product catalogs
Comment sections
Search results

Best Types: Feed, Article, Shopping

社交媒体信息流
新闻文章列表
商品目录
评论区
搜索结果

推荐类型： Feed、Article、Shopping

Profile/User Loading

个人资料/用户信息加载

User profiles
Contact cards
Account details
Team member displays
About sections

Best Types: Profile, CirclePersona, SquarePersona

用户个人资料
联系人卡片
账户详情
团队成员展示
关于板块

推荐类型： Profile、CirclePersona、SquarePersona

Media Loading

媒体加载

Video thumbnails
Image galleries
Media players
Streaming content
Photo albums

Best Types: Video, Custom layout with image placeholders

视频缩略图
图片画廊
媒体播放器
流媒体内容
相册

推荐类型： Video、带图片占位符的自定义布局

E-commerce

电商场景

Product grids
Shopping carts
Product details
Category pages
Wishlists

Best Types: Shopping, Custom layouts

商品网格
购物车
商品详情
分类页面
心愿单

推荐类型： Shopping、自定义布局

Implementation Tips

实现提示

Match Shimmer to Content: Design shimmer layouts that closely resemble the actual content structure for seamless transitions.
Use RepeatCount for Lists: Set
```
RepeatCount
```
to match the expected number of items visible in the viewport.
Timing:
- Show shimmer immediately when loading starts
- Hide shimmer when content is ready to display
- Typical shimmer duration: 500ms - 3000ms
Color Theming:
- Light theme: Fill = #F6F6F6, WaveColor = White
- Dark theme: Fill = #2C2C2C, WaveColor = #3C3C3C
Performance: Shimmer animations are GPU-accelerated. Multiple shimmers can run simultaneously without performance issues.
Accessibility: Shimmer is purely visual. Ensure screen readers announce loading state separately using live regions or status messages.
Wave Speed:
- Fast loading (<2s): WaveDuration = 800-1000ms
- Normal loading (2-5s): WaveDuration = 1000-1500ms
- Slow loading (>5s): WaveDuration = 1500-2000ms
Custom Layouts: Use Rectangle elements with rounded corners (RadiusX/RadiusY) and Ellipse for circular placeholders.

让Shimmer匹配内容： 设计与实际内容结构高度相似的shimmer布局，实现无缝过渡效果。
为列表使用RepeatCount： 设置
```
RepeatCount
```
匹配视口中预计可见的条目数量。
时机控制：
- 加载开始时立即展示shimmer
- 内容准备就绪后隐藏shimmer
- 典型shimmer展示时长：500ms - 3000ms
颜色主题适配：
- 浅色主题：Fill = #F6F6F6，WaveColor = White
- 深色主题：Fill = #2C2C2C，WaveColor = #3C3C3C
性能： Shimmer动画是GPU加速的，可同时运行多个shimmer不会出现性能问题。
无障碍适配： Shimmer是纯视觉元素，请通过实时区域或状态消息让屏幕阅读器单独播报加载状态。
波浪速度：
- 快速加载（<2s）：WaveDuration = 800-1000ms
- 普通加载（2-5s）：WaveDuration = 1000-1500ms
- 慢速加载（>5s）：WaveDuration = 1500-2000ms
自定义布局： 使用带圆角（RadiusX/RadiusY）的Rectangle元素，圆形占位符使用Ellipse。

Shimmer vs Other Loading Patterns

Shimmer与其他加载模式的对比

Use Shimmer when:

Content structure is known beforehand
Loading time is 500ms - 5 seconds
Showing list-based or structured content
Modern app with emphasis on perceived performance

Use BusyIndicator when:

Content structure is unknown
Generic loading indication needed
Modal/blocking operations
Very quick (<500ms) or very long (>10s) operations

Use ProgressBar when:

Determinate progress can be shown
File uploads/downloads
Progress percentage is available
Sequential operations with measurable progress

适用Shimmer的场景：

提前知晓内容结构
加载时长为500ms - 5秒
展示列表类或结构化内容
注重感知性能的现代化应用

适用BusyIndicator的场景：

内容结构未知
需要通用加载提示
模态/阻塞式操作
非常快（<500ms）或非常慢（>10s）的操作

适用ProgressBar的场景：

可展示确定进度
文件上传/下载
可获取进度百分比
进度可衡量的顺序操作

syncfusion-winui-shimmer

Original

Translation

Implementing WinUI Shimmer

实现WinUI Shimmer

When to Use This Skill

何时使用本指南

Component Overview

组件概览

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

Built-in Shimmer Types

内置Shimmer类型

Custom Layouts

自定义布局

Customization Options

自定义选项

Quick Start Example

快速开始示例

Common Patterns

常见使用模式

1. Simple Profile Loading Shimmer

1. 简单个人资料加载Shimmer

2. Article/Blog Loading with Repeat

2. 文章/博客加载（带重复效果）

3. Shopping/Product Grid Shimmer

3. 电商/商品网格Shimmer

4. Video/Media Feed Shimmer

4. 视频/媒体信息流Shimmer

5. Conditional Shimmer Display

5. 条件式Shimmer展示

6. Custom Layout for Specific UI

6. 特定UI的自定义布局

Key Properties

核心属性

Common Use Cases

常见使用场景

List/Feed Loading

列表/信息流加载

Profile/User Loading

个人资料/用户信息加载

Media Loading

媒体加载

E-commerce

电商场景

Implementation Tips

实现提示

Shimmer vs Other Loading Patterns

Shimmer与其他加载模式的对比

Related Documentation

相关文档