在SharePoint 框架解决方案中使用 SharePoint 品牌中心字体

2025-04-24

SharePoint 品牌中心提供了一个集中式品牌管理应用程序，使品牌经理或指定的品牌所有者能够帮助你的组织自定义其体验的外观。此品牌资产管理系统允许客户在一个位置管理颜色、字体、图像和其他资产。

开发人员可以在其SharePoint 框架 (SPFx) 组件中使用品牌中心中定义的字体。本文演示如何在 SPFx 组件中使用 SharePoint 品牌中心中定义的字体。

本文介绍如何修改 SPFx 组件以使用中设置的相同字体

在 SPFx 组件中使用 SharePoint 品牌中心字体

首先创建新的SharePoint 框架组件，例如 Web 部件。

提示

若要了解如何创建第一个 SPFx Web 部件，请参阅生成第一个 SharePoint 客户端 Web 部件 (Hello World 第 1 部分) 。

在 Web 部件中，找到并打开项目中的 *.module.scss 文件。例如，如果创建了名为 “Hello World”的 Web 部件，则会在项目中的以下位置找到该文件：./src/webparts/helloWorld/HelloWorldWebPart.module.scss。

此文件包含 SPFx 组件的样式。

品牌中心内定义的所有字体都使用命名约定 --fontFamilyCustomFont###后的变量进行引用。全部以前缀 --fontFamily 开头，后跟 字体槽 名称。

例如，若要更改 Web 部件中的主字体，请将以下样式添加到 .helloWorld 类：

font-family: var(--fontFamilyCustomFont100, var(--fontFamilyBase));

这会告知 Web 部件使用 SharePoint 样式上下文中定义的值和变量 --fontFamilyCustomFont100，但如果该值未设置，它将默认为 --fontFamilyBase 槽。

生成的类现在将如下所示：

.helloWorld {
  font-family: var(--fontFamilyCustomFont100, var(--fontFamilyBase));
  overflow: hidden;
  padding: 1em;
  color: "[theme:bodyText, default: #323130]";
  color: var(--bodyText);
  &.teams {
    font-family: $ms-font-family-fallbacks;
  }
}

接下来，针对要应用这些更改的样式中任何其他类重复此步骤。例如，在默认 Web 部件中，你也会更新 .welcome 和 .links.a 样式，因此生成的 *.scss 文件将如下所示：

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

.helloWorld {
  font-family: var(--fontFamilyCustomFont100, var(--fontFamilyBase));
  overflow: hidden;
  padding: 1em;
  color: "[theme:bodyText, default: #323130]";
  color: var(--bodyText);
  &.teams {
    font-family: $ms-font-family-fallbacks;
  }
}

.welcome {
  text-align: center;
  font-family: var(--fontFamilyCustomFont100, var(--fontFamilyBase));
}

.welcomeImage {
  width: 100%;
  max-width: 420px;
}

.links {
  a {
    font-family: var(--fontFamilyCustomFont100, var(--fontFamilyBase));
    text-decoration: none;
    color: "[theme:link, default:#03787c]";
    color: var(--link); // note: CSS Custom Properties support is limited to modern browsers only

    &:hover {
      text-decoration: underline;
      color: "[theme:linkHovered, default: #014446]";
      color: var(--linkHovered); // note: CSS Custom Properties support is limited to modern browsers only
    }
  }
}

测试 Web 部件。

若要测试 Web 部件，请启动本地 Web 浏览器，但不启动到托管工作台的浏览器。

从项目的根目录运行命令 gulp serve ，并包含 --nobrowser 参数：
```
gulp serve --nobrowser
```
重要

SharePoint 托管的工作台不支持在 SharePoint 品牌中心定义的自定义字体。若要测试 Web 部件，需要在 SharePoint 网站的页面上测试它们。
在控制台中， gulp serve 命令将输出如下所示的行：
```
[spfx-serve] To load your scripts, use this query string: ?debug=true&noredir=true#debugManifestsFile=https://localhost:4321/temp/build/manifests.js
```
注意

调试查询字符串已从 SPFx verson 1.21 https://localhost:4321/temp/manifests.js 从更改为 https://localhost:4321/temp/build/manifests.js
打开浏览器并导航到有权将 Web 部件添加到页面的页面。
将上述控制台消息中的查询字符串添加到 URL 并加载页面。

在 “允许调试脚本 ”对话框中出现提示时，选择“ 加载调试脚本”。
接下来，将页面置于编辑模式，并将示例 Web 部件添加到页面。
最后，发布更改。

使用页面上的 Web 部件，从品牌中心网站中选择一种自定义字体：

选择Microsoft 365 套件栏右上角的齿轮图标，然后选择“ 更改外观”。
在 “更改外观 ”面板上，选择“ 字体”。
在 “字体 ”面板上，选择其中一种字体以查看 Web 部件上的更改。

请注意，页面上的字体将发生变化，包括自定义 Web 部件中的字体：

品牌中心字体槽参考

下表列出了开发人员可在其自定义 SPFx 组件中使用的 SharePoint 品牌中心中的所有可用字体槽位：

字体槽	自定义字体标记	Fluent 设计令牌	简短说明	在产品位置中使用
正文	CustomFont100	caption2	小标题
正文	CustomFont200	caption2Strong	标题媒体	新闻徽章、图像描述文字、站点 WP 活动、头像角色/作业、英雄徽章
正文	CustomFont300	caption1	标题大	图像覆盖
交互	CustomFont400	caption1Strong	小标签	虚拟形象链接
交互	CustomFont500	caption1Stronger	标签介质	页脚链接、顶部导航链接、中心导航链接、左侧导航、主图按钮
交互	CustomFont600	body1	标签大	按钮
正文	CustomFont700	body1Strong	段落小	快速链接说明、新闻子说明、网站 Web 部件信息、网站 Web 部件说明、头像名称、头像说明
正文	CustomFont800	body1Stronger	段落中等	新闻说明， RTE 普通， RTE 表单元格，主图说明
正文	CustomFont900	body2	段落大
标题	CustomFont1000	subtitle2	标题超小	新闻副标题， RTE H4， RTE 表标题， RTE，表列，网站 WP 网站标题，行动号召文本，英雄行动号召
标题	CustomFont1100	subtitle2Stronger	小标题	快速链接标题、新闻标题、页脚标题、RTE H3、RTE 拉引号、分区标题、英雄标题、英雄小磁贴标题
标题	CustomFont1200	subtitle1	标题中等	RTE H2， Hero title large
标题	CustomFont1300	title3	标题大	Web 部件标题、Hero 磁贴标题
标题	CustomFont1400	title2	标题特大
标题	CustomFont1500	title1	小标题	中心标题
标题	CustomFont1600	largeTitle	标题媒体	页面标题、网站标题
标题	CustomFont1700	显示	大型游戏

提示

在样式表中使用其中一个自定义字体槽标记时，请不要忘记包含 --fontFamily 前缀。

另请参阅

视频：在自定义 SPFx 解决方案中使用 SharePoint 品牌中心字体设置

通过

在SharePoint 框架解决方案中使用 SharePoint 品牌中心字体

在 SPFx 组件中使用 SharePoint 品牌中心字体

测试 Web 部件。

品牌中心字体槽参考

另请参阅

其他资源