fancyBox-中文文档(教程).doc

fancyBox 中文文档
fancyBox 为您的网页提供惊艳的缩放功能，同时支持图片、网页内容以及各种多媒体文件。
她基于目前最流行的 jQuery 框架开发，不仅易于应用，而且可以定制。欢迎来到 fancyBox 的世界~
· 更新日志
· 快速入门
· 常见用法
· 官方演示
· 使用许可&下载地址
· 完整API
· 常见问题
更新日志
重大变更
· 可扩展的幻灯片导航工具
· 响应式（调整浏览器窗口大小时自适应窗口大小）
· 集成幻灯片图片播放功能
· 新增幻灯片过渡效果
· 引入CSS3阴影、圆角特效
· 新的插件选项（与之前版本不兼容）
· 改用 知识共享署名-非商业性使用3.0 许可协议授权
即将上线
· WordPress小插件
· 重构本站及API文档
· 完善缩略图浏览工具
· fancyBox 手机版（待定）
· fancyBox 3.0
↑回顶部
快速入门
1. 下载 fancyBox，解压后根据需要将文件复制到网页文件夹中（建议不要更改目录结构），并在网页源码中引入相应的 css 样式和 js 文件（如果更改了目录结构，引入的时候请调整相应代码，对应它们所在的路径）。
注意：别忘了还要先加载 jQuery 库！推荐使用公共库：百度 | 新浪。示例代码：
<!-- 加载 jQuery 库（必须） --><script type="text/javascript" src="
<!-- 引入 fancyBox 核心文件（必须）--><link rel="stylesheet" href="/fancybox/source/jquery.fancybox.css?v=2.1.5" type="text/css" media="screen" /><script type="text/javascript" src="/fancybox/source/jquery.fancybox.pack.js?v=2.1.5"></script>
<!-- 引入 mousewheel 插件（可选，如果想通过鼠标滚轮控制图片播放则必须） --><script type="text/javascript" src="/fancybox/lib/jquery.mousewheel-3.0.6.pack.js"></script>
<!-- 根据需要引入浏览工具：按钮式，缩略图式和/或多媒体工具（可选，详见下方“官方演示”中的“浏览工具”部分） --><!-- 按钮式需要引入以下2个文件 --><link rel="stylesheet" href="/fancybox/source/helpers/jquery.fancybox-buttons.css?v=1.0.5" type="text/css" media="screen" /><script type="text/javascript" src="/fancybox/source/helpers/jquery.fancybox-buttons.js?v=1.0.5"></script>
<!-- 缩略图式需要引入以下2个文件 --><link rel="stylesheet" href="/fancybox/source/helpers/jquery.fancybox-thumbs.css?v=1.0.7" type="text/css" media="screen" /><script type="text/javascript" src="/fancybox/source/helpers/jquery.fancybox-thumbs.js?v=1.0.7"></script>
<!-- 多媒体工具需要引入以下文件 --><script type="text/javascript" src="/fancybox/source/helpers/jquery.fancybox-media.js?v=1.0.6"></script>
2. 给触发 fancyBox 特效的元素（如一张缩略图或“点击我”三个字）加上 a 链接，并将其 href 属性值设置为遮罩层中需要展示的文件的链接（如刚刚那张缩略图的原图的网址）。示例代码：
<a class="fancybox" rel="group" href="原图_1.jpg"><img src="缩略图_1.jpg" alt="" /></a><a class="fancybox" rel="group" href="原图_2.jpg"><img src="缩略图_2.jpg" alt="" /></a>
3. 使页面加载完毕时初始化 fancybox() 函数。如果你不懂jQuery但英语还行，请看官方推荐的新手教程。英语不好肿么办？请点右上角的红叉...因为暂时找不到中文版的帮助文档。示例代码：
<script type="text/javascript">
$(document).ready(function() {
$(".fancybox").fancybox();
});</script>
好了，你已经学会使用 fancyBox 了，新技能 Get！
↑回顶部
常见用法
每一个链接都有对应的源码可供参考
1. 更改遮罩层的颜色和透明度
2. 去除白色边框
3. 切换图片时使用淡出效果
4. 为全部图片添加 fancyBox 特效
5. 关闭 fancyBox 后刷新页面
6. 霸屏模式（姑且这么叫吧-_-#）
7. 调用YouTube API - 当前视频播放完时自动播放下一个
8. 在 iframe 中打开 PDF 文件
9. 禁用锁定模式 - 默认会锁定遮罩层中的内容
10. 圆点式浏览工具（类似于轮播）
11. 保护版权：禁止右键点击（添加水印）
12. 和 title 相关的：
o 通过添加属性值自定义 title
o 读取并显示缩略图的 "alt" 属性值 - 默认是显示其 "title" 属性值
o 调用内联 div 作为 title 显示
o title 显示在白框外，图片下方
o title 显示在白框内，图片上方
o 禁用 title
o 在 title 中加入其他内容（如下载链接）
o 鼠标悬停时显示 title
13. 去除两边的导航小箭头：
o 全部去除
o 仅去除"iframe"的
14. 自定义内容：
o 显示社交图标（只能Twitter或Facebook）
o 添加自定义图标（如全屏图标）
o 附加自定义内容
o 其他网站的富媒体
15. 只用一张缩略图触发相册：
o 方案一：隐藏其他缩略图（多个相册）
o 方案二：在 js 代码中传入其他图片的链接（多个相册）
16. 页面加载完毕自动打开fancyBox：
o 方案一：触发任一元素（真不是错别字，请体会“任一”和“任意”的区别）
o 方案二：通过 js 触发
17. 单独设置参数（比如高度、宽度）：
o 通过 HTML5 data 属性
o 通过 URL 链接传递参数
o 通过元数据（metadata）
o 通过元素的ID，用js控制
↑回顶部
官方演示
你也可以直接到 这里 查看网页的源代码。
· 单张图片
· HTML
· JavaScript
$(document).ready(function() {
$("#single_1").fancybox({
helpers: {
title : {
type : 'float'
}
}
});

$("#single_2").fancybox({
openEffect : 'elastic',
closeEffect : 'elastic',

helpers : {
title : {
type : 'inside'
}
}
});

$("#single_3").fancybox({
openEffect : 'none',
closeEffect : 'none',
helpers : {
title : {
type : 'outside'
}
}
});

$("#single_4").fancybox({
helpers : {
title : {
type : 'over'
}
}
});});
注意：每个元素的 ID 属性值不能重复
要使多张图片构成相册，请为不同的图片设置相同的 "data-fancybox-group" 或 "rel" 属性值。如下所示：
· 图片相册
· HTML
· JavaScript

fancyBox 通过 "href" 或 "data-fancybox-href" 的属性值来获取要加载的元素，同时判定其 MIME 类型。你可以通过给元素添加 "fancybox.image"、 "fancybox.iframe" 等 css 类或通过设置 "data-fancybox-type" 的属性值来直接指定文件的类型。要设置元素的title描述请设置 "title" 或 "data-fancybox-title" 的属性值。
· 其他类型
· HTML
· JavaScript
· Ajax数据
· Iframe
· 内联层
· swf文件
· Youtube视频 (iframe)
· Google地图 (iframe)
· 不存在的链接
或者，可以在初始化 fancybox() 函数的 js 代码中直接传入参数，指定元素的 MEMI 类型，例如指定 "open_ajax" 类的元素均为 "ajax" 类型：
$(".open_ajax").fancybox({type: 'ajax'});.
注意：ajax 请求遵循 同源策略，也就是说不能跨域访问。
浏览工具
注意：只有加载了相应文件以后浏览工具才会生效。
· 按钮式浏览工具
· HTML
· JavaScript

· 缩略图式浏览工具
· HTML
· JavaScript

· 多媒体浏览工具
· HTML
· JavaScript
该工具会自动将网址中包含的视频、音乐、图片等嵌入遮罩层中，而不是将链接指向的整个网页以 iframe 的形式打开。可惜大部分只支持墙外站点，优酷、土豆等均无法使用。
· Youtube
· 优酷（经测试无效）
· Vimeo
· Metacafe
· Dailymotion
· Twitvid
· Twitpic
· Instagram
· Google地图
o 地点搜索结果
o 显示某个地方
o 谷歌街景
↑回顶部
使用许可&下载地址
fancyBox 采用 知识共享署名-非商业性使用3.0 许可协议授权。
对于个人网站和非营利性网站，你可以免费使用。
如需商用，请 点击这里 购买授权。
最新的源码可以通过 GitHub 获取。
下载 v2.1.5 购买商业授权
↑回顶部
完整API
· 可用参数
· API 函数
· 回调函数
你可以通过键/值对象的形式将参数传递给 fancybox()。你也可以直接修改 js 文件中的源码或通过 $.fancybox.defaults 覆盖默认配置。
参数名
参数值&简介
padding
浏览框的内边距。可以通过数组的形式设定 - [top, right, bottom, left]
整数/数组； 默认值：15
margin
浏览框的外边距。可以通过数组的形式设定 - [top, right, bottom, left]。如果浏览框中内容的大小超出浏览器视区，则右外边距和底外边距自动失效
整数/数组； 默认值：20
width
iframe 和 swf 文件的默认宽度。对于 'autoSize' 值为 'false' 的内联文本、ajax数据以及html页面同样可以通过它设定宽度。可以是具体的数值或者'auto'
数字/字符串； 默认值：800
height
iframe 和 swf 文件的默认高度。对于 'autoSize' 值为 'false' 的内联文本、ajax数据以及html页面同样可以通过它设定高度。可以是具体的数值或者'auto'
数字/字符串； 默认值：600
minWidth
自适应窗口大小时的最小宽度
数字； 默认值：100
minHeight
自适应窗口大小时的最小高度
数字； 默认值： 100
maxWidth
自适应窗口大小时的最大宽度
数字； 默认值：9999
maxHeight
自适应窗口大小时的最大高度
数字； 默认值：9999
autoSize
是否自适应内容的宽高。若为 true，则 autoHeight 和 autoWidth 的值自动设为 true
布尔值；默认值：true
autoHeight
是否自动调节高度。若为 true，则内联文本、ajax 数据以及 html 页面的宽度（不知道原作者是不是和下面写反了...）自动调节
布尔值；默认值：false
autoWidth
是否自动调节宽度。若为 true，则内联文本、ajax 数据以及 html 页面的高度（不知道原作者是不是和上面写反了...）自动调节
布尔值；默认值：false
autoResize
是否自适应窗口变化。若为 true，则窗口大小发生改变时自动适应其大小
布尔值；默认值：!isTouch
autoCenter
是否自动居中。若为 true，则浏览框始终处于视区中心
布尔值；默认值：!isTouch
fitToView
是否自适应视区。若为 true，则在打开之前会自适应视区的大小。（好吧，其实这个我没看懂...关键是作者没有demo啊...）
布尔值；默认值：true
aspectRatio
是否保持长宽比。若为 true，则自适应窗口大小时保持长宽比不变（对于图像，长宽比始终不变；对于其他类型文件，参考 这里 更改长宽比）
布尔值；默认值：false
topRatio
纵向位置系数。如果值为0.5，则纵向居中。如果值为0，则居顶
数字；默认值：0.5
leftRatio
横向位置系数。如果值为0.5，则横向居中。如果值为0，则居左
数字；默认值：0.5
scrolling
显示或隐藏滚动条，可以设为 'auto'、'yes'、'no' 或者 'visible'
字符串；默认值：'auto'
wrapCSS
为遮罩层自定义 css
字符串；默认值：无
arrows
是否显示两侧导航小箭头，true 为显示
布尔值；默认值：true
closeBtn
是否显示关闭图标，true 为显示
布尔值；默认值：true
closeClick
是否单击关闭。若为 true，则当用户点击浏览框内时会关闭 fancyBox
布尔值；默认值：false
nextClick
是否单击继续。若为 true，则当用户点击浏览框内时会显示下一个内容
布尔值；默认值：false
mouseWheel
是否响应鼠标滚轮操作。若为 true，则用户可以用鼠标滚轮控制播放
布尔值；默认值：true
autoPlay
是否自动播放。若为 true，则打开遮罩层后自动进入幻灯片模式播放
布尔值；默认值：false
playSpeed
幻灯片播放速度。单位：毫秒
整数；默认值：3000
preload
预加载图片的数量
整数；默认值： 3
modal
是否关闭导航小箭头和关闭按钮的显示
布尔值；默认值：false
loop
是否循环播放。若为 true，则当播放到最后一张图时会从第一张重新开始
布尔值；默认值：true
ajax
设定 ajax 请求参数
对象；默认值：
{
dataType : 'html',
headers : { 'X-fancyBox': true }}
iframe
设定 iframe 参数
对象；默认值：
{
scrolling : 'auto',
preload : true}
swf
设定 swf 文件参数
对象；默认值：
{
wmode: 'transparent',
allowfullscreen : 'true',
allowscriptaccess : 'always'}
keys
设定控制和关闭幻灯片的键盘快捷键。
对象；默认值：
{
next : {
13 : 'left', // enter
34 : 'up', // page down
39 : 'left', // right arrow
40 : 'up' // down arrow
//下一个：回车，PageDown，→，↓
},
prev : {
8 : 'right', // backspace
33 : 'down', // page up
37 : 'right', // left arrow
38 : 'down' // up arrow
//上一个：退格，PageUp，←，↑
},
close : [27], // escape key
//关闭：ESC
play : [32], // space - start/stop slideshow
//开始/暂停：空格
toggle : [70] // letter "f" - toggle fullscreen
//全屏/退出全屏：F}
direction
导航小箭头的默认方向
对象；默认值：
{
{
next : 'left',
prev : 'right'
}}
scrollOutside
若为 true，则浏览框将尽量避免出现横向滚动条。适用于 iframe 和 html
布尔值；默认值：true
index
设定从第几个对象开始播放（从0开始计数）
整数；默认值： 0
type
设定 MEMI 类型。支持设置为 'image'、'inline'、'ajax'、'iframe'、'swf' 和 'html'
字符串；默认值：null
href
覆盖要显示内容的链接
字符串；默认值：null
content
覆盖要显示的内容
字符串；默认值：null
title
覆盖 title 描述，支持使用 html
字符串；默认值：null
tpl
设定包含多个模板的对象
对象；默认值：
{
wrap : '<div class="fancybox-wrap" tabIndex="-1"><div class="fancybox-skin"><div class="fancybox-outer"><div class="fancybox-inner"></div></div></div></div>',
image : '<img class="fancybox-image" src="{href}" alt="" />',
iframe : '<iframe id="fancybox-frame{rnd}" name="fancybox-frame{rnd}" class="fancybox-iframe" frameborder="0" vspace="0" hspace="0"' + ($.browser.msie ? ' allowtransparency="true"' : '') + '></iframe>',
error : '<p class="fancybox-error">The requested content cannot be loaded.<br/>Please try again later.</p>',
closeBtn : '<a title="Close" class="fancybox-item fancybox-close" href="javascript:;"></a>',
next : '<a title="Next" class="fancybox-nav fancybox-next" href="javascript:;"><span></span></a>',
prev : '<a title="Previous" class="fancybox-nav fancybox-prev" href="javascript:;"><span></span></a>'}
openEffect / closeEffect / nextEffect / prevEffect
设定相应事件（左边从上到下依次是打开、关闭、下一个、上一个）的动画效果。可选 'elastic'、 'fade' 或 'none'
字符串；默认值：'fade', 'fade', 'elastic', 'elastic'
openSpeed / closeSpeed / nextSpeed / prevSpeed
设定相应动画效果（左边从上到下依次是打开、关闭、下一个、上一个）的时间。单位：毫秒。或者直接用 "slow"、"normal" 或 "fast"
整数/字符串；默认值：250
openEasing / closeEasing / nextEasing / prevEasing
设定相应事件（左边从上到下依次是打开、关闭、下一个、上一个）的 Easing 效果。需引入 jQuery Easing 插件
字符串；默认值：'swing'
openOpacity / closeOpacity
若为 true，则打开和关闭时会有透明度的过渡
布尔值；默认值：true
openMethod / closeMethod / nextMethod / prevMethod
从 $.fancybox.transitions() 调用相应事件（左边从上到下依次是打开、关闭、下一个、上一个）的过渡方法（可以自行添加）
字符串；默认值：'zoomIn' / 'zoomOut' / 'changeIn' / 'changeOut'
helpers
若启用了浏览工具，则通过这个对象设置参数
对象；默认值：
{
overlay : {
closeClick : true, // 若为true，则当用户点击遮罩层时会自动关闭 fancyBox
speedOut : 200, // 淡出动画的间隔，单位：毫秒
showEarly : true, // 立即打开 fancyBox 还是等内容加载完毕再打开
css : {}, // 自定义 CSS
locked : true // 若为 true，则内容会被锁定在遮罩层中
},
title : {
type : 'float' // title 的位置，可选 'float'、 'inside'、'outside' 或 'over'
}}
live
If set to true, fancyBox uses "live" to assign click event. Set to "false", if you need to apply only to current collection, e.g., if using something like - 
（呃...时至今日还是看不懂...）
$("#page").children().filter('a').eq(0).fancybox();

布尔值；默认值：true
parent
设定父元素
$(".fancybox").fancybox({
parent: "form:first" // jQuery 选择器});

字符串；默认值: body
浏览工具
浏览工具的引入为 fancyBox 增色不少。fancyBox 内置两套工具——遮罩层和title。你可以禁用它们、自定义它们或者启用其他的工具。例如：
//禁用 title 工具
$(".fancybox").fancybox({
helpers: {
title: null
}});
//禁用遮罩层工具
$(".fancybox").fancybox({
helpers: {
overlay : null
}});
//更改title的位置；对象加载完毕以后再显示遮罩层
$(".fancybox").fancybox({
helpers: {
title : {
type : 'inside'
},
overlay : {
showEarly : false
}
}});
//启用缩略图工具，并自定义参数
$(".fancybox").fancybox({
helpers: {
thumbs : {
width: 50,
height: 50
}
}});
按钮式工具可用参数
参数名
参数值&简介
tpl
HTML 模板
position
按钮位置，'top' 或 'bottom'
缩略图式工具可用参数
参数名
参数值&简介
width
缩略图宽度
height
缩略图高度
source
缩略图链接。如果不提供，默认使用 a 标签中的第一个图像。
例如： 
position
缩略图位置，'top' 或 'bottom'
↑回顶部
FAQs
1. 图片都是在新窗口打开的，出啥错了？
请检查是否在网页中引入了所需的相关css和js文件，尤其是jQuery，必须第一个加载。
2. fancyBox 怎么样才不会被 flash 遮挡？
请参考 这个帮助文档 。
3. 我能从 iframe 中调用 fancyBox 吗？
如果父窗口中引入了所需的全部文件，那么是可以的。例如：
<a href="javascript:parent.$.fancybox.open({href : 'myurl'});">点我打开</a>
4. 我怎么通过其他元素关闭 fancyBox ？
给其他元素添加onClick事件，并调用 $.fancybox.close() 函数即可。
5. fancyBox 只对第一张图片有效，其他全部失效，这是什么情况？
可能由于你在使用 ID 选择器，而不是类选择器。将 $("#selector").fancybox(); 改成$(".selector").fancybox(); 即可。