【翻译】fancyBox3 中文文档

发布时间：2025-12-10 11:43:32 浏览次数：12

fancyBox3 中文文档

译文永久地址：kangkai124.github.io/fancybox/

说明：本文档仅供参考，更新不及时请查看官方文档

1. 介绍

fancyBox 是一个 JavaScript 库，它以优雅的方式展示图片，视频和一些 html 内容。它包含你所期望的一切特性 —— 支持触屏，响应式和高度自定义。

1.1 依赖

推荐 jQuery 3+，但是 fancyBox 仍支持 jQery 1.9.1+ 和 jQuery 2+ 。

注意

如果你在图片缩放时遇到了问题，请升级 jQuery 到最近版本（至少v3.2.1）。

1.2 兼容

fancyBox 支持触屏操作，而且支持缩放等手势操作。在移动端和PC端上都十分合适。

fancyBox 已经在下列浏览器中测试：

Chrome
firefox
IE10/11
Edge
IOS Safari
Nexus 7 Chrome

2. 配置

可以在 html 文档中引入.css和.js来使用fancyBox，确保在这之前引入了 jQuery 库。下面是使用fancyBox的一个基本的HTML模板：

<!DOCTYPE html><html><head><meta charset="utf-8"><title>My page</title><link rel="stylesheet" type="text/css" href="jquery.fancybox.min.css"></head><body><script src="//code.jquery.com/jquery-3.2.1.min.js"></script><script src="jquery.fancybox.min.js"></script></body></html>复制代码

注意

要先引入jQuery
如果页面中已经引入过jQuery，不能再次引入
不要同时引入 fancybox.js 和 fancybox.min.js
一些方法（ajax，iframes 等）必须在一个web服务器上才可以正常运行，在浏览器打开一个本地文件是无法正常工作的

2.1 下载fancyBox

可以在 GIthub 下载最新的版本。

或者直接引用 cdnjs —cdnjs.com/libraries/f…。

2.2 包管理工具

fancyBox 还可以通多 npm 和 Bower安装。

# NPMnpm install @fancyapps/fancybox --save# Bowerbower install fancybox --save复制代码

3. 使用

3.1 使用 data 属性初始化

最基本的用法是通过添加 data-fancybox 属性到一个超链接标签。标题可以通过 data-capiton 添加。例如：

<a href="image.jpg" data-fancybox data-caption="My caption"><img src="thumbnail.jpg" alt="" /></a>复制代码

在 CodePen 上查看例子

这种方式使用默认的配置，可以查看选项进行自定义配置，或者使用data-options属性。

3.2 使用 JavaScript 初始化

使用 jQuery 选择器选择一个元素，然后调用fancybox方法：

在 CodePen 上查看例子

使用这种方式，只有被选中的元素才可以触发点击事件。

为了可以现在或之后存在的元素都可以触发点击事件，使用selector选项。例如：

$().fancybox({selector : '[data-fancybox="images"]',loop : true});复制代码

在 CodePen 上查看例子

3.3 手动调用 fancyBox

fancyBox 允许使用 JavaScrip t以任意形式触发，因此不必需要通过某一个元素触发。下面例子为展示一段简单的信息：

$.fancybox.open('<p class="message"><h2>Hello!</h2><p>You are awesome!</p></p>');复制代码

在 CodePen 上查看例子

通过 API 查看更多的信息和例子。

3.4 分组

如果你有一组元素，组内元素使用相同的 data-fancybox 值就可以组成一个相册。不同的组应该使用不同的属性值加以区分。

<a href="image_1.jpg" data-fancybox="group" data-caption="Caption #1"><img src="thumbnail_1.jpg" alt="" /></a><a href="image_2.jpg" data-fancybox="group" data-caption="Caption #2"><img src="thumbnail_2.jpg" alt="" /></a>复制代码

在 CodePen 上查看例子

注意

fancyBox根据给定的url自己尝试检测内容的类型。如果无法检测，该类型可以使用data-type属性手动添加。

<a href="images.php?id=123" data-type="image" data-caption="Caption">Show image</a>复制代码

4. 媒体类型

4.1 图片

使用 fancyBox 的标准做法是用小尺寸的图片链接到大尺寸图片：

<a href="image.jpg" data-fancybox="images" data-caption="My caption"><img src="thumbnail.jpg" alt="" /></a>复制代码

在 CodePen 上查看例子

默认情况下，fancyBox 会在一张图片展示前进行预加载。你可以选择立即显示图片，这样当加载完成后会马上渲染和显示完整尺寸的图片。不过，以下属性是必须添加的：

data-width - 图片的完整宽度
data-height - 图片的完整高度

<a href="image.jpg" data-fancybox="images" data-width="2048" data-height="1365"><img src="thumbnail.jpg" /></a>复制代码

在 CodePen 上查看例子

fancyBox 支持 scrset，它的作用是根据不同的可视区域显示不同尺寸的图片。你可以使用这个属性来减少移动端用户的下载时间。例如：

<a href="medium.jpg" data-fancybox="images" data-srcset="large.jpg 1600w, medium.jpg 1200w, small.jpg 640w"><img src="thumbnail.jpg" /></a>复制代码

在 CodePen 上查看例子

fancyBox 还支持禁止右键下载来保护图片。当然这无法阻止那些下定决心下载的用户，但是可以让大多数想要盗取你文件的用户打消这个念头。

$('[data-fancybox]').fancybox({protect: true})复制代码

在 CodePen 上查看例子

4.2 行内 HTML

对于行内元素，你需要创建一个隐藏的元素并添加独特的 id 属性：

<p style="display: none;" id="hidden-content"><h2>Hello</h2><p>You are awesome.</p></p>复制代码

然后只需要创建一个带有 data-src 属性的超链接，该属性值匹配之前隐藏元素的id（优先使用# ）：

<a data-fancybox data-src="#hidden-content" href="javascript:;">Trigger the fancyBox</a>复制代码

在 CodePen 上查看例子

这段代码会产生一个关闭按钮（如果你没有通过 smallBtn: false 禁用的话），这个按钮只设置了居中。因此你可以很轻松地通过css来自定义样式。

4.3 Ajax

想要通过 Ajax 加载内容，需要在超链接添加 data-type="ajax" 属性：

<a data-fancybox data-type="ajax" data-src="my_page.com/path/to/ajax/" href="javascript:;">AJAX content</a>复制代码

在 CodePen 上查看例子

另外，可以使用 data-filter 属性定义一个选择器，来显示响应的一部分。这个选择器需要是一个合法的 jQuery 选择器：

<a data-fancybox data-type="ajax" data-src="my_page.com/path/to/ajax/" data-filter="#two" href="javascript:;">AJAX content</a>复制代码

在 CodePen 上查看例子

4.4 Iframe

如果内容可以展示在页面，并且放在 iframe 中不会被脚本或者安全策略禁止，它就可以在 fancyBox 中展示：

<a data-fancybox data-type="iframe" data-src="http://codepen.io/fancyapps/full/jyEGGG/" href="javascript:;">Webpage</a><a data-fancybox data-type="iframe" data-src="https://mozilla.github.io/pdf.js/web/viewer.html" href="javascript:;">Sample PDF</a>复制代码

在 CodePen 上查看例子

如果嵌入了 iframe，可以从父容器中访问和控制 fancyBox：

// 根据内容调整 iframe 的高度parent.jQuery.fancybox.getInstance().update();// 关闭当前的 fancyBox 实例parent.jQuery.fancybox.getInstance().close();复制代码

Iframe 尺寸可以通多 CSS 调整：

.fancybox-slide--iframe .fancybox-content {width : 800px;height : 600px;max-width : 80%;max-height : 80%;margin: 0;}复制代码

如果需要的话，CSS 样式可以被 JS 覆盖：

$("[data-fancybox]").fancybox({iframe : {css : {width : '600px'}}});复制代码

如果你没有禁止 iframe 的预加载（使用preload），那么fancyBox会尝试计算内容的尺寸，并且会根据内容来调整 iframe 的宽高。注意，这依赖于同源策略，因此会有一些限制。

下面这个例子禁止了 iframe 的预加载，并且用取消按钮代替了工具栏。

$('[data-fancybox]').fancybox({toolbar : false,smallBtn : true,iframe : {preload : false}})复制代码

在 CodePen 上查看例子

5. 嵌入

支持的网站可以展示在 fancyBox 中，只需要提供页面的地址即可：

<a data-fancybox href="https://www.youtube.com/watch?v=_sI_Ps7JSEk">YouTube video</a><a data-fancybox href="https://vimeo.com/191947042">Vimeo video</a><a data-fancybox href="https://www.google.com/maps/search/Empire+State+Building/">Google Map</a><a data-fancybox href="https://www.instagram.com/p/BNXYW8-goPI/?taken-by=jamesrelfdyer" data-caption="<span title="Edited">balloon rides at dawn ✨?<br>was such a magical experience floating over napa valley as the golden light hit the hills.<br><a href="https://www.instagram.com/jamesrelfdyer/">@jamesrelfdyer</a></span>">Instagram photo</a>复制代码

在 CodePen 上查看例子

5.1 视频尺寸

通过 CSS 调整视频的显示大小：

.fancybox-slide--video .fancybox-content {width : 800px;height : 600px;max-width : 80%;max-height : 80%;}复制代码

在 CodePen 上查看例子

显然，你可以选择你喜欢的尺寸。部分未支持的画面比例，可以参照这个方法。

5.2 视频参数

通过 url 中的参数控制视频

<a data-fancybox href="https://www.youtube.com/watch?v=_sI_Ps7JSEk&autoplay=1&rel=0&controls=0&showinfo=0">YouTube video - hide controls and info</a><a data-fancybox href="https://vimeo.com/191947042?color=f00">Vimeo video - custom color</a>复制代码

在 CodePen 上查看例子

通过 JavaScript 控制视频：

$('[data-fancybox]').fancybox({youtube : {controls : 0,showinfo : 0},vimeo : {color : 'f00'}});复制代码

在 CodePen 上查看例子

6. 选项

默认选项值快速参考：

通过传入 fancybox 方法一个对象来设置一个实例：

$("[data-fancybox]").fancybox({thumbs : {autoStart : true}});复制代码

可以通过 $.fancybox.defaults 命名空间修改 fancyBox 的默认选项：

$.fancybox.defaults.animationEffect = "fade";复制代码

对于单独的元素可以通过 data-options 属性进行自定义。这个属性值要求JSON格式的对象：

<a data-fancybox data-options='{"caption" : "My caption", "src" : "https://codepen.io/about/", "type" : "iframe"}' href="javascript:;" class="btn">Open external page</a>复制代码

在 CodePen 上查看例子

7. API

API 提供了一系列的方法来控制 fancyBox。这些方法帮助你扩展插件，整合到其他的 web 应用中。

7.1 核心方法

操作实例的核心方法：

// 只关闭当前 active 状态或者所有的 fancyBox 实例$.fancybox.close( true );// 打开 fancyBox$.fancybox.open( items, opts, index );复制代码

通过 jQuery 将相册中的元素变为 jQuery 对象或者包含纯对象的数组，进行更多操作如创建定义点击事件。

var $links = $('.fancybox');$links.on('click', function() {$.fancybox.open( $links, {// 自定义内容}, $links.index( this ) );return false;});复制代码

手动创建一组对象时，组内元素应该遵循以下规则：

{src : '' // 资源type : '' // 类型: image|inline|ajax|iframe|html (optional)opts : {} // 选项 (optional)}复制代码

下面是一个通过 JavaScrip t打开相册的例子：

$.fancybox.open([{src : '1_b.jpg',opts : {caption : 'First caption'}},{src : '2_b.jpg',opts : {caption : 'Second caption'}}], {loop : false});复制代码

在 CodePen 上查看例子

fancyBox 允许只传一个对象。打开行内元素的例子：

$.fancybox.open({src : '#hidden-content',type : 'inline',opts : {afterShow : function( instance, current ) {console.info( 'done!' );}}});// 译者注：行内元素如下<p id="#hidden-content"><p>...content</p></p>复制代码

在 CodePen 上查看例子

如果你想展示一些html文档（例如一段信息），你只需要使用很简单的一句语法。fancyBox 建议使用一个wrapper 包裹你的内容。

$.fancybox.open('<p class="message"><h2>Hello!</h2><p>You are awesome!</p></p>');复制代码

在 CodePen 上查看例子

7.2 实例的方法

你需要定义一个实例来使用实例的方法。

var instance = $.fancybox.open(// 内容和选项);复制代码

从当前 active 的实例中获取信息：

var instance = $.fancybox.getInstance();复制代码

回调函数的第一个参数返回实例信息：

$("[data-fancybox]").fancybox({afterShow : function( instance, current ) {console.info( instance );}});复制代码

实例可以调用以下方法：

// 跳到下一个相册元素instance.next( duration );//跳到上一个相册元素instance.previous( duration );// 调到选中的相册元素instance.jumpTo( index, duration );// 检测当前尺寸是否小于实际尺寸instance.isScaledDown();// 缩放到实际尺寸instance.scaleToActual( x, y, duration );// 检测尺寸是否超过父元素instance.canPan();// 缩放适应父元素尺寸instance.scaleToFit( duration );// 更新滑块的内容和位置instance.update();// 更新侧边栏的位置，缩放内容来适应instance.updateSlide( slide );// 更新 infobar 的值，导航按钮的状态，和展示标题instance.updateControls( force );// 在侧边栏中加载自定义内容instance.setContent( slide, content );// 在侧边栏中加载loading效果instance.showLoading( slide );// 从侧边栏中去除loading效果instance.hideLoading( slide );// 找到和把焦点放在第一个可以放置焦点的元素instance.focus();// 激活当前 active 的实例，显示在最前面instance.activate();// 关闭实例instance.close();复制代码

你可以这样使用：

$.fancybox.getInstance().jumpTo(1);复制代码

或者：

$.fancybox.getInstance('jumpTo', 1);复制代码

7.3 事件

fancyBox 支持触发以下事件：

beforeLoad : 滑块的内容加载前afterLoad : 滑块内容加载后beforeShow : 打开动画开始前afterShow : 内容或者动画加载完成beforeClose : 实例准备关闭前，染回`false`取消关闭afterClose : 实例关闭后onInit : 实例初始化完成onActivate : 实例active状态onDeactivate : 其他实例变为active状态复制代码

事件可以作为一个对象的函数属性，该对象作为参数传入到 fancyBox 初始化方法中：

每一个回调函数接收两个参数 —— 当前的 fancyBox 实例和当前的相册对象（如果它们存在）。

fancyBox也支持触发所有的实例事件。为了防止和其他的脚本产生干扰，这些事件命名为.fb结尾。这些事件函数接收3个参数—事件（event），当前的 fancyBox 实例和当前的相册对象。

下面例子是绑定afterShow事件：

$(document).on('afterShow.fb', function( e, instance, slide ) {// Your code goes here});复制代码

如果你想阻止当前弹窗的关闭（例如在表单提交之后），可以使用beforeClose。只需要返回false即可：

beforeClose : function( instance, current, e ) {if ( $('#my-field').val() == '' ) {return false;}}复制代码

8. 模块

fancyBox 代码被分成几个扩展核心功能的文件（模块）。你可以通过去除不必要的模块来构建你自己的 fancyBox 版本。如果需要，每一个模块有自己的.js和.css文件。

// 自定义、添加新的媒体类型// 例如:/*media : {youtube : {params : {autoplay : 0}}}*/media : {},slideShow : {autoStart : false,speed : 4000},thumbs : {autoStart : false, // 打开时显示缩略图hideOnClose : true, // Hide thumbnail grid when closing animation startsparentEl : '.fancybox-container', // Container is injected into this elementaxis : 'y' // Vertical (y) or horizontal (x) scrolling}Example (show thumbnails on start):复制代码

开始时展示缩略图的例子：

$('[data-fancybox="images"]').fancybox({thumbs : {autoStart : true}})复制代码

如果你查看了 fancyBox 的实例对象，你会发现一些key的值是大写的 —— 他们关联着其他模块的对象。当然，你也会发现 fancyBox 使用和 jQuery 一直的前缀 $ 。

下面例子为如何拿到缩略图栅格元素：

$.fancybox.getInstance().Thumbs.$grid复制代码

下面例子为如何调用切换缩略图的方法：

$.fancybox.getInstance().Thumbs.toggle();复制代码

可使用的方法列表：

Thumbs.focus()Thumbs.update();Thumbs.hide();Thumbs.show();Thumbs.toggle();FullScreen.request( elem );FullScreen.exit();FullScreen.toggle( elem );FullScreen.isFullscreen();FullScreen.enabled();SlideShow.start();SlideShow.stop();SlideShow.toggle();复制代码

如果你想禁止 hash 模块，使用下面代码片段（引用 JS 之后）：

$.fancybox.defaults.hash = false;复制代码

9. FAQ

1. 打开、关闭导致固定定位的元素移动

在固定定位的元素的class中加入compensate-for-scrollbar。例子为使用Bootstrap的navbar组件：

<nav class="navbar navbar-inverse navbar-fixed-top compensate-for-scrollbar"><p class="container">..</p></nav>复制代码

在 CodePen 上查看例子

上个例子中，脚本会测量滚动条的宽度，创建compensate-for-scrollbar样式并将宽度值复制到该样式的margin-right属性。因此，如果你的元素宽度设置为width:100%，你应该同时使用left和right定位，例如：

.navbar {position: fixed;top: 0;left: 0;right: 0;}复制代码

2. 如何自定义标题

你可以使用caption选项，它接收一个函数，并且被组内的每个元素调用。例子为增加图片下载链接：

$( '[data-fancybox="images"]' ).fancybox({caption : function( instance, item ) {var caption = $(this).data('caption') || '';if ( item.type === 'image' ) {caption = (caption.length ? caption + '<br />' : '') + '<a href="' + item.src + '">Download image</a>' ;}return caption;}});复制代码

在 CodePen 上查看例子

在标题右边增加当前图片的序号和图片总数：

$( '[data-fancybox="images"]' ).fancybox({infobar : false,caption : function( instance, item ) {var caption = $(this).data('caption') || '';return ( caption.length ? caption + '<br />' : '' ) + 'Image <span data-fancybox-index></span> of <span data-fancybox-count></span>';}});复制代码

在 CodePen 上查看例子

在caption方法里面，this指向被点击的元素。例子为使用不同的标题：

$( '[data-fancybox]' ).fancybox({caption : function( instance, item ) {return $(this).find('figcaption').html();}});复制代码

在 CodePen 上查看例子

3. 如何在tool上创建自定义按钮

创建可重复使用的按钮例子：

// 创建按钮模板$.fancybox.defaults.btnTpl.fb = '<button data-fancybox-fb class="fancybox-button fancybox-button--fb" title="Facebook">' +'<svg viewBox="0 0 24 24">' +'<path d="M22.676 0H1.324C.594 0 0 .593 0 1.324v21.352C0 23.408.593 24 1.324 24h11.494v-9.294h-3.13v-3.62h3.13V8.41c0-3.1 1.894-4.785 4.66-4.785 1.324 0 2.463.097 2.795.14v3.24h-1.92c-1.5 0-1.793.722-1.793 1.772v2.31h3.584l-.465 3.63h-3.12V24h6.115c.733 0 1.325-.592 1.325-1.324V1.324C24 .594 23.408 0 22.676 0"/>' +'</svg>' +'</button>';// 使用时间代理使按钮可点击$('body').on('click', '[data-fancybox-fb]', function() {window.open("https://www.facebook.com/sharer/sharer.php?u="+encodeURIComponent(window.location.href)+"&t="+encodeURIComponent(document.title), '','left=0,top=0,width=600,height=300,menubar=no,toolbar=no,resizable=yes,scrollbars=yes');});// 自定义按钮$( '[data-fancybox="images"]' ).fancybox({buttons : ['fb','close']});复制代码

在 CodePen 上查看例子

4. 如何重置缩略图栅格的位置

这里没有 JS 选项去改变缩略图栅格的位置，但是 fancyBox 允许你使用 CSS 来改变每个块元素的位置或者尺寸（例如：内容区域，标题或者缩略图栅格）。这使你很自由的改变弹框窗口的外观和样式。

在 CodePen 上查看例子

5. 如何禁止touch操作

当你想内容可选择或者可点击，有两个选项：

设置touch:false完全禁止 touch 操作
添加data-selectable="true"属性到你的 html 元素

在 CodePen 上查看例子

上一篇：怎么取消拨号连接？取消拨号连接方法及步骤详解下一篇：华硕n75怎么样华硕n75参数解读

综合百科

【翻译】fancyBox3 中文文档

fancyBox3 中文文档

1. 介绍

1.1 依赖

1.2 兼容

2. 配置

2.1 下载fancyBox

2.2 包管理工具

3. 使用

3.1 使用 data 属性初始化

3.2 使用 JavaScript 初始化

3.3 手动调用 fancyBox

3.4 分组

4. 媒体类型

4.1 图片

4.2 行内 HTML

4.3 Ajax

4.4 Iframe

5. 嵌入

5.1 视频尺寸

5.2 视频参数

6. 选项

7. API

7.1 核心方法

7.2 实例的方法

7.3 事件

8. 模块

9. FAQ

1. 打开、关闭导致固定定位的元素移动

2. 如何自定义标题

3. 如何在tool上创建自定义按钮

4. 如何重置缩略图栅格的位置

5. 如何禁止touch操作

综合百科

网站导航