包含资产

最后更新：2026-10-05 15:56:51

许多区块主题无需加载任何资源。就设计方面而言，其中大部分可以通过“全局设置和样式”系统来处理。但在某些情况下，您可能需要包含 CSS 样式表、自定义 JavaScript 文件，甚至是其他类型的媒体。

如果您熟悉 HTML，您可能习惯于通过 <link rel=”stylesheet”/> 或 <style> 标签来包含 CSS 样式表。对于通过 <script> 标签包含 JavaScript 也是如此。但您绝不应该在主题中手动硬编码这些 HTML 元素。

WordPress 具有特定的钩子来确定何时加载脚本/样式以及用于生成标记的函数。这确保了 WordPress、任何已激活的插件和您的主题都能协同工作。

在本文档中，您将学习生成指向资源文件的正确 URL 所需的功能，以及如何将脚本、样式和其他资源包含到您的主题中。

与核心概念章节中的一些旧页面相比，本文档是一个飞跃。您需要一些基础的 PHP 和 HTML 知识才能跟上。您还必须了解如何使用主题的 functions.php 文件。这对于加载 CSS 样式表和 JavaScript 文件是必要的。

URL 和目录路径函数

在包含资源之前，您应该熟悉 WordPress 提供的用于获取主题内 URL 和目录路径的一些实用程序函数。在包含任何类型的资源时，您应始终使用这些辅助函数以确保 URL 或路径正确。

三个主要的 URL 辅助函数是：

get_stylesheet_uri()：返回当前主题的 style.css 文件 URL。
get_theme_file_uri( $file )：返回当前主题的 URL，并带有可选的 $file 参数。如果子主题处于活动状态且文件不存在，则回退到父主题。
get_parent_theme_file_uri( $file )：返回父主题的 URL，并带有可选的 $file 路径。

对于目录路径（在资源中较少需要），有两个主要函数：

get_theme_file_path( $file )：返回当前主题的目录路径，并带有可选的 $file 参数。如果子主题处于活动状态且文件不存在，则回退到父主题。
get_parent_theme_file_path( $file )：返回父主题的目录路径，并带有可选的 $file 参数。

包含 CSS

wp_enqueue_style() 是用于将样式表加入队列的主要函数，它告诉 WordPress 您希望将其放入队列以加载。您会在 functions.php 文件中的操作钩子回调中使用此函数，这在“自定义功能”中已介绍过。您将在接下来的部分中学习针对特定场景应使用哪些操作钩子。

查看函数签名：

wp_enqueue_style( 
	string $handle, 
	string $src           = '', 
	string[] $deps        = array(), 
	string|bool|null $ver = false, 
	string $media         = 'all'
);

您可以使用这些参数：

$handle 是样式表的唯一名称/ID，应以您的主题 slug 为前缀。
$src 是您的样式表的文件 URL。虽然从技术上讲这是一个可选参数，但实际上加载特定样式表时是必需的。
$deps 是一个可选数组，列出您的样式表所依赖的其他样式表句柄。
$ver 设置您的样式表的版本号，用于缓存清除。默认为当前 WordPress 版本。
$media 用于指定要为此样式表加载哪种类型的媒体，例如 all（默认）、screen、print 或 handheld。

如果您正在将位于主题中 /assets/css/example.css 的样式表加入队列，您的函数调用可能如下所示：

wp_enqueue_style( 
	'theme-slug-example',
	get_parent_theme_file_uri( 'assets/css/example.css' ),
	array(),
	wp_get_theme()->get( 'Version' ),
	'all'
);

上面的代码使用 wp_get_theme() 获取主题的版本号以进行缓存清除，但您可以将其保留为默认值或使用完全自定义的内容。

前端样式表

在网站的页面前端加载样式表时，对于大多数场景，您将使用 wp_enqueue_scripts 钩子。

假设您想使用 get_stylesheet_uri() 函数加载主题的 style.css 文件。您可以通过将以下代码添加到您的 functions.php 文件中来实现：

add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );

function theme_slug_enqueue_styles() {
	wp_enqueue_style( 
		'theme-slug-style', 
		get_stylesheet_uri()
	);
}

请记住，如果需要，您也可以向 wp_enqueue_style() 函数传递其他参数。上面的代码是加载样式表所需的最小内容。

让我们进一步假设您想加载位于主题中 /assets/css/primary.css 的第二个样式表。为此，您将使用 get_parent_theme_file_uri() 函数获取正确的 URL。

这是同时加入队列两个样式表时您的代码外观：

add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );

function theme_slug_enqueue_styles() {
	wp_enqueue_style(
		'theme-slug-style', 
		get_stylesheet_uri()
	);

	wp_enqueue_style( 
		'theme-slug-primary',
		get_parent_theme_file_uri( 'assets/css/primary.css' )
	);
}

内联样式

有时您可能需要在前端的 <head> 区域添加一些内联 CSS。WordPress 具有针对此特定场景的 wp_add_inline_style() 函数。

查看函数签名：

wp_add_inline_style( 
	string $handle, 
	string $data 
);

在这种情况下，您必须传递一个 $handle 参数以匹配已为页面加入队列的现有样式表的句柄。$data 参数是您的自定义 CSS 代码。

让我们通过添加一小段将背景色设置为浅灰色的 CSS 来扩展上一节的代码：

add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );

function theme_slug_enqueue_styles() {
	wp_enqueue_style(
		'theme-slug-style', 
		get_stylesheet_uri()
	);

	wp_enqueue_style( 
		'theme-slug-primary',
		get_parent_theme_file_uri( 'assets/css/primary.css' )
	);

	wp_add_inline_style( 
		'theme-slug-primary', 
		'body { background: #eee; }'
	);
}

在 wp_add_inline_style() 函数调用中，代码使用现有的 theme-slug-primary 句柄来附加内联样式。

编辑器样式表

当创建具有前端自定义 CSS 的主题时，您几乎总是希望您的自定义样式也出现在编辑器中。这将在整个站点上创建一致的用户体验。但 WordPress 不会自动在编辑器中加载您的前端样式表。

为此，您需要使用 add_editor_style() 函数：

add_editor_style( array|string $stylesheet = 'editor-style.css' );

它接受一个 $stylesheet 参数，可以是单个样式表文件名或文件名数组。这些可以相对于主题文件夹或完整 URL。

请注意，当使用相对 URL 时，具有相同文件名的子主题中的文件将优先。这就是为什么通常最好使用完整样式表 URL 的最佳做法。

此代码片段显示了如何将当前主题的主要 style.css 文件添加为编辑器样式：

add_action( 'after_setup_theme', 'theme_slug_setup' );

function theme_slug_setup() {
	add_editor_style( get_stylesheet_uri() );
}

如果您想添加之前示例中的 style.css 文件和 primary.css，您可以将它们作为数组传递：

add_action( 'after_setup_theme', 'theme_slug_setup' );

function theme_slug_setup() {
	add_editor_style( array(
		get_stylesheet_uri(),
		get_parent_theme_file_uri( 'assets/css/primary.css' )
	) );
}

区块样式表

WordPress 还包括一个 wp_enqueue_block_style() 函数，用于在编辑器和页面前端加载每个区块的样式表。有关此内容的完整详细信息，请参阅“区块样式表”文档。

对于对区块样式表的深入探索，请阅读 WordPress 开发者博客上的利用 theme.json 和每个区块的样式以获得更高效的主题。

包含 JavaScript

与样式表一样，WordPress 具有用于将 JavaScript 文件加入队列的主要函数：wp_enqueue_script()。您也会在 functions.php 文件中的操作钩子回调中使用此函数，并且您将在以下部分中学习要使用哪些钩子。

查看函数签名：

wp_enqueue_script( 
	string $handle, 
	string $src           = '', 
	string[] $deps        = array(), 
	string|bool|null $ver = false, 
	array|bool $in_footer = false
);

您可以使用这些参数：

$handle: 脚本的唯一名称/ID，应以您的主题 slug 为前缀。
$src: 您的脚本的文件 URL。虽然从技术上讲这是一个可选参数，但实际上加载特定脚本时是必需的。
$deps: 一个可选数组，列出您的脚本所依赖的其他脚本句柄。
$ver: 设置您的脚本的版本号，用于缓存清除。默认为当前 WordPress 版本。
$in_footer: 确定是否在页眉或页脚中加载脚本。自 WordPress 6.3 起，此参数接受一个数组值：
- strategy: 接受 'defer'（默认）或 'async' 来设置脚本加载策略。
- in_footer: 一个布尔值，用于确定是否在页眉或页脚中加载脚本。

如果您正在将位于主题中 /assets/js/example.js 的脚本加入队列，您的函数调用可能如下所示：

wp_enqueue_script( 
	'theme-slug-example',
	get_parent_theme_file_uri( 'assets/js/example.js' ),
	array(),
	wp_get_theme()->get( 'Version' ),
	true
);

前端 JavaScript

在网站的页面前端加载样式表时，对于大多数场景，您将使用 wp_enqueue_scripts 钩子。

假设您有一个位于主题中 assets/js/navigations.js 的自定义导航脚本。为此，您将使用 get_parent_theme_file_uri() 函数获取正确的 URL。

这是加入队列脚本时您的函数外观：

add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_scripts' );

function theme_slug_enqueue_scripts() {
	wp_enqueue_script( 
		'theme-slug-navigation',
		get_parent_theme_file_uri( 'assets/js/navigation.js' ),
		array(),
		wp_get_theme()->get( 'Version' ),
		true
	);
}

内联 JavaScript

有时您可能想在前端的 <head> 区域添加一些内联 JavaScript。WordPress 具有用于此目的的 wp_add_inline_script() 函数。

查看函数签名：

wp_add_inline_script( 
	string $handle, 
	string $data, 
	string $position = 'after' 
);

与样式表类似，您必须通过 $handle 参数将此内容附加到已加入队列的脚本。第二个参数 $data 应该是 JavaScript 代码本身。这里的区别是添加了第三个参数 $position，它允许您将内联脚本定位在它所附加的脚本之前或之后。

以下代码基于上一节的导航脚本，通过向其添加内联脚本来构建：

add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_scripts' );

function theme_slug_enqueue_scripts() {
	wp_enqueue_script( 
		'theme-slug-navigation',
		get_parent_theme_file_uri( 'assets/js/navigation.js' ),
		array(),
		wp_get_theme()->get( 'Version' ),
		true
	);

	wp_add_inline_script( 
		'theme-slug-navigation', 
		'console.log( "Testing" );'
	);
}

在 wp_add_inline_script() 函数调用中，代码使用现有的 theme-slug-navigation 句柄来附加内联样式。

编辑器 JavaScript

当您需要为区块编辑器加载 JavaScript 文件时，您必须使用 enqueue_block_editor_assets 钩子。请注意，这是用于在管理页面本身加载脚本，而不是在内容 iframe 内。

假设您有一个需要在编辑器中加载的 assets/js/editor.js 文件。您的代码应如下所示：

add_action( 'enqueue_block_editor_assets', 'theme_slug_enqueue_editor_scripts' );

function theme_slug_enqueue_editor_scripts() {
	wp_enqueue_script( 
		'theme-slug-editor',
		get_parent_theme_file_uri( 'assets/js/editor.js' ),
		array(),
		wp_get_theme()->get( 'Version' ),
		true
	);
}

通常，主题不需要为编辑器本身加载 JavaScript。但对于高级用例，这可能是必要的。还建议与 @wordpress/scripts 包集成以进行更易于管理。有关如何执行此操作的更多信息，请阅读超越区块样式，第 1 部分：在主题中使用 WordPress scripts 包。

默认 WordPress 脚本

WordPress 捆绑了许多自定义和第三方脚本。如果您需要它们中的任何一个而不是加载自定义版本，您应始终使用这些脚本。这确保您避免与插件发生冲突。

一些脚本在 wp_enqueue_script() 文档中引用，但该列表可能并不总是最新的。您可以在 wp-includes/script-loader.php 中找到包含文件的完整列表。

包含图像

区块主题通常不需要包含图像，除非在模式中。您将在“区块模式”文档中了解更多关于这些内容。但为了快速概述，让我们看看如何在主题中引用图像。

假设您有一个位于 assets/img/example.webp 的图像文件，您将使用此代码来引用正确的 URL：

<img src="<?php echo esc_url( get_parent_theme_file_uri( 'assets/img/example.webp' ) ); ?>" alt="" />

请注意，上面的示例使用了 get_parent_theme_file_uri()。在大多数情况下，这是正确的函数。

但如果您正在构建子主题或一个您希望允许其他子主题作者覆盖图像的主题，您可以使用 get_theme_file_uri() 代替：

<img src="<?php echo esc_url( get_theme_file_uri( 'assets/img/example.webp' ) ); ?>" alt="" />

包含字体

通常，您会期望字体直接位于资源文档下。但 WordPress 具有通过 theme.json 文件加载字体的特殊方法，该方法与编辑器集成。此文档位于全局设置和样式章节的“排版”页面下。