Barba.js 完全使用指南
Barba.js 完全使用指南
版本: 1.0.0
更新时间: 2025-08-26
难度: 初级到中级
🎯 一分钟了解 Barba.js
Barba.js 是一个仅有 7KB 的轻量级 JavaScript 库，专门用于创建页面间的流畅转场动效。它通过拦截页面导航、异步加载内容并提供丰富的生命周期钩子，让传统的多页面网站也能拥有 SPA 般的丝滑体验。
🌟 为什么选择 Barba.js？
- 超轻量: 压缩后仅 7KB，几乎不影响页面加载速度
- 易上手: API 简洁直观，学习成本低
- 高性能: 基于 Promise 的异步架构，动画流畅不卡顿
- 灵活性: 与任何动画库兼容（GSAP、Anime.js 等）
- Vue 友好: 可与 Vue3 无缝集成
📋 目录
- 适用场景分析
- 环境准备与安装
- 核心概念详解
- 基础入门示例
- GSAP 动画进阶
- Vue3 集成完全指南
- 最小可运行 Demo
- 进阶技巧与优化
- 常见问题速查表
- 性能优化建议
- 实战案例分析
🎯 适用场景分析
✅ 推荐使用场景
| 场景类型 | 描述 | 推荐指数 |
|---|---|---|
| 多页面静态站点 | 企业官网、作品集、博客等 | ⭐⭐⭐⭐⭐ |
| SSR 应用 | Next.js、Nuxt.js 等服务端渲染应用 | ⭐⭐⭐⭐⭐ |
| 混合架构 | 部分页面为 SPA，部分为传统页面 | ⭐⭐⭐⭐ |
| 落地页集合 | 营销页面、活动页面等 | ⭐⭐⭐⭐ |
❌ 不推荐使用场景
| 场景类型 | 原因 | 替代方案 |
|---|---|---|
| 纯 Vue SPA | Vue Router 已提供完善的路由过渡 | Vue Router + <Transition> |
| React SPA | React Router 已有完善的动画方案 | React Router + Framer Motion |
| 复杂表单应用 | 状态管理复杂，容易出现数据丢失 | 单页应用架构 |
🛠 环境准备与安装
前置要求
- Node.js: 16.0+
- 浏览器: 支持 ES6+ 的现代浏览器
- 基础知识: HTML、CSS、JavaScript、Vue3 基础
安装方式
方式一：NPM 安装（推荐）
# 安装核心包
npm install @barba/core# 安装动画库（推荐）
npm install gsap# Vue3 项目
npm install vue@3
方式二：CDN 引入（快速测试）
<script src="https://unpkg.com/@barba/core"></script>
<script src="https://unpkg.com/gsap@3/dist/gsap.min.js"></script>
<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
🔧 核心概念详解
1. Container（容器）
每个页面必须包含一个带有 data-barba="container" 属性的容器：
<div class="barba-container" data-barba="container" data-barba-namespace="home"><!-- 页面内容 -->
</div>
2. Wrapper（包装器）
所有容器的外层包装：
<div id="barba-wrapper"><!-- 容器在这里 -->
</div>
3. Namespace（命名空间）
用于区分不同类型的页面，便于应用不同的动画或逻辑：
<!-- 首页 -->
<div data-barba-namespace="home">...</div><!-- 关于页 -->
<div data-barba-namespace="about">...</div><!-- 产品页 -->
<div data-barba-namespace="product">...</div>
4. 生命周期钩子
Barba 提供了丰富的生命周期钩子：
barba.init({transitions: [{// 页面初次加载once() { /* 初始化逻辑 */ },// 离开当前页面前beforeLeave() { /* 清理工作 */ },// 离开当前页面（播放退出动画）leave() { /* 退出动画 */ },// 进入新页面前beforeEnter() { /* 准备工作 */ },// 进入新页面（播放进入动画）enter() { /* 进入动画 */ },// 进入新页面后afterEnter() { /* 完成后的逻辑 */ }}]
});
🚀 基础入门示例
最简单的淡入淡出效果
import barba from '@barba/core';barba.init({transitions: [{name: 'fade',// 退出动画leave({ current }) {return new Promise(resolve => {current.container.style.transition = 'opacity 0.3s';current.container.style.opacity = '0';setTimeout(resolve, 300);});}