为 TDesignBlazor 添加暗黑模式

news2025/1/16 6:44:54

本文将讲述我为 TDesignBlazor 开源项目提交 PR 的经历，主要介绍暗黑模式功能的实现以及之后如何在项目中使用。我将会分享我在实现这一功能时遇到的问题，以及我是如何解决这些问题的。我希望通过我的经历能够鼓励更多的人参与开源项目，为 TDesignBlazor 贡献代码，帮助项目快速迭代。

文章目录

1. 背景
2. 开发过程
- 2.1 实现原理
- 2.2 TDesignBlazor 实现思路
3. 最后

1. 背景

TDesign 是腾讯各业务团队在服务业务过程中沉淀的一套企业级设计体系。其支持业界主流的 React/Vue/Angular/微信小程序/Flutter 开发技术栈，并提供桌面端和移动端两套风格统一的组件资源，是一款界面和使用体验都无可挑剔的前端框架。

TDesign 官方是没有提供 Blazor 版本的支持，很幸运的是在我自己搭好了架子捣鼓了一个组件后，发现社区已经有了一个非常完善的 TDesignBlazor。毕竟工作量非常大，一个人的力量是有限的，需要社区的力量来支撑。也是刚好看到张队转载的文章，发起者在寻求 Blazor 爱好者参与，所以我决定加入进来，帮助维护和改进这个项目。这样就能够将 TDesign 的优秀设计和交互体验带到 Blazor 项目中，提高开发效率和用户体验。我相信社区的力量，我们一起能够完成这个目标。

2. 开发过程

TDesign 组件库提供了暗色模式，并且官方的演示站点是有暗黑模式的体验。这里我们要为 TDesignBlazor 项目的演示站点添加暗黑模式，并为使用该 Blazor 组件的项目提供简单的调用暗黑模式的方式。

2.1 实现原理

根据 TDesign 文档的介绍，我们只需要给网页的 html 标签增加 theme-mode 属性即可。其组件库会自动变换颜色模式，通过此种方式也可以设置不同的颜色主题。

在这里插入图片描述

其实现的原理也非常简单，组件库使用 css variables（自定义属性）实现颜色的定义，同时定义了 :root[theme-color="custom-theme"][theme-mode="dark"] 选择器来设置浅色/暗色模式两组不同的颜色值，然后通过 js 控制 html 标签的 theme-mode 属性：setAttribute 和 removeAttribute 来实现主题的切换。

我们可以在官方演示站点通过 F12 打开开发人员工具，审查 html 标签来看到这些信息：

在这里插入图片描述

2.2 TDesignBlazor 实现思路

通过文档我们已经了解到，暗色模式只需要通过 js 控制 html 标签的 theme-mode 属性：

// 设置暗色模式
document.documentElement.setAttribute('theme-mode', 'dark');
// 重置为浅色模式
document.documentElement.removeAttribute('theme-mode');

这里对于 TDesignBlazor 暗黑功能的实现，我们只需要通过 .NET 调用 JavaScript 函数即可。关于这一块的相关知识可以参考微软官方文档：《JavaScript 互操作》。

参与开源项目，首先我们要遵守项目的贡献指南，更要了解这个项目。在 TDesignBlazor 项目中，src 目录下是 TDesign 的 Blazor 类库和测试项目。doc 目录下是 Blazor 类库使用的演示站点，分为 ServerSide 和 WebAssembly 两种形式，Shared 是两者共用的部分。

搞清楚了项目的基本情况，我们就可以动手添加这一部分功能了。前面我们也讲到，最好是在 Blazor 类库中提供可以直接切换的方法。

首先，在 tdesign-blazor.js 添加相关的 js 方法。

/**
 * 暗黑模式
 * */
let theme = {
    /**
     * 浅色模式
     * */
    light: function () {
        document.documentElement.removeAttribute('theme-mode');
    },
    /**
     * 暗色模式
     * */
    dark: function () {
        document.documentElement.setAttribute('theme-mode', 'dark');
    }
}

TDesignExtensions.cs 是 TDesign 的扩展，我在里面添加 ChangeThemeMode 方法。

/// <summary>
/// 执行切换暗黑和浅色模式切换
/// </summary>
/// <param name="js"></param>
/// <param name="isDark">是否为暗黑模式</param>
public static async Task ChangeThemeMode(this IJSRuntime js, bool isDark = true)
{
    var jsObject = await js.ImportScriptAsync();
    await jsObject.InvokeVoidAsync(isDark ? "theme.dark" : "theme.light");
}

对于演示站点的修改，大部分工作主要是界面上的，集中在 doc/TDesign.Docs.Shared/Layouts/MainLayout.razor。这里需要添加一个 TInputRadioGroup 主题切换的按钮，样式按照官方站点设计即可。在需要执行主题切换调用的地方执行 JS.ChangeThemeMode 方法，如下：

@using Microsoft.JSInterop
@inject IJSRuntime JS

<TInputRadioGroup @bind-Value="ThemeMode" OnValueSelected="@(e=>JS.ChangeThemeMode(e=="2"))" Size="Size.Medium" ButtonStyle="RadioButtonStyle.Outline">
    <TInputRadio Value="1">浅色</TInputRadio>
    <TInputRadio Value="2">暗黑</TInputRadio>
</TInputRadioGroup>

@code{
    int ThemeMode { get; set; } = 1;
}