如何在WordPress中为所有标题元素添加data-splitting自定义属性

核心需求 #

给全站所有<h1>、<h2>、<h3>、<h4>标签添加data-splitting属性，使标签变为<h1 data-splitting>、<h2 data-splitting>形式，以实现标题动画效果，网站使用Cloudflare全缓存。

用户疑问解答 #

1. 硬编码需修改主题文件还是WordPress核心文件？ #

绝对不要修改WordPress核心文件——核心文件在系统更新时会被完全覆盖，所有自定义修改都会丢失。正确做法是修改当前使用的主题文件，如果是第三方主题，建议先创建子主题再修改，避免主题更新时丢失自定义内容。

2. 这类自定义属性的名称是什么，是否等同于<h2>加<data-splitting>？ #

这类属性叫做HTML自定义数据属性（data-* attributes），是HTML5标准允许的自定义属性，用于存储页面或应用的私有数据。它不是<h2>加<data-splitting>标签，而是直接作为<h2>标签的属性存在，比如<h2 data-splitting>就是给h2标签添加了一个名为data-splitting的属性（属性值为空）。

已尝试的JS方法失效原因及修复方案 #

你之前尝试的几种JS写法都存在问题，以下是具体原因和修复后的方案：

问题分析 #

1. 通过functions.php引入外部脚本时，代码缺少依赖声明——你的脚本依赖jQuery，但没有告诉WordPress加载jQuery，导致$未定义；
2. 手动添加async属性会让脚本异步加载，可能在DOM未完全渲染时就执行，无法找到标题元素；
3. 内联脚本的写法有误：
   • 写法一的脚本标签未闭合（</script少了>`）；
   • 写法二的jQuery.noConflict()使用方式错误，同时$('document')应该是$(document)（不需要引号）。

修复后的JS方案 #

方案1：通过functions.php正确引入脚本

在主题的functions.php中添加以下代码：

function enqueue_splitting_script() {
    // 加载WordPress自带的jQuery
    wp_enqueue_script('jquery');
    // 引入自定义脚本，声明依赖jQuery
    wp_enqueue_script( 
        'splitting-script', 
        'https://example.com/h.js', 
        array('jquery'), // 声明依赖jQuery
        '1.0', 
        true // 脚本放在页面底部，确保DOM加载完成后执行
    );
}
add_action('wp_enqueue_scripts', 'enqueue_splitting_script');

然后修改外部h.js的代码：

jQuery(document).ready(function($) {
    // 给所有h1-h4添加data-splitting属性
    $('h1, h2, h3, h4').attr('data-splitting', '');
});

方案2：内联脚本直接添加到头部（修复写法错误）

确保脚本标签正确闭合，并且使用正确的DOM ready写法：

<script>
jQuery(document).ready(function($) {
    $('h1, h2, h3, h4').attr('data-splitting', '');
});
</script>

或者使用原生JS（不依赖jQuery，兼容性更好）：

<script>
document.addEventListener('DOMContentLoaded', function() {
    const headings = document.querySelectorAll('h1, h2, h3, h4');
    headings.forEach(heading => {
        heading.setAttribute('data-splitting', '');
    });
});
</script>

硬编码实现方案（无需JS） #

如果不想用JS，直接在主题文件中修改标题输出的代码：

1. 找到主题中负责输出标题的模板文件，比如header.php（页面标题）、single.php（文章标题）、page.php（页面内容中的标题）等；
2. 找到输出<h1>、<h2>等标签的代码，比如the_title( '<h1 class="entry-title">', '</h1>' );，修改为：

the_title( '<h1 class="entry-title" data-splitting>', '</h1>' );

3. 对所有h1-h4标签的输出代码做同样修改即可。

注意：如果主题使用了区块编辑器，可能需要通过过滤器来修改区块输出的标题属性，比如添加以下代码到functions.php：

add_filter('render_block', function($block_content, $block) {
    if (in_array($block['blockName'], array('core/heading'))) {
        $level = $block['attrs']['level'] ?? 2;
        // 只处理h1-h4
        if ($level >=1 && $level <=4) {
            $block_content = str_replace("<h{$level}", "<h{$level} data-splitting", $block_content);
        }
    }
    return $block_content;
}, 10, 2);

Cloudflare缓存注意事项 #

因为网站使用Cloudflare全缓存，修改后需要清除Cloudflare的缓存，同时清除WordPress的缓存（如果有使用缓存插件），才能看到修改后的效果。

内容的提问来源于stack exchange，提问作者CrazyJack