feat: 添加 Swup 页面过渡效果及相关功能

Signed-off-by: wangsimiao1 <wangsimiao1@xiaomi.com>

Author: WangSimiao2000

_javascript/commons.js

@@ -1,5 +1,6 @@
-import { basic, initSidebar, initTopbar } from './modules/layouts';
+import { basic, initSidebar, initTopbar, initSwup } from './modules/layouts';
 
 initSidebar();
 initTopbar();
 basic();
+initSwup();

_javascript/modules/layouts.js

@@ -1,3 +1,4 @@
 export { basic } from './layouts/basic';
 export { initSidebar } from './layouts/sidebar';
 export { initTopbar } from './layouts/topbar';
+export { initSwup } from './layouts/swup-setup';

_javascript/modules/layouts/swup-setup.js

@@ -0,0 +1,41 @@
+import Swup from 'swup';
+import SwupHeadPlugin from '@swup/head-plugin';
+import SwupScriptsPlugin from '@swup/scripts-plugin';
+
+export function initSwup() {
+  const swup = new Swup({
+    containers: ['#swup'],
+    animationSelector: '.swup-transition-main',
+    cache: true,
+    plugins: [
+      new SwupHeadPlugin({
+        persistAssets: true // keep existing CSS/JS, avoid re-downloading
+      }),
+      new SwupScriptsPlugin({
+        head: true,
+        body: true
+      })
+    ]
+  });
+
+  // Update sidebar active state after navigation
+  swup.hooks.on('page:view', () => {
+    const currentPath = window.location.pathname;
+    const navItems = document.querySelectorAll('#sidebar .nav-item');
+
+    navItems.forEach((item) => {
+      const link = item.querySelector('a');
+      if (!link) return;
+
+      const href = link.getAttribute('href');
+      const isActive =
+        (href === '/' && currentPath === '/') ||
+        (href !== '/' && currentPath.startsWith(href));
+
+      item.classList.toggle('active', isActive);
+    });
+
+    // Scroll content area to top
+    window.scrollTo({ top: 0 });
+  });
+}

_layouts/default.html

@@ -23,40 +23,43 @@
       <div class="container d-flex flex-column px-xxl-5">
         {% include topbar.html lang=lang %}
 
-        <div class="row flex-grow-1">
-          <main aria-label="Main Content" class="col-12 col-lg-11 col-xl-9 px-md-4">
-            {% if layout.layout == 'default' %}
-              {% include refactor-content.html content=content lang=lang %}
-            {% else %}
-              {{ content }}
-            {% endif %}
-          </main>
-
-          <!-- panel -->
-          <aside aria-label="Panel" id="panel-wrapper" class="col-xl-3 ps-2 text-muted">
-            <div class="access">
-              {% include_cached update-list.html lang=lang %}
-              {% include_cached trending-tags.html lang=lang %}
-            </div>
-
-            {% for _include in layout.panel_includes %}
-              {% assign _include_path = _include | append: '.html' %}
-              {% include {{ _include_path }} lang=lang %}
-            {% endfor %}
-          </aside>
-        </div>
+        <div id="swup" class="swup-transition-main">
+          <div class="row flex-grow-1">
+            <main aria-label="Main Content" class="col-12 col-lg-11 col-xl-9 px-md-4">
+              {% if layout.layout == 'default' %}
+                {% include refactor-content.html content=content lang=lang %}
+              {% else %}
+                {{ content }}
+              {% endif %}
+            </main>
+
+            <!-- panel -->
+            <aside aria-label="Panel" id="panel-wrapper" class="col-xl-3 ps-2 text-muted">
+              <div class="access">
+                {% include_cached update-list.html lang=lang %}
+                {% include_cached trending-tags.html lang=lang %}
+              </div>
+
+              {% for _include in layout.panel_includes %}
+                {% assign _include_path = _include | append: '.html' %}
+                {% include {{ _include_path }} lang=lang %}
+              {% endfor %}
+            </aside>
+          </div>
 
-        <div class="row">
-          <!-- tail -->
-          <div id="tail-wrapper" class="col-12 col-lg-11 col-xl-9 px-md-4">
-            {% for _include in layout.tail_includes %}
-              {% assign _include_path = _include | append: '.html' %}
-              {% include {{ _include_path }} lang=lang %}
-            {% endfor %}
+          <div class="row">
+            <!-- tail -->
+            <div id="tail-wrapper" class="col-12 col-lg-11 col-xl-9 px-md-4">
+              {% for _include in layout.tail_includes %}
+                {% assign _include_path = _include | append: '.html' %}
+                {% include {{ _include_path }} lang=lang %}
+              {% endfor %}
 
-            {% include_cached footer.html lang=lang %}
+              {% include_cached footer.html lang=lang %}
+            </div>
           </div>
         </div>
+        <!-- /#swup -->
 
         {% include_cached search-results.html lang=lang %}
       </div>

_sass/components/_index.scss

@@ -1,2 +1,3 @@
 @forward 'buttons';
 @forward 'popups';
+@forward 'swup';

_sass/components/_swup.scss

@@ -0,0 +1,12 @@
+/* Swup page transition */
+.swup-transition-main {
+  transition: opacity 0.2s ease-in-out;
+}
+
+html.is-changing .swup-transition-main {
+  opacity: 0;
+}
+
+html.is-animating .swup-transition-main {
+  opacity: 1;
+}

package-lock.json

@@ -15,15 +15,18 @@
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",
-    "@babel/preset-env": "^7.24.0",
     "@babel/plugin-transform-class-properties": "^7.24.0",
     "@babel/plugin-transform-private-methods": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-terser": "^0.4.4",
     "rollup": "^4.12.0"
   },
   "dependencies": {
-    "bootstrap": "^5.3.3"
+    "@swup/head-plugin": "^2.3.1",
+    "@swup/scripts-plugin": "^2.1.0",
+    "bootstrap": "^5.3.3",
+    "swup": "^4.8.3"
   }
 }