【翻译】fancyBox 3中文文档

栾弘新

2023-12-01

fancyBox3 中文文档

译文永久地址：https://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. 配置

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

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>My page</title>

    <!-- CSS -->
    <link rel="stylesheet" type="text/css" href="jquery.fancybox.min.css">
</head>
<body>

    <!-- Your HTML content goes here -->

    <!-- JS -->
    <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—https://cdnjs.com/libraries/fancybox。

2.2 包管理工具

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

# NPM
npm install @fancyapps/fancybox --save

# Bower
bower 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方法：

<script type="text/javascript">
    $("[data-fancybox]").fancybox({
        // Options will go here
    });
</script>

在CodePen上查看例子

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

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

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

在CodePen上查看例子

3.3 手动调用fancyBox

fancyBox允许使用JavaScript随时触发，因此不必需要通过某一个元素触发。下面例子为展示一段简单点信息：

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

在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

对于行内元素，创建一个隐藏的元素并独特的is属性：

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

然后只需要创建一个带有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上查看例子

To access and control fancyBox in parent window from inside an iframe:

// 根据内容调整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中，只需要提供页面的地址即可：

“`html

YouTube video

Vimeo video

Google Map

balloon rides at dawn ✨

【翻译】fancyBox 3中文文档

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. 嵌入

相关阅读

相关文章

相关问答

相关文档