如何为字体库注册自定义字体集

查看官方原文 ↗ 发布于 2024年4月1日

WordPress 6.5 将带来期待已久的字体库功能，允许你直接从站点编辑器管理字体。表面上看，这主要是一个面向用户的工具，但其中也包含了一些面向开发者的实用功能。

在本文中，你将学习如何注册自定义字体集。这是字体库的一个子功能，允许你定义字体集合，供你的主题或插件用户在其网站上安装。然后，他们可以通过样式面板或在文章、模板和区块模式中直接使用这些字体来进一步自定义排版。

默认情况下，WordPress 自带一个字体集，允许你从 Google Fonts 库安装字体。但作为开发者，你可以通过构建自定义字体集来提供更精选的体验。

字体集如何工作

要在 WordPress 6.5 中找到字体库，你必须进入管理后台的外观 > 编辑器。然后，选择样式面板（半圆形图标）。在该面板中，选择排版，你应该会看到一个新的设置图标，其工具提示为管理字体：

WordPress 站点编辑器，侧边栏中打开了样式面板。显示了排版子面板及其选择字体的设置字段。

如果你还不熟悉界面导航，可能会觉得它有点隐蔽。但它位于所有其他排版设置旁边。

点击管理字体按钮后，会出现一个新的字体模态框，显示几个选项卡，如下图所示：

覆盖在 WordPress 站点编辑器屏幕上的字体模态框。选中了 Google Fonts 选项卡，显示可选择的字体列表。

显示的三个选项卡是：

库：这将显示你主题中的所有字体以及通过字体库安装的字体。
上传： 允许你直接从计算机上传字体文件。
Google Fonts： 这是 WordPress 自带的默认字体集，允许你安装任何 Google 字体。

当你从Google Fonts集合中选择一种字体时，会出现一个新面板，让你安装网站所需的字体变体：

覆盖在 WordPress 站点编辑器屏幕上的字体模态框。显示了 Fira Code 字体，并选择了两个变体进行安装。

需要注意的是，这些字体存储在用户本地的 /wp-content/uploads/fonts 文件夹中。此过程对于默认字体集和你在主题中注册的任何自定义字体集都相同。

注册字体集

有两种注册字体的方法。第一种方法仅使用 PHP 来定义字体集及其字体族。第二种方法使用 PHP 注册字体集，但使用 JSON 来定义字体族。本教程将介绍这两种方法。

本教程将重点介绍通过主题注册自定义字体集。但你当然也可以通过插件注册字体集——只需更改任何文件路径以指向你的插件文件夹。

注册函数

WordPress 提供了一个用于注册字体集的辅助函数 wp_register_font_collection()。查看其签名：

wp_register_font_collection( string $slug, array $args );

该函数接受两个参数：

$slug： 你的字体集的唯一标识符，应仅包含字母数字字符、短横线和下划线。最佳实践是使用你的主题或插件 slug 作为前缀。
$args： 用于定义字体集的参数数组：
- name： 字体集的人类可读标签，应进行国际化。
- description： 字体集的国际化描述，显示在用户界面中。
- font_families： 字体族定义的数组，或包含指向包含字体集的 JSON 文件的文件路径或 URL 的字符串（你将在下面学习如何定义字体族）。
- categories： 类别数组。每个类别应是一个包含以下内容的数组：
  - name： 类别的国际化标签。
  - slug： 唯一的 slug，仅包含字母数字字符、短横线和下划线。

要注册字体集，你应该在 init 钩子上进行。在本教程的剩余部分，你将使用名为 themeslug_font_collections() 的单个函数，它是此钩子上的一个动作。

将以下代码添加到主题的 functions.php 文件中以进行设置：

add_action( 'init', 'themeslug_font_collections' );

function themeslug_font_collections() {
	// 在此处注册或注销字体集。
}

字体族定义

在继续之前，了解如何在 WordPress 中定义字体族很重要。如果你熟悉在 theme.json 中定义字体族的格式，这会感觉很相似。

以下是字体族数组的示例。第一个是系统字体，第二个是网络字体：

$font_families = [
	[
		'font_family_settings' => [
			'fontFamily' => 'system-ui, sans-serif',
			'slug'       => 'system-ui',
			'name'       => __( 'System UI', 'themeslug' ),
		],
		'categories' => [ 'sans-serif' ]
	],
	[
		'font_family_settings' => [
			'name'       => __( 'Roboto Flex', 'themeslug' ),
			'slug'       => 'roboto-flex',
			'fontFamily' => 'Roboto Flex, sans-serif',
			'fontFace'   => [
				[
					'src'        => 'https://fonts.gstatic.com/s/robotoflex/v9/NaN4epOXO_NexZs0b5QrzlOHb8wCikXpYqmZsWI-__OGfttPZktqc2VdZ80KvCLZaPcSBZtOx2MifRuWR28sPJtUMbsFEK6cRrleUx9Xgbm3WLHa_F4Ep4Fm0PN19Ik5Dntczx0wZGzhPlL1YNMYKbv9_1IQXOw7AiUJVXpRJ6cXW4O8TNGoXjC79QRyaLshNDUf3e0O-gn5rrZCu20YNYG0EACUTNK-QKavMlxGJI8dxef0jQ.woff2',
					'fontWeight' => '400',
					'fontStyle'  => 'normal',
					'fontFamily' => 'Roboto Flex',
					'preview'    => 'https://s.w.org/images/fonts/17.7/previews/roboto-flex/roboto-flex-400-normal.svg'
				]
			]
		],
		'categories' => [ 'sans-serif' ]
	]
];

字体族定义包含以下参数：

font_family_settings： 用于定义字体族的设置数组，遵循标准的 theme.json 定义字体族的格式：
- name： 字体族的人类可读标题。
- slug： 字体族的唯一 slug，应仅包含字母数字字符、短横线和下划线。
- fontFamily： 将映射到 CSS font-family 值的有效值。通常，这是一个带有后备字体的字体栈。
- fontFace：（可选） 映射到 CSS @font-face 规则的字体面数组。这对于包含来自 URL 的网络字体是必需的。单个字体面（变体）的格式应为：
  - fontFamily： 有效的 CSS font-family 描述符。
  - fontWeight： 有效的 CSS font-weight 值。
  - fontStyle： 有效的 CSS font-style 值。
  - fontStretch： 有效的 CSS font-stretch 值。
  - src： 指向字体文件的文件 URL。
  - preview： （可选） 指向用于预览特定字体面的图像的 URL。如果未定义，则会在浏览器中加载 src 资源来渲染预览。
- preview： （可选） 指向用于预览字体族的图像的 URL。如果未定义，则会在浏览器中加载最接近 normal 400 字体面的 src 资源来渲染预览。
categories： 字体族的类别 slug（为字体集注册）数组。

当注册网络字体且未在 font_family_settings 或 fontFace 下提供 preview 图像时，WordPress 将通过 fontFace.src 文件自动加载字体。对于大型字体集，这可能会影响性能，因此建议为网络字体包含预览图像。

至此，你已经学习了构成字体集及其内部字体族的基础部分。一下子消化这么多信息可能有点多。让我们看一个实际例子，并将所学付诸实践。

通过 PHP 注册字体集

注册字体集最直接的方法是通过 PHP。你可以在一个文件中完成所有操作，如果你的字体集只有少量字体，这是理想的选择。如果你有很多字体，你可能需要使用下一节描述的 JSON 方法。

我最喜欢的排版相关网站之一是 Modern Font Stacks，它有一个全面的系统字体列表。我认为从该网站获取一些字体栈并将其引入 WordPress 字体库是个好主意。这也使得第一个例子更容易，因为系统字体不需要字体文件。

在你之前添加到 functions.php 的 themeslug_fonts_collection() 函数内部，粘贴以下代码：

wp_register_font_collection( 'modern-stacks', [
	'name'          => __( 'Modern Stacks', 'themeslug' ),
	'description'   => __( 'A collection of modern system fonts.', 'themeslug' ),
	'font_families' => [
		[
			'font_family_settings' => [
				'fontFamily' => 'system-ui, sans-serif',
				'slug'       => 'system-ui',
				'name'       => __( 'System UI', 'themeslug' ),
			],
			'categories' => [ 'sans-serif' ]
		],
		[
			'font_family_settings' => [
				'fontFamily' => "Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif",
				'slug'       => 'transitional',
				'name'       => __( 'Transitional', 'themeslug' ),
			],
			'categories' => [ 'serif' ]
		],
		[
			'font_family_settings' => [
				'fontFamily' => "'Nimbus Mono PS', 'Courier New', monospace",
				'slug'       => 'monospace-slab-serif',
				'name'       => __( 'Monospace Slab Serif', 'themeslug' ),
			],
			'categories' => [ 'monospace', 'serif' ]
		],
		[
			'font_family_settings' => [
				'fontFamily' => "'Segoe Print', 'Bradley Hand', Chilanka, TSCu_Comic, casual, cursive",
				'slug'       => 'handwritten',
				'name'       => __( 'Handwritten', 'themeslug' ),
			],
			'categories' => [ 'handwriting' ]
		]
	],
	'categories' => [
		[
			'name' => __( 'Handwriting', 'themeslug' ),
			'slug' => 'handwriting'
		],
		[
			'name' => __( 'Monospace', 'themeslug' ),
			'slug' => 'monospace'
		],
		[
			'name' => __( 'Sans Serif', 'themeslug' ),
			'slug' => 'sans-serif'
		],
		[
			'name' => __( 'Serif', 'themeslug' ),
			'slug' => 'serif'
		]
	]
] );

保存文件并刷新浏览器后，重新打开字体模态框时，你应该会看到Modern Stacks选项卡：

覆盖在 WordPress 站点编辑器屏幕上的字体模态框。选中了 Modern Stacks 选项卡，显示现代系统字体列表。

此时，如果你想测试安装其中一种字体，只需按照之前的相同步骤操作即可。

由于系统字体没有关联的字体文件，因此没有文件需要安装到 /wp-content/uploads/fonts 目录中。

通过 JSON 注册字体集

随着向字体集中添加更多字体，从 PHP 管理字体族可能会变得有些笨拙。JSON 通常是存储这些较大数据集合的首选格式，WordPress 支持开箱即用地为你的字体集添加字体族。

让我们稍微改变一下，添加一个新的幻想网络字体集合。与上一节的系统字体不同，这些字体将有物理文件需要安装。

首先，在你已在 functions.php 中创建的 themeslug_font_collections() 函数内部添加以下代码：

wp_register_font_collection( 'fantasy', [
	'name'          => __( 'Fantasy', 'themeslug' ),
	'description'   => __( 'A collection of fantasy fonts.', 'themeslug' ),
	'font_families' => get_theme_file_path( 'assets/fonts/fantasy.json' ),
	'categories' => [
		[
			'name' => __( 'Display', 'themeslug' ),
			'slug' => 'display'
		]
	]
] );

请注意，font_families 参数与上一节 PHP 示例中的参数非常不同。你不是传递字体族定义的数组，而是传递指向 JSON 文件的文件路径。

现在在你的主题中添加一个新的 /assets/fonts/fantasy.json 文件。你将使用此文件来注册字体集中的字体族。

对于 JSON 文件，你可以设置两个顶级属性：

$schema： 对 WordPress 字体集合 JSON 模式的引用，可以在大多数现代代码编辑器中添加提示。
font_families： 字体族定义的数组。与 PHP 方法的不同之处在于，你现在必须使用 JSON 格式。

在本练习中，我引用了来自 Google Fonts 和 WordPress.org 的 URL 作为 src 和 preview 参数。你可以通过 WordPress 的 font-collection.json 文件查看完整示例。你也可以选择使用托管这些资源的自定义 URL，例如 GitHub。

现在将以下代码添加到你的 fantasy.json 文件中：

{
	"$schema": "https://schemas.wp.org/trunk/font-collection.json",
	"font_families": [
		{
			"font_family_settings": {
				"name": "Henny Penny",
				"fontFamily": "Henny Penny, system-ui",
				"slug": "henny-penny",
				"fontFace": [
					{
						"src": "https://fonts.gstatic.com/s/hennypenny/v17/wXKvE3UZookzsxz_kjGSfMQvt3M7tMDT.woff2",
						"fontWeight": "400",
						"fontStyle": "normal",
						"fontFamily": "Henny Penny",
						"preview": "https://s.w.org/images/fonts/17.7/previews/henny-penny/henny-penny-400-normal.svg"
					}
				],
				"preview": "https://s.w.org/images/fonts/17.7/previews/henny-penny/henny-penny.svg"
			},
			"categories": [ "display" ]
		},
		{
			"font_family_settings": {
				"name": "MedievalSharp",
				"fontFamily": "MedievalSharp, system-ui",
				"slug": "medievalsharp",
				"fontFace": [
					{
						"src": "https://fonts.gstatic.com/s/medievalsharp/v26/EvOJzAlL3oU5AQl2mP5KdgptAqp6MwvXLDk.woff2",
						"fontWeight": "400",
						"fontStyle": "normal",
						"fontFamily": "MedievalSharp",
						"preview": "https://s.w.org/images/fonts/17.7/previews/medievalsharp/medievalsharp-400-normal.svg"
					}
				],
				"preview": "https://s.w.org/images/fonts/17.7/previews/medievalsharp/medievalsharp.svg"
			},
			"categories": [ "display" ]
		},
		{
			"font_family_settings": {
				"name": "Metamorphous",
				"fontFamily": "Metamorphous, system-ui",
				"slug": "metamorphous",
				"fontFace": [
					{
						"src": "https://fonts.gstatic.com/s/metamorphous/v20/Wnz8HA03aAXcC39ZEX5y1330OSCthTsmaQ.woff2",
						"fontWeight": "400",
						"fontStyle": "normal",
						"fontFamily": "Metamorphous",
						"preview": "https://s.w.org/images/fonts/17.7/previews/metamorphous/metamorphous-400-normal.svg"
					}
				],
				"preview": "https://s.w.org/images/fonts/17.7/previews/metamorphous/metamorphous.svg"
			},
			"categories": [ "display" ]
		}
	]
}

保存文件并刷新浏览器窗口后，你应该会在字体模态框中看到一个新的Fantasy选项卡，其中包含你注册的字体：

覆盖在 WordPress 站点编辑器屏幕上的字体模态框。选中了 Fantasy 选项卡，显示各种幻想字体。

与之前一样，这些字体可以像任何其他字体一样安装和使用。

通过 JSON 为字体集注册字体族的缺点是，无法引用动态 URL（例如主题文件夹）作为字体文件源和预览图像。通过第三方站点托管这些资源可能会违反主题审查指南（仅允许 Google Fonts CDN）。在某些情况下，你可能别无选择，只能使用 PHP 方法。

注销字体集

要注销字体集，必须使用 wp_unregister_font_collection() 函数，该函数接受先前注册的字体集的单个 $slug 参数：

wp_unregister_font_collection( string $slug );

你可以使用此函数来注销由第三方插件、父主题（如果你正在构建子主题）甚至 WordPress 注册的字体集。让我们深入了解一个实际示例。

注销 Google Fonts 字体集

如果你像我一样从事主题开发很长时间，你可能现在已经知道，向最终用户开放整个 Google Fonts 库是破坏你主题精心设计的排版的秘诀。并非所有字体都是一样的。

如果你想要更精选的体验，我建议禁用默认的 Google Fonts 字体集，只提供你知道与你的主题配合良好的字体。

要注销 Google Fonts 字体集，请在 functions.php 中的 themeslug_font_collections() 函数内添加以下代码：

wp_unregister_font_collection( 'google-fonts' );

当你打开字体模态框时，应该只看到你之前注册的Modern Stacks和Fantasy字体集：

覆盖在 WordPress 站点编辑器屏幕上的字体模态框。显示了库、上传和自定义字体集选项卡，但 Google Fonts 选项卡已被移除。

主题的限制

自定义字体集（以及字体库功能整体）

云策 WordPress 开发者社区

WordPress 社区新闻

如何为字体库注册自定义字体集

字体集如何工作

注册字体集

注册函数

字体族定义

通过 PHP 注册字体集

通过 JSON 注册字体集

注销字体集

注销 Google Fonts 字体集

主题的限制