包含 CSS 和 JavaScript（已归档）

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

这是一个旧页面，已归档以替代核心概念章节中较新的包含资源文档。该页面最终将被移除并重定向到新文档。

在创建主题时，您可能希望创建额外的样式表或 JavaScript 文件。但是请记住，WordPress 网站不仅会激活您的主题，还会使用许多不同的插件。因此，为了确保一切和谐工作，重要的一点是主题和插件必须使用标准的 WordPress 方法加载脚本和样式表。这将确保站点保持高效且不会出现不兼容问题。

向 WordPress 添加脚本和样式是一个相当简单的过程。本质上，您将创建一个函数来注册所有您的脚本和样式。当注册一个脚本或样式时，WordPress 会创建句柄（handle）和路径以查找您的文件及其可能存在的依赖项（如 jQuery），然后您将通过钩子插入您的脚本和样式。

注册脚本和样式

向主题添加脚本和样式的正确方法是在 functions.php 文件中注册它们。所有主题都需要 style.css 文件，但可能需要添加其他文件以扩展您主题的 functionality。

提示：WordPress 作为软件包的一部分包含了许多 JavaScript 文件，包括 jQuery 等常用库。在添加自己的 JavaScript 之前，检查是否可以利用已包含的库。

基本步骤如下：

使用 wp_enqueue_script()、wp_enqueue_style() 或 wp_enqueue_block_style 注册脚本或样式。

样式表

您的 CSS 样式表用于自定义主题的外观。样式表也是存储有关您主题的信息的文件。因此，每个主题都需要 style.css 文件。

而不是在 header.php 文件中加载样式表，您应该使用 wp_enqueue_style 来加载它。为了加载您的主样式表，您可以在 functions.php 中注册它。

要注册 style.css：

wp_enqueue_style( 'style', get_stylesheet_uri() );

这将查找名为 "style"的样式表并加载它。

注册样式的函数基本语法如下：

wp_enqueue_style( $handle, $src, $deps, $ver, $media );

您可以包含这些参数：

$handle 仅仅是样式表的名称。
$src 是其所在位置。其余参数是可选的。
$deps 指的是该样式表是否依赖于另一个样式表。如果设置了此项，除非先加载其依赖的样式表，否则不会加载此样式表。
$ver 设置版本号。
$media 可以指定要在此处加载样式的媒体类型，例如 'all'（所有）、'screen'（屏幕）、'print'（打印）或 'handheld'（手持设备）。

因此，如果您想在主题根目录下的名为 "CSS"的文件夹中加载名为 "slider.css" 的样式表，您将使用：

wp_enqueue_style( 'slider', get_template_directory_uri() . '/css/slider.css', false, '1.1', 'all');

为块样式包含 CSS

除了 wp_enqueue_style() 之外，您还可以使用 wp_enqueue_block_style() 来注册块的样式。 wp_enqueue_block_style() 需要 WordPress 5.9 或更高版本。

创建块主题的关键部分是性能。通过 wp_enqueue_block_style()，当在页面上使用块时，主题仅加载所选块的 CSS。

额外的样式会在编辑器中和前台加载（在由 WordPress 和 Gutenberg 插件提供的块样式之后）。您可以使用此方法添加无法通过 theme.json 添加的块样式。例如媒体查询。

以下代码示例更改了最新评论块中日期的字体大小和文本颜色。因为这是一个嵌套在其他 HTML 元素中的 time HTML 元素，所以无法使用 theme.json 进行样式设置。

首先，创建一个名为块的新的 CSS 文件：latest-comments.css。
放置文件的位置取决于您如何组织主题文件。在示例中，该文件放置在文件夹 assets/CSS/blocks 内。

时间元素的 CSS 类是 wp-block-latest-comments__comment-date。前缀和块名称后跟部分（partial），由两个下划线分隔。

您可以在编码指南中阅读有关块编辑器命名约定的更多信息。

文本颜色和字体大小是通过从 theme.json生成的 CSS 自定义属性添加的：

.wp-block-latest-comments__comment-date {
	color: var(--wp--preset--color--primary);
	font-size: var(--wp--preset--font-size--small);
}

接下来，在主题的设置函数内注册块样式。

将块名称放在数组中以加载多个块样式。
foreach 循环遍历数组中的每个块并创建句柄（handle）、源（src）和路径参数。
wp_enqueue_block_style() 然后使用块名称和参数注册文件：
wp_enqueue_block_style( "prefix/blockname", $args );

在代码示例中，前缀是"core"，因为样式是针对核心块的。当您为插件的块设置样式时，需要调整前缀。

function myfirsttheme_setup() {
	/*
	 * Load additional block styles.
	 */
	$styled_blocks = ['latest-comments'];
	foreach ( $styled_blocks as $block_name ) {
		$args = array(
			'handle' => "myfirsttheme-$block_name",
			'src'    => get_theme_file_uri( "assets/css/blocks/$block_name.css" ),
			$args['path'] = get_theme_file_path( "assets/css/blocks/$block_name.css" ),
		);
		wp_enqueue_block_style( "core/$block_name", $args );
	}
}
add_action( 'after_setup_theme', 'myfirsttheme_setup' );

脚本

主题所需的任何额外的 JavaScript 文件都应使用 wp_enqueue_script 加载。这确保了正确的加载和缓存，并允许使用条件标签来针对特定页面。这些是可选的。

wp_enqueue_script 使用了与 wp_enqueue_style类似的语法。

注册您的脚本：

wp_enqueue_script( $handle, $src, $deps, $ver, $args );

$handle 是脚本的名称。
$src 定义了脚本的位置。
$deps 是一个可以处理您的新脚本依赖的任何脚本的数组，例如 jQuery。
$ver 允许您列出版本号。
$args 是定义脚印打印（通过 in_footer键）和脚本加载策略（通过strategy键）的参数的数组，例如 defer或 async。这自 WordPress 6.3版本以来替换/覆盖了 $in_footer参数。

您的注册函数可能如下所示：

wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array( 'jquery' ), 1.1, true);

延迟脚本加载

WordPress 通过 $args数组参数中引入的新strategy键，支持在 wp_register_script()和 wp_enqueue_script()函数中指定脚本加载策略。

支持的策略如下：

defer
- 通过向$参数添加数组键值对'strategy' => 'defer'来添加。
- 标记为延迟执行的脚本——通过 defer 脚本属性——仅在 DOM 树完全加载后执行（但在 DOMContentLoaded和 window load事件之前）。与异步脚本不同，延迟脚本按照它们在 DOM 中打印/添加的顺序执行。
async
- 通过向$args参数指定数组键值对'strategy' => 'async'来添加。
- 标记为异步执行的脚本——通过 async 脚本属性——在浏览器加载它们时立即执行。由于脚本 B（尽管在 DOM 中添加在脚本 A之后）可能在其之前完成加载，因此异步脚本没有保证的执行顺序。此类脚本可能在 DOM 完全构建之前或DOMContentLoaded事件之后执行。

以下是在脚本注册期间指定加载策略的示例：

wp_register_script( 
    'foo', 
    '/path/to/foo.js', 
    array(), 
    '1.0.0', 
    array( 
        'strategy'  => 'defer',
    )
);

使用 wp_enqueue_script()时采用相同的方法。

在指定延迟脚本加载策略时，会考虑脚本的依赖树（其依赖项和/或被依赖项），以决定“合格策略”，从而避免应用对某个脚本有效但对同一棵树中的其他脚本有害的策略。因此，您通过 $args 参数传递的预期加载策略可能不是最终（选择的）策略，但它永远不会损害（或比）预期策略更严格。

评论回复脚本

WordPress 的评论开箱即具有相当多的功能，包括分层评论和增强的评论表单。为了使评论正常工作，它们需要一些 JavaScript。但是，由于需要在该 JavaScript中定义某些选项，因此应将 comment-reply 脚本添加到每个使用评论的经典主题。

在块主题中，当您放置一个评论块时就会包含此脚本。您不需要手动添加它。

在经典主题中包含评论回复的正确方法是使用条件标签检查是否存在特定条件，以便不会不必要地加载该脚本。例如，您可以仅在使用 is_singular 的单篇文章页面上加载脚本，并检查是否选择了用户“启用分层评论”。因此，您可以设置一个函数：

if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
	wp_enqueue_script( 'comment-reply' );
}

如果用户启用了评论且我们处于文章页面，则加载评论回复脚本。否则不会。

组合注册函数

最好将所有注册的脚本和样式合并到一个函数中，然后使用 wp_enqueue_scripts 操作调用它们。该函数和操作应位于初始设置（如上所述）的下方：

function add_theme_scripts() {
	wp_enqueue_style( 'style', get_stylesheet_uri() );

	wp_enqueue_style( 'slider', get_template_directory_uri() . '/css/slider.css', array(), '1.1', 'all' );

	wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array( 'jquery' ), 1.1, true );

	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'wp_enqueue_scripts', 'add_theme_scripts' );

WordPress 包含和注册的默认脚本

默认情况下，WordPress 包含许多网络开发人员常用的流行脚本以及 WordPress 自身使用的脚本。其中一些列在此参考页面上：

wp_enqueue_script()

列表远非完整。您可以在 wp-includes/script-loader.php 中找到包含文件的完整列表。

更新日志：

更新于 2023-02-24：添加了有关 wp_enqueue_block_style()的信息。
更新于 2024-06-06：添加警报以引导读者查看新文档。