Vue FullPage.js 完整使用指南：Vue 3 官方全屏滾動解決方案

概述

vue-fullpage.js 是 FullPage.js 的官方 Vue.js 3 包裝器，為 Vue 3 應用提供了強大的全屏滾動功能。該插件基于成熟的 FullPage.js 庫，支持多種滾動效果和豐富的配置選項，特別適用于企業級數據大屏、產品展示、單頁應用等場景。

官方信息：

GitHub 倉庫：alvarotrigo/vue-fullpage.js

適用場景：

企業數據可視化大屏
領導駕駛艙系統
產品功能演示頁面
企業官網首頁
多媒體展示應用

🚀 安裝與配置

1. 安裝依賴

# 使用 npm
npm install --save vue-fullpage.js# 使用 yarn
yarn add vue-fullpage.js# 使用 pnpm
pnpm add vue-fullpage.js

2. 在 main.ts 中全局注冊

import { createApp } from 'vue'
import App from './App.vue'
import VueFullPage from 'vue-fullpage.js'
import 'vue-fullpage.js/dist/style.css'const app = createApp(App)
app.use(VueFullPage)
app.mount('#app')

基礎使用

1. 基本結構

根據官方文檔，vue-fullpage.js 創建了一個 <full-page> 組件：

<template><div><full-page ref="fullpage" :options="options" id="fullpage"><!-- 第一屏 --><div class="section"><div class="screen-content"><h1>第一屏內容</h1></div></div><!-- 第二屏 --><div class="section"><div class="screen-content"><h1>第二屏內容</h1></div></div><!-- 第三屏 --><div class="section"><div class="screen-content"><h1>第三屏內容</h1></div></div></full-page></div>
</template><script setup lang="ts">
import { ref } from 'vue'// fullpage 引用
const fullpage = ref<any>(null)// 配置選項 - 支持所有 FullPage.js 選項
const options = ref({// 許可證（商業使用必需）licenseKey: 'YOUR_KEY_HERE', // 替換為您的許可證密鑰// 基礎配置navigation: true,           // 顯示導航點navigationPosition: 'right', // 導航點位置scrollingSpeed: 1000,       // 滾動速度（毫秒）easingcss3: 'ease-in-out',  // CSS3 緩動函數// 控制選項keyboardScrolling: true,    // 鍵盤控制touchSensitivity: 5,        // 觸摸靈敏度autoScrolling: true,        // 自動滾動fitToSection: true,         // 適配屏幕// 回調函數afterLoad: (origin: any, destination: any) => {console.log('切換到屏幕:', destination.index + 1)},onLeave: (origin: any, destination: any) => {console.log('離開屏幕:', origin.index + 1, '前往:', destination.index + 1)}
})
</script><style scoped>
/* 確保 fullpage 容器占滿整個視口 */
:deep(#fullpage) {position: fixed;top: 0;left: 0;width: 100%;height: 100vh;z-index: 1;
}/* 確保 section 占滿整個高度 */
:deep(.fp-section) {height: 100vh !important;
}.screen-content {width: 100%;height: 100%;display: flex;flex-direction: column;justify-content: center;align-items: center;padding: 24px;box-sizing: border-box;
}
</style>

高級功能

1. 自定義導航菜單

<template><!-- 自定義導航菜單 --><div class="top-nav-menu"><div class="nav-item" :class="{ active: currentSection === 0 }" @click="goToSection(0)"><div class="nav-icon">🏠</div><div class="nav-text">首頁</div></div><div class="nav-item" :class="{ active: currentSection === 1 }" @click="goToSection(1)"><div class="nav-icon">📊</div><div class="nav-text">數據</div></div><div class="nav-item" :class="{ active: currentSection === 2 }" @click="goToSection(2)"><div class="nav-icon">??</div><div class="nav-text">設置</div></div></div><full-page ref="fullpage" :options="options" id="fullpage"><!-- 屏幕內容 --></full-page>
</template><script setup lang="ts">
import { ref } from 'vue'const fullpage = ref<any>(null)
const currentSection = ref(0)// 菜單點擊處理函數
const goToSection = (sectionIndex: number) => {if (fullpage.value && fullpage.value.api) {fullpage.value.api.moveTo(sectionIndex + 1)}
}const options = ref({navigation: false, // 隱藏默認導航點afterLoad: (_origin: any, destination: any) => {currentSection.value = destination.index}
})
</script><style scoped>
.top-nav-menu {position: fixed;top: 20px;left: 20px;z-index: 1000;display: flex;gap: 8px;background: rgba(255, 255, 255, 0.95);backdrop-filter: blur(10px);border-radius: 12px;padding: 12px 16px;box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
}.nav-item {display: flex;align-items: center;gap: 8px;padding: 10px 14px;border-radius: 8px;cursor: pointer;transition: all 0.3s ease;color: #606266;
}.nav-item:hover {background: rgba(64, 158, 255, 0.1);color: #409eff;
}.nav-item.active {background: linear-gradient(135deg, #409eff, #66b3ff);color: white;
}
</style>

解決滾動重定向問題

在使用 Vue FullPage.js 時，可能會遇到以下問題：

頁面滾動被 Vue Router 的 scrollBehavior 重定向
瀏覽器默認滾動行為與 FullPage.js 沖突
移動端觸摸滾動事件干擾

解決方案

1. 路由配置優化

// router/index.ts
import { createRouter, createWebHistory, type RouterScrollBehavior } from 'vue-router'const router = createRouter({history: createWebHistory(),routes: [{path: '/dashboard',name: 'leadershipDashboard',component: () => import('@/views/LeadershipDashboard/LeadershipDashboard.vue'),meta: { disableScroll: true, // 標記需要禁用滾動的頁面fullPage: true }}],scrollBehavior: ((to, from, savedPosition) => {// 如果目標頁面需要禁用滾動，返回 falseif (to.meta.disableScroll) {return false}// 如果是從全屏頁面跳轉，重置滾動位置if (from.meta.fullPage) {return { top: 0, left: 0 }}// 其他情況保持默認行為if (savedPosition) {return savedPosition}return { top: 0, left: 0 }}) as RouterScrollBehavior
})export default router

隱藏右下角水印

1. CSS 方式隱藏水印

/* 在全局樣式文件或組件樣式中添加 */
/* 隱藏 fullPage.js 水印 - 方法一：通用選擇器 */
.fp-watermark,
.fp-watermark a,
[data-watermark],
.fp-watermark-text,
div[style*="position: fixed"][style*="bottom: 0"][style*="right: 0"] {display: none !important;visibility: hidden !important;opacity: 0 !important;
}/* 方法二：更精確的選擇器 */
div[style*="position: fixed"][style*="bottom: 0"][style*="right: 0"][style*="z-index: 999999"] {display: none !important;visibility: hidden !important;opacity: 0 !important;
}/* 方法三：針對特定類名 */
.fp-watermark,
.fp-watermark a,
.fp-watermark-text {display: none !important;visibility: hidden !important;opacity: 0 !important;pointer-events: none !important;
}

常見問題與解決方案

1. 圖表不顯示問題

問題描述： ECharts 圖表在全屏滾動頁面中無法正常顯示。

解決方案：

// 延遲初始化圖表，確保 DOM 元素已渲染
onMounted(() => {// 使用 nextTick 確保 DOM 更新完成nextTick(() => {setTimeout(() => {initChart()}, 100)})
})// 或者使用 ResizeObserver 監聽容器大小變化
const initChartWithObserver = () => {if (!chartRef.value) returnconst resizeObserver = new ResizeObserver(() => {if (chart.value) {chart.value.resize()}})resizeObserver.observe(chartRef.value)
}

2. 導航菜單層級問題

問題描述： 自定義導航菜單被 FullPage.js 容器遮擋。

解決方案：

/* 確保導航菜單在最上層 */
.top-nav-menu {position: fixed !important;top: 20px !important;left: 20px !important;z-index: 9999 !important; /* 高于 FullPage.js 的 z-index */background: rgba(255, 255, 255, 0.95) !important;backdrop-filter: blur(10px) !important;
}/* 確保 FullPage.js 容器不會覆蓋導航 */
:deep(#fullpage) {z-index: 1 !important;
}

3. 移動端觸摸滾動問題

問題描述： 移動端觸摸滾動與 FullPage.js 沖突。

解決方案：

// 移動端觸摸事件處理
const handleTouchStart = (e: TouchEvent) => {// 記錄觸摸開始位置touchStartY = e.touches[0].clientY
}const handleTouchMove = (e: TouchEvent) => {// 防止默認滾動行為e.preventDefault()
}// 在組件中添加觸摸事件監聽
onMounted(() => {document.addEventListener('touchstart', handleTouchStart, { passive: true })document.addEventListener('touchmove', handleTouchMove, { passive: false })
})

4. 內存泄漏問題

問題描述： 組件銷毀后 FullPage.js 實例未正確清理。

解決方案：

onBeforeUnmount(() => {// 1. 移除事件監聽器window.removeEventListener('resize', handleResize)document.removeEventListener('wheel', preventScroll)document.removeEventListener('touchmove', preventScroll)// 2. 銷毀 FullPage.js 實例if (fullpage.value && fullpage.value.api) {fullpage.value.api.destroy('all')}// 3. 清理圖表實例if (chart.value) {chart.value.dispose()}// 4. 清理觀察器if (watermarkObserver) {watermarkObserver.disconnect()}
})

5. 性能優化問題

問題描述： 大量數據或復雜圖表導致頁面卡頓。

解決方案：

// 使用虛擬滾動或分頁加載
const useVirtualScroll = () => {const visibleItems = ref(10)const itemHeight = 50const getVisibleData = (data: any[]) => {return data.slice(0, visibleItems.value)}const loadMore = () => {visibleItems.value += 10}return { visibleItems, getVisibleData, loadMore }
}// 圖表懶加載
const useLazyChart = () => {const isChartVisible = ref(false)const observer = new IntersectionObserver((entries) => {entries.forEach(entry => {if (entry.isIntersecting) {isChartVisible.value = trueobserver.disconnect()}})})return { isChartVisible, observer }
}