syncfusion-blazor-themes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Blazor Themes

Syncfusion Blazor 主题

Complete guidance for applying and customizing Syncfusion Blazor component themes using Theme Studio, SCSS overrides, and production-ready best practices.

本指南完整介绍如何使用Theme Studio、SCSS变量覆盖以及生产级最佳实践，来应用和自定义Syncfusion Blazor组件主题。

When to Use

适用场景

Use this skill when you need to:

Apply a built-in Syncfusion theme (Material 3, Bootstrap 5, Fluent, Tailwind, etc.)
Customize theme colors interactively using Theme Studio
Generate a filtered, minimal CSS bundle for only the components you use
Override theme variables with Sass
```
@use
```
and CSS custom properties
Use lightweight theme variants to reduce bundle size
Import and re-use saved theme settings (
```
settings.json
```
)

Do NOT use for:

Initial Blazor project setup → use
```
syncfusion-blazor-common
```
Script loading and CRG bundles → use
```
syncfusion-blazor-common
```
CSP configuration for stylesheets → use
```
syncfusion-blazor-security
```

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

应用Syncfusion内置主题（Material 3、Bootstrap 5、Fluent、Tailwind等）
使用Theme Studio交互式自定义主题颜色
仅为你用到的组件生成筛选后的最小CSS包
通过Sass的
```
@use
```
和CSS自定义属性覆盖主题变量
使用轻量主题变体来缩减包体积
导入并复用已保存的主题配置（
```
settings.json
```
）

请勿用于以下场景：

初始Blazor项目搭建 → 使用
```
syncfusion-blazor-common
```
脚本加载和CRG包处理 → 使用
```
syncfusion-blazor-common
```
样式表的CSP配置 → 使用
```
syncfusion-blazor-security
```

Quick Reference

快速参考

Full Theme Studio guide: See theme-appearance.md

完整Theme Studio指南：查看theme-appearance.md

Available Themes at a Glance

可用主题概览

Theme	Description
Material 3	Google Material Design 3 (recommended default)
Bootstrap 5	Bootstrap 5 design system
Fluent / Fluent 2	Microsoft Fluent Design System
Tailwind CSS	Tailwind CSS design tokens
Bootstrap 4	Bootstrap 4 design system
Material	Original Material Design
High Contrast	WCAG-compliant accessible theme

Lightweight variants (e.g.,
fluent2-lite.css
) exclude web fonts — ideal for offline or bandwidth-constrained environments.

主题	说明
Material 3	Google Material Design 3（推荐默认主题）
Bootstrap 5	Bootstrap 5设计系统
Fluent / Fluent 2	微软Fluent设计系统
Tailwind CSS	Tailwind CSS设计令牌
Bootstrap 4	Bootstrap 4设计系统
Material	初代Material Design
High Contrast	符合WCAG标准的无障碍主题

轻量变体（例如
fluent2-lite.css
）不含网页字体——非常适合离线或带宽受限的环境。

Quick Setup: Add a Theme

快速配置：添加主题

Blazor Web App (.NET 8+)

Add to

<head>

~/Components/App.razor

html

<link href="_content/Syncfusion.Blazor.Themes/material3.css" rel="stylesheet" />

在

~/Components/App.razor

的

<head>

标签中添加：

html

<link href="_content/Syncfusion.Blazor.Themes/material3.css" rel="stylesheet" />

Blazor WebAssembly Standalone

Add to

<head>

wwwroot/index.html

html

<link href="_content/Syncfusion.Blazor.Themes/material3.css" rel="stylesheet" />

⚠️ Important: Only reference one Syncfusion base theme at a time to avoid style conflicts.

在

wwwroot/index.html

的

<head>

标签中添加：

html

<link href="_content/Syncfusion.Blazor.Themes/material3.css" rel="stylesheet" />

⚠️ 重要提示：一次仅引用一个Syncfusion基础主题，避免出现样式冲突。

Theme Studio Workflow

Theme Studio 使用流程

Open Blazor Theme Studio
Select a base theme and customize colors with live preview
Filter to include only the components used in your app (reduces CSS size)
Download the package — includes
```
.css
```
,
```
.scss
```
, and
```
settings.json
```
Copy the CSS to
```
~/wwwroot/styles/
```
and reference it in your host page
Save
```
settings.json
```
to version control for future updates

打开Blazor Theme Studio
选择基础主题并自定义颜色，支持实时预览
筛选仅包含应用中用到的组件（可减小CSS体积）
下载主题包——包含
```
.css
```
、
```
.scss
```
和
```
settings.json
```
文件
将CSS文件复制到
```
~/wwwroot/styles/
```
目录下，并在宿主页面中引用
将
```
settings.json
```
保存到版本控制系统中，方便后续更新

SCSS Variable Override Example

SCSS 变量覆盖示例

scss

/* Custom.scss */
:root {
  --color-primary-override: 54, 34, 89;
}

@use 'material3.scss' with (
  $primary: var(#{--color-primary-override})
);

scss

/* Custom.scss */
:root {
  --color-primary-override: 54, 34, 89;
}

@use 'material3.scss' with (
  $primary: var(#{--color-primary-override})
);