企业官网建设流程全解析

fullPage.js Parallax 扩展使用指南：视差背景的配置、HTML 结构与方法 API 详解

【免费下载链接】fullPage.jsfullPage plugin by Alvaro Trigo. Create full screen pages fast and simple项目地址: https://gitcode.com/gh_mirrors/fu/fullPage.js

本指南以 fullPage.js 官方文档中关于 Parallax（视差）扩展的说明为核心，系统讲解如何通过fp-bg元素为全屏 Section / Slide 打造随滚动产生位移差的背景层效果，涵盖必需的 HTML 结构、背景应用方式、parallax与parallaxOptions配置项、以及setOption/init/destroy方法 API，并辅以当前仓库源码（默认配置、类型定义、扩展激活说明）进行佐证。读者阅读后可独立完成 Parallax 扩展的激活、页面改造、参数调优与动态启停。

一、扩展激活：使用 Parallax 前的前置准备

Parallax 属于 fullPage.js 的官方扩展（Extension），并非内置功能，使用前必须完成激活。完整流程见仓库内文档 lang/japanese/how-to-activate-fullpage-extension.md，要点如下：

1. 访问官方激活页面（购买扩展后邮件中会提供该 URL），输入购买时获得的许可证密钥（License Key），按提示填写域名，生成对应域名的激活密钥（Activation Key）。
2. 激活密钥与许可证密钥是两类不同的密钥，切勿混淆：许可证密钥用于生成激活密钥，格式为 4 组 8 字符（如XXXXXXXXXXXX-XXXXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXX）；激活密钥则绑定到特定域名，长度可变且不分组。
3. 初始化 fullPage.js 时，以扩展名 + "Key"的形式传入激活密钥：

new fullPage('#fullpage', { parallax: true, parallaxKey: 'ここにアクティベーションキーを入力', // 填入你的激活密钥 });

4. 必须在页面中引入fullpage.extensions.min.js（扩展版构建文件），而非普通的fullpage.js。当前仓库源码 src/js/common/constants.js 中维护了包括'parallax'在内的一组扩展名列表，用于校验传入的parallaxKey等扩展选项是否合法。

开发便利性说明：localhost与127.0.0.1不需要激活密钥即可在本地开发调试；线上域名则需要专业版或商业版许可证，多域名许可证可传入密钥数组，例如parallaxKey: ['domain1_key', 'domain2_key', 'domain3_key']。

二、必需的 HTML 结构：在 Section / Slide 中插入fp-bg元素

要在 Section 或 Slide 上启用视差背景，必须先在 DOM 中新增一个带fp-bg类的空div元素，并且它必须是该 Section / Slide 的第一个子元素：

<div class="fp-bg"></div>

背景样式只能应用到这个fp-bg元素上，而不能直接施加给 Section / Slide 本身。以下是一个同时覆盖竖向 Section 与横向 Slide 的完整示例：

<div id="fullpage"> <div class="section" id="section1"> <div class="fp-bg"></div> スライド 1.1 </div> <div class="section" id="section2"> <div class="slide" id="slide2-1"> <div class="fp-bg"></div> スライド 2.1 </div> <div class="slide" id="slide2-2"> <div class="fp-bg"></div> スライド 2.2 </div> </div> </div>

仓库中的 examples/parallax.html 即为 Parallax 扩展的官方演示入口（页面中直接跳转到扩展在线演示站点，可查看其源码结构）。

备选方案：如果因为布局原因实在无法新增元素，可将parallaxOptions中的property选项设置为background，直接对当前 Section / Slide 的背景属性施加视差效果。但官方明确提示：该方式性能不如fp-bg元素方案，仅在确有需要时才建议使用。

三、背景的施加方法

背景通过 CSS 或内联样式施加在fp-bg元素上，写法与普通元素背景完全一致。例如：

#section1 .fp-bg{ background-image: url('imgs/alvaro-genious.jpg'); background-size: cover; background-position: center 80%; }

由于fp-bg是独立的层，推荐配合background-size: cover与合理的background-position使用，以保证不同屏幕比例下背景铺满且构图稳定。你也可以直接使用仓库 examples/imgs 下的背景图（如bg1.jpg、bg2.jpg等）进行本地联调。

四、配置选项：parallax与parallaxOptions

Parallax 扩展涉及两个顶层配置项，其默认值在 src/js/optionsDefault.js 中定义：

parallax: false, parallaxOptions: { type: 'reveal', percentage: 62, property: 'translate' },

4.1parallaxOptions子选项详解

与之对应的 TypeScript 类型定义见 types/index.d.ts：

type ParallaxOptions = { percentage?: number property?: "translate" | "background" type?: "reveal" | "cover" };

从类型定义可以确认：property仅接受"translate" | "background"两个取值，type仅接受"reveal" | "cover"，与文档描述一一对应。

4.2 性能要点：为何默认使用translate

使用fp-bg元素时，视差位移通过translate3d实现，可以充分利用 GPU 硬件加速，因此性能更好。property: 'background'选项的定位是兜底方案——当页面无法修改 HTML 标记、无法为每个 Section/Slide 插入fp-bg元素时使用，但由于直接操作背景属性无法利用硬件加速，性能会明显劣化。

4.3 兼容性限制

根据 README.md 中的说明，parallax选项不兼容以下场景：

• fp-auto-height（自动高度）Section；
• offsetSections（偏移 Section）扩展；
• dragAndMove（拖拽移动）扩展。

在同一页面中同时启用这些功能与parallax时，需要评估冲突可能导致的显示异常。

五、方法 API：运行时动态控制视差

Parallax 扩展通过fullpage_api.parallax暴露三个方法，可用于在页面运行时动态调整视差行为。

5.1setOption(optionName, value)

设置parallaxOptions中某个子选项的值。optionName取值限定为type、percentage或property。

// 将 type 属性改为 'cover' fullpage_api.parallax.setOption('type', 'cover'); // 将 percentage 属性改为 30 fullpage_api.parallax.setOption('percentage', '30');

注意示例中percentage以字符串'30'传入，实现层会将其转换为数值参与百分比计算，实际使用时可传数字或数字字符串。

5.2init()

启用视差效果。当页面需要在特定时机（而非初始化时）动态开启视差时使用：

fullpage_api.parallax.init();

5.3destroy()

关闭视差效果：

fullpage_api.parallax.destroy();

六、完整配置示例

将以上内容整合，一份可落地的初始化配置如下：

new fullPage('#fullpage', { // 启用 Parallax 扩展（也可设为 'sections' 或 'slides' 限定作用范围） parallax: true, // 扩展激活密钥 parallaxKey: 'ここにアクティベーションキーを入力', // 视差参数调优 parallaxOptions: { type: 'cover', // 'reveal' | 'cover' percentage: 62, // 0 ~ 100，越小视差越明显 property: 'translate' // 'translate' | 'background' }, });

配合 CSS：

#section1 .fp-bg{ background-image: url('imgs/bg1.jpg'); background-size: cover; background-position: center 80%; }

即可在保留全屏翻页体验的同时，让背景层以不同的位移速率产生立体纵深感。

七、总结

Parallax 扩展为 fullPage.js 提供了一套开箱即用的视差背景方案：核心是“把背景抽离到fp-bg元素上”，通过parallax开关与parallaxOptions三件套（type/percentage/property）控制位移方向、幅度与实现方式，再配合setOption/init/destroy三个方法在运行时动态调整。实际开发中应优先采用默认的translate方案以享受 GPU 加速，仅在无法改动 HTML 结构时才降级为background属性方案，同时注意避开fp-auto-height、offsetSections、dragAndMove等不兼容组合。相关源码入口见 src/js/optionsDefault.js、types/index.d.ts 与 src/js/common/constants.js。

【免费下载链接】fullPage.jsfullPage plugin by Alvaro Trigo. Create full screen pages fast and simple项目地址: https://gitcode.com/gh_mirrors/fu/fullPage.js