WordPress主题 PJAX 无刷新以及渲染问题的修复

This note was originally clipped from https://hiripple.com/archives/2982

PJAX是一种用于加快网页加载速度的技术,结合了HTML5的pushState API和Ajax技术。使用PJAX可以实现局部页面内容的更新,减少不必要的页面刷新,提高用户体验和降低服务器负载。但也有一些局限性,如对于不支持HTML5 pushState API的浏览器可能无法正常工作。在WordPress主题中配置PJAX时需要解决一些问题,如Matomo追踪代码、左侧目录刷新、Lazyload等。|

powered by RippleAi

本文最后更新于 343 天前,其中的信息可能已经有所发展或改变。

近期为自己的wp主题配置了PJAX~此前使用的是Turbolinks插件,因为插件属于不可控元素,产生过多BUG后还是决定手动配置更为先进的PJAX(其实BUG更多了,但至少可以逐一排查...)

原理

PJAX原理

GitHub - defunkt/jquery-pjax: pushState + ajax = pjax

pushState + ajax = pjax. Contribute to defunkt/jquery-pjax development by creating an account on GitHub.

github.com

PJAX(Pushstate + Ajax)是一种用于加快网页加载速度的技术。它结合了HTML5的pushState API和Ajax技术,使得在不刷新整个页面的情况下,可以实现局部页面内容的更新。PJAX的主要原理可以分为以下几个步骤:

  1. 用户点击链接:当用户点击一个链接时,PJAX会拦截该链接的点击事件。
  2. 阻止默认行为:PJAX会阻止浏览器执行默认的链接跳转行为,避免整个页面的刷新。
  3. 发送Ajax请求:接着,PJAX会通过Ajax发送一个请求到服务器,请求目标链接的内容。这个请求通常会包含一个特殊的请求头,以便服务器能够识别这是一个PJAX请求,从而仅返回局部更新所需的内容,而非整个页面的HTML代码。
  4. 更新URL和页面内容:当服务器返回局部内容后,PJAX会利用HTML5的pushState API来更新浏览器地址栏中的URL,然后用返回的内容替换页面中指定的容器元素。这样一来,用户就会感觉像是进行了一次正常的页面跳转,但实际上只是局部内容发生了更新。
  5. 更新浏览器历史记录:通过pushState API更新URL之后,浏览器的历史记录也会相应地更新。这样,用户在点击浏览器的前进和后退按钮时,可以按照预期的方式导航。

PJAX的优势在于减少了不必要的页面刷新,提高了用户体验。同时,由于只需要加载局部内容,它还有助于降低服务器负载。然而,PJAX也有一些局限性,例如对于不支持HTML5 pushState API的浏览器,PJAX可能无法正常工作。

引入PJAX

引入JS文件

前往主题的function.php,添加如下代码入队:

function add_pjax() {
    wp_register_script('pjax', 'https://cdn.bootcss.com/jquery.pjax/2.0.1/jquery.pjax.min.js', array('jquery'), '2.0.1', true);
    wp_enqueue_script('pjax');
}
add_action('wp_enqueue_scripts', 'add_pjax');

PHP

包裹PJAX容器

本段部分参考至https://alpha.skywt.cn/post/typecho-pjax-and-some-problems

F12检查自己博客的html结构,找到需要PJAX动态刷新的类,并将它包裹在PJAX容器中:

一般的网页结构:

<html>
    <head>
        <!-- ... -->
    </head>
    <body>
        <header><!-- 页眉,标题什么的 --></header>
        <nav><!-- 导航栏什么的 --></nav>
        <main id="pjax-container">
            <!-- 网站主体内容,文章列表 / 文章内容 / 评论什么的 -->
        </main>
        <script>
            // 下面要加上的代码
        </script>
        <footer><!-- 页脚什么的 --></footer>
    </body>
</html>

HTML

只需前往header.php以及footer.php中找到相应部分即可,在PJAX容器后方添加初始化代码(这里是Wordpress版本):

<script>
	jQuery(document).ready(function($) {
    $(document).pjax('a[href^="<?php echo home_url(); ?>"]:not(a[target="_blank"])', {
        container: '#pjax-container',
        fragment: '#pjax-container'
    });

    $(document).on('pjax:send', function() {
        $('#pjax-container').fadeTo(700,0.0); //这里添加了一个淡入动画
        // alert('开始加载');
    // 开始加载时要运行的代码(如显示加载动画)
    });

    $(document).on('pjax:complete', function() {
        $('#pjax-container').fadeTo(700,1);
        // 完成加载时要运行的代码
    });
});
</script>

HTML

保存并清除缓存后,刷新后打开开发者工具,网络选项搜索PJAX,看见?_pjax=#pjax-container意味着PJAX配置成功。

加载指示器

引入PJAX时,用户点击超链后浏览器将不作回应,因此需要使用加载指示器显示页面正在加载中,HTML中加入

<div id="loading-spinner" class="loader" style="display:none;"></div>

HTML

对应CSS(这里使用CSS矢量动画作为加载指示)

@keyframes spin {
  0% {
    transform: rotate(0deg);
  }
  100% {
    transform: rotate(360deg);
  }
}

#loading-spinner {
  position: fixed;
  top: 20px;
  right: 20px;
  width: 24px;
  height: 24px;
  border: 2px solid #ccc;
  border-top: 2px solid #3498db;
  border-radius: 50%;
  animation: spin 1s linear infinite;
  z-index: 9999;
}

CSS

PJAX发送时,加载动画出现,完成时隐藏,这是我的完整JS

jQuery(document).ready(function ($) {
    $(document).pjax('a[href^="<?php echo home_url(); ?>"]:not(a[target="_blank"])', {
        container: '#pjax-container',
        fragment: '#pjax-container'
    });

    $(document).on('pjax:send', function () {
        // 显示加载指示器
        $('#loading-spinner').show();

        window.scrollTo({ top: 0, behavior: 'smooth' });
        $('#pjax-container').fadeTo(400, 0.0);
        $('#toc').empty();
    });

    $(document).on('pjax:complete', function () {
        // 隐藏加载指示器
        $('#loading-spinner').hide();

        // 初始化左侧小组件
        Toc.init({
            $nav: $('#toc')
        });
        $('body').scrollspy({
            target: '#toc'
        });
        
        trackPjaxPageView();
        
        $('#pjax-container').fadeTo(400, 1);
    });
});

JavaScript

遇到的一些问题

PJAX意味着随之而来的无数BUG...

Matomo追踪代码

如果启用了Matomo或其他的一些追踪代码(它们一般放在Header内),意味着用户通过PJAX进入的界面无法被记入统计数据,因此必须在PJAX完成后重新载入这段JS,首先定义一个新函数

function trackPjaxPageView() {
    if (typeof _paq !== 'undefined') {
        _paq.push(['setReferrerUrl', document.referrer]);
        _paq.push(['setDocumentTitle', document.title]);
        _paq.push(['setCustomUrl', window.location.href]);
        _paq.push(['trackPageView']);
    }
}

JavaScript

PJAX完成后调用它:

$(document).on('pjax:complete', function() {
		trackPjaxPageView();
        $('#pjax-container').fadeTo(700,1);
    });

var _paq = window._paq = window._paq || [];
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
    var u="//analy.hiripple.com/";//这是我的matomo地址
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', '1']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();

JavaScript

左侧目录刷新

将PJAX容器包裹在正文,意味着左侧小工具栏所有元素都不会刷新(例如这个使用了bootstrap-toc.js的小目录)

$(document).on('pjax:complete', function() {
        // 初始化左侧小组件,查询官方的说明文档
        Toc.init({
            $nav: $('#toc'),
            $scope: $(document.body)
        });
        $('body').scrollspy({
            target: '#toc'
        });
        $('#pjax-container').fadeTo(700,1);
    });

JavaScript

即使重新初始化,也存在前一界面目录未清除的问题,在发送PJAX时清除目录:

$(document).on('pjax:send', function() {
        $('#pjax-container').fadeTo(700,0.0);
		$('#toc').empty(); //清除目录
    });

JavaScript

Lazyload/lightbox

PJAX可能会导致Lazyload无法加载的情况:

function pjax_reload() {
  var imgs = document.querySelectorAll("#main img.lazyload");
  lazyload(imgs);
}
jQuery(document).ready(function($) {

    // 初始化fancybox
    jQuery('[data-fancybox="gallery"]').fancybox();

    // 初始化lazyload
    pjax_reload();

    $(document).pjax('a[href^="<?php echo home_url(); ?>"]:not(a[target="_blank"])', {
        container: '#pjax-container',
        fragment: '#pjax-container'
    });

    $(document).on('pjax:send', function() {
        $('#pjax-container').fadeTo(700,0.0);
    });

    $(document).on('pjax:complete', function() {
        jQuery('[data-fancybox="gallery"]').fancybox();

        // 重新初始化lazyload
        pjax_reload();

        $('#pjax-container').fadeTo(700,1);
    });
});

JavaScript

或者直接使用图片loading='lazy'属性,这是HTML5中的原生懒加载。原生懒加载不需要额外的处理,浏览器会自动处理懒加载。

点击事件

这里需要切换夜间模式

function initDarkModeToggle() {
  const toggleBtnMoon = document.getElementById("moon-icon");
  const toggleBtnSun = document.getElementById("sun-icon");

  function applyDarkMode() {
    document.body.classList.add("dark-mode");
    localStorage.setItem("theme", "dark-mode");
    toggleBtnMoon.style.display = "none";
    toggleBtnSun.style.display = "block";
  }

  function removeDarkMode() {
    document.body.classList.remove("dark-mode");
    localStorage.setItem("theme", "light-mode");
    toggleBtnMoon.style.display = "block";
    toggleBtnSun.style.display = "none";
  }

  if (localStorage.getItem("theme") === "dark-mode") {
    applyDarkMode();
  } else {
    removeDarkMode();
  }

  toggleBtnMoon.addEventListener("click", applyDarkMode);
  toggleBtnSun.addEventListener("click", removeDarkMode);
}
$(document).on('pjax:complete', function() {
  initDarkModeToggle();
});

JavaScript


目录