如何在 WordPress 主题中添加自定义 JavaScript

你想在 WordPress 主题中添加自定义 JavaScript。也许是滚动效果、第三方跟踪代码片段或交互功能。你将代码粘贴到模板文件中,结果什么都不起作用——或者更糟的是,你将 PHP 和 JavaScript 混在一起,导致一切崩溃。

这种情况经常发生。解决方法很简单:使用 WordPress 内置的脚本管理系统,而不是硬编码 <script> 标签。

为什么应该在 WordPress 中排队加载脚本

WordPress 运行在一个由主题和插件组成的复杂生态系统上。当你直接在模板中插入 JavaScript 时,会产生以下问题:

• 重复加载:多个插件可能加载同一个库。
• 依赖失败:你的脚本在其依赖项加载之前运行。
• 缓存问题:浏览器无法正确缓存内联脚本。
• 冲突:脚本之间没有协调而相互干扰。

wp_enqueue_script 函数通过让 WordPress 管理脚本加载顺序、依赖关系和输出位置来解决这些问题。

向 WordPress 添加 JavaScript 的正确方法

步骤 1:创建你的 JavaScript 文件

将 JavaScript 放在主题目录中。常见的结构如下:

your-theme/
├── js/
│   └── custom.js
├── functions.php
└── style.css

编写纯净的 JavaScript,不要混入 PHP:

document.addEventListener('DOMContentLoaded', function() {
    // Your code here
});

步骤 2:在 functions.php 中排队加载脚本

将以下代码添加到主题的 functions.php 中:

function mytheme_enqueue_scripts() {
    wp_enqueue_script(
        'mytheme-custom',                              // Handle
        get_template_directory_uri() . '/js/custom.js', // Source
        array(),                                        // Dependencies
        '1.0.0',                                        // Version
        array( 'in_footer' => true )                   // Load in footer
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

对于子主题,使用 get_stylesheet_directory_uri() 而不是 get_template_directory_uri()。

理解 wp_enqueue_script 参数

该函数接受五个参数:

条件脚本加载

当脚本仅在特定页面需要时,不要在所有地方加载:

function mytheme_enqueue_scripts() {
    if ( is_singular( 'post' ) ) {
        wp_enqueue_script( 'mytheme-post-scripts', /* ... */ );
    }

    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'mytheme-contact-form', /* ... */ );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

性能优先的加载策略

WordPress 6.3 引入了对 defer 和 async 加载的原生支持:

wp_enqueue_script(
    'mytheme-analytics',
    get_template_directory_uri() . '/js/analytics.js',
    array(),
    '1.0.0',
    array(
        'in_footer' => true,
        'strategy'  => 'defer'
    )
);

Defer 在 DOM 解析后执行脚本,同时保持它们声明的顺序。Async 在脚本下载完成后立即执行,不保证顺序。大多数情况下使用 defer,对于像分析这样的独立脚本使用 async。

现代 WordPress:脚本模块和区块集成

WordPress 持续改进其 JavaScript 处理方式。值得注意的两个发展:

脚本模块 API:WordPress 6.5 引入了 wp_enqueue_script_module() 用于原生 ES 模块。这使得能够使用适当的模块导入来实现现代 JavaScript 模式。

基于区块的主题:如果你正在构建区块,请在 block.json 中使用 viewScript 或 viewScriptModule 字段声明脚本,而不是手动排队。当区块渲染时,WordPress 会自动处理加载。

这些方法与传统的排队加载方式并存——根据项目需求选择。

结论

向 WordPress 主题添加自定义 JavaScript 需要使用排队系统,而不是硬编码脚本标签。创建单独的 JavaScript 文件,使用 wp_enqueue_script 注册它们,正确声明依赖关系,并使用条件加载来避免不必要的请求。为了获得更好的性能,利用 WordPress 6.3 以来可用的 defer 和 async 策略。

模式很简单:将 PHP 和 JavaScript 分开,让 WordPress 管理加载,你的脚本将在主题和插件之间可靠地工作。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.