图片浏览器是一个像iOS图片浏览器一样用来展示图片的组件。图片可以被缩放或者平移 (可选)。
图片浏览器使用 幻灯片组件来展现图片。
创建一个图片浏览器实例
图片浏览器只需通过javaScript就可以被创建和初始化。我们需要使用App封装好的方法:
myApp.photoBrowser(parameters) - 带参初始化图片浏览器
- parameters - object - 图片浏览器参数对象(必选)。
- 该方法返回图片浏览器实例引用
示例:
- var myPhotoBrowser = app.photoBrowser({
- zoom: 400,
- photos: ['path/to/image1.jpg', 'path/to/image2.jpg']
- });
- myPhotoBrowser.open(); // 打开图片浏览器
图片浏览器参数
所有可用参数列表:
参数(Parameter) | 类型(Type) | 默认(Default) | 描述(Description) |
---|---|---|---|
photos | array | [] | 照片的url数组或者是包含“url”(或者“html”)和“caption”属性的对象数组. |
initialSlide | number | 0 | 初始化时展示的图片序号 |
spaceBetween | number | 20 | 图片展现间隔距离(px) |
speed | number | 300 | 切换图片的时间间隔(ms) |
zoom | boolean | true | 是否启用图片的缩放和平移功能 |
maxZoom | number | 3 | 最大缩放倍数 |
minZoom | number | 1 | 最小缩放倍数 |
exposition | boolean | true | 图片点击时是否启用浏览模式 |
expositionHideCaptions | boolean | false | 是否在浏览模式中隐藏标题 |
swipeToClose | boolean | true | 是否可以通过上下滑动的方式来关闭图片浏览器 |
view | View instance | undefined | 如果想用page形式打开,则需要指定一个初始化的View实例,如果不指定,将默认在Main View中打开 |
type | string | 'standalone' | 定义图片浏览器的打开方式,可选参数有'standalone'(打开时将有一个自定义过渡效果的遮罩层),'popup'(打开一个popup),’page‘(将被放置于View中,作为一个新页面加载) |
loop | boolean | false | Set to "true" to enable continuous loop mode |
theme | string | 'light' | 图片浏览器颜色主题,可以为'light'或者'dark' |
captionsTheme | string | 标题的颜色主题,可以为light'或者'dark'。默认与"theme"相同 | |
navbar | boolean | true | 是否生成图片浏览器的导航栏 |
toolbar | boolean | true | 是否生成图片浏览器的工具栏 |
backLinkText | string | 'Close' | 图片浏览器的导航栏中返回链接的文本 |
ofText | string | 'of' | 图片的序号和总数之间的分割词,例如:"3 of 5" |
懒加载 | |||
lazyLoading | boolean | false | 设置为true启用懒加载 |
lazyLoadingInPrevNext | boolean | false | 设置为 true,则会懒加载最近的图片(上一个和下一个) |
lazyLoadingOnTransitionStart | boolean | false | 默认情况下,图片浏览器在动画结束后开始懒加载。如果你希望在动画开始的时候就开始懒加载,你可以设置这个参数。 |
模板 | |||
template | string | *见下面 | 图片浏览器的HTML模版 |
navbarTemplate | string | *见下面 | 导航栏的HTML模版 |
toolbarTemplate | string | *见下面 | 工具栏的HTML模版 |
photoTemplate | string | *见下面 | 单独图片元素的HTML模版 |
photoLazyTemplate | string | *Look below | Single lazy loading photo element HTML template |
objectTemplate | string | *见下面 | 单独对象元素的HTML模版 |
captionTemplate | string | *见下面 | 单独标题元素的HTML模版 |
回调函数 | |||
onOpen(photobrowser) | function | 回调函数,当图片浏览器被打开的时候执行 | |
onClose(photobrowser) | function | 回调函数,当图片浏览器被关闭的时候执行 | |
onSwipeToClose(photobrowser) | function | 回调函数,当图片浏览器通过上下滑动的形式关闭时执行 | |
Swiper Callbacks | |||
onSlideChangeStart(swiper) | function | 回调函数,当图片浏览器向前或者向后切换图片开始的时候执行,接受幻灯片的实例作为参数 | |
onSlideChangeEnd(swiper) | function | ||
onTransitionStart(swiper) | function | Callback function, will be executed in the beginning of transition. Receives swiper instance as an argument. | |
onTransitionEnd(swiper) | function | Callback function, will be executed after transition. Receives slider instance as an argument. | |
onClick(swiper, event) | function | 回调函数,当图片浏览器被点击/触碰的时候延迟300ms执行,接受幻灯片的实例和touchend事件两个对象作为参数 | |
onTap(swiper, event) | function | 回调函数,当图片浏览器被点击/触碰的时候执行,接受幻灯片的实例和touchend事件两个对象作为参数 | |
onDoubleTap(swiper, event) | function | 回调函数,当图片浏览器被连续两次触碰的时候执行,接受幻灯片的实例和touchend事件两个对象作为参数 | |
onLazyImageLoad(swiper, slide, image) | function | Callback function, will be executed when Photo Browser begins to load lazy loading photo | |
onLazyImageReady(swiper, slide, image) | function | Callback function, will be executed after lazy loading photo will be loaded |
图片浏览器方法及属性
当我们初始化图片浏览器之后,我们将会得到它的实例引用(比如myPhotoBrowser
), 并且包括很多有用的方法和属性:
属性 | |
---|---|
myPhotoBrowser.swiper | 包含一个Swiper 实例,这个实例上有所有可用的Swiper 方法和属性 |
myPhotoBrowser.container | Dom7形式的图片浏览器HTML容器 |
myPhotoBrowser.exposed | 图片浏览器是否处于浏览模式 |
myPhotoBrowser.activeSlideIndex | 当前可见的幻灯片的序号 |
myPhotoBrowser.params | 传入的初始化参数对象 |
方法 | |
myPhotoBrowser.open(index); | 根据“index”参数的值打开图片浏览器,如果“index”参数没有被指定,则打开最后关闭的图片 |
myPhotoBrowser.close(); | 关闭图片浏览器 |
myPhotoBrowser.toggleZoom(); | 切换当前幻灯片的缩放形式 |
myPhotoBrowser.toggleExposition(); | 切换浏览模式 |
myPhotoBrowser.enableExposition(); | 启用浏览模式 |
myPhotoBrowser.disableExposition(); | 禁用浏览模式 |
图片数组
当我们初始化图片浏览器的时候,需要传递一个数组,包括图片或者是视频的相关信息,让我们看看这个数组的各种变形:
- //如果我们只需要图片的话,可以传递图片地址数组
- var photos = [
- 'image1.jpg',
- 'image2.jpg',
- 'image3.jpg',
- 'image4.jpg',
- ];
- //如如果我们需要标题的话,则需要包装成一个含有caption属性的对象:
- var photos = [
- {
- url: 'image1.jpg',
- caption: 'Caption 1'
- },
- {
- url: 'image2.jpg',
- caption: 'Caption 1'
- },
- // 这个是没有标题的
- {
- url: 'image3.jpg',
- },
- // 也可以不使用对象形式
- 'image4.jpg'
- ];
- //如果我们需要使用视频,则把包含视频元素的HTML片段或者是iframe放到“html”属性里:
- var photos = [
- {
- url: 'image1.jpg',
- caption: 'Caption 1'
- },
- // 带标题的视频
- {
- html: '<video src="video1.mp4"></video>',
- caption: 'Video Caption'
- },
- // 这个是没有标题的iframe
- {
- html: '<iframe src="..."></iframe>',
- },
- // 这个是没有标题的视频标签
- '<video src="video2.mp4"></video>'
- ];
示例
- <div class="page-content">
- <div class="content-block-title">Light Theme</div>
- <div class="content-block row">
- <div class="col-33"><a href="#" class="button pb-standalone">Standalone</a></div>
- <div class="col-33"><a href="#" class="button pb-popup">Popup</a></div>
- <div class="col-33"><a href="#" class="button pb-page">Page</a></div>
- </div>
- <div class="content-block-title">Dark Theme</div>
- <div class="content-block row">
- <div class="col-50"><a href="#" class="button pb-standalone-dark">Standalone</a></div>
- <div class="col-50"><a href="#" class="button pb-popup-dark">Popup</a></div>
- </div>
- </div>
- var myApp = new Framework7();
- var $$ = Dom7;
- var mainView = myApp.addView('.view-main', {
- dynamicNavbar: true
- });
- /*=== 默认为 standalone ===*/
- var myPhotoBrowserStandalone = myApp.photoBrowser({
- photos : [
- 'http://lorempixel.com/1024/1024/sports/1/',
- 'http://lorempixel.com/1024/1024/sports/2/',
- 'http://lorempixel.com/1024/1024/sports/3/',
- ]
- });
- //点击时打开图片浏览器
- $$('.pb-standalone').on('click', function () {
- myPhotoBrowserStandalone.open();
- });
- /*=== Popup ===*/
- var myPhotoBrowserPopup = myApp.photoBrowser({
- photos : [
- 'http://lorempixel.com/1024/1024/sports/1/',
- 'http://lorempixel.com/1024/1024/sports/2/',
- 'http://lorempixel.com/1024/1024/sports/3/',
- ],
- type: 'popup'
- });
- $$('.pb-popup').on('click', function () {
- myPhotoBrowserPopup.open();
- });
- /*=== 作为Page ===*/
- var myPhotoBrowserPage = myApp.photoBrowser({
- photos : [
- 'http://lorempixel.com/1024/1024/sports/1/',
- 'http://lorempixel.com/1024/1024/sports/2/',
- 'http://lorempixel.com/1024/1024/sports/3/',
- ],
- type: 'page',
- backLinkText: 'Back'
- });
- $$('.pb-page').on('click', function () {
- myPhotoBrowserPage.open();
- });
- /*=== Standalone Dark ===*/
- var myPhotoBrowserDark = myApp.photoBrowser({
- photos : [
- 'http://lorempixel.com/1024/1024/sports/1/',
- 'http://lorempixel.com/1024/1024/sports/2/',
- 'http://lorempixel.com/1024/1024/sports/3/',
- ],
- theme: 'dark'
- });
- $$('.pb-standalone-dark').on('click', function () {
- myPhotoBrowserDark.open();
- });
- /*=== Popup Dark ===*/
- var myPhotoBrowserPopupDark = myApp.photoBrowser({
- photos : [
- 'http://lorempixel.com/1024/1024/sports/1/',
- 'http://lorempixel.com/1024/1024/sports/2/',
- 'http://lorempixel.com/1024/1024/sports/3/',
- ],
- theme: 'dark',
- type: 'popup'
- });
- $$('.pb-popup-dark').on('click', function () {
- myPhotoBrowserPopupDark.open();
- });
- /*=== 有标题 ===*/
- var myPhotoBrowserPopupDark = myApp.photoBrowser({
- photos : [
- {
- url: 'http://lorempixel.com/1024/1024/sports/1/',
- caption: 'Caption 1 Text'
- },
- {
- url: 'http://lorempixel.com/1024/1024/sports/2/',
- caption: 'Second Caption Text'
- },
- // 这个没有标题
- {
- url: 'http://lorempixel.com/1024/1024/sports/3/',
- },
- ],
- theme: 'dark',
- type: 'standalone'
- });
- $$('.pb-standalone-captions').on('click', function () {
- myPhotoBrowserPopupDark.open();
- });
- /*=== 有视频 ===*/
- var myPhotoBrowserPopupDark = myApp.photoBrowser({
- photos : [
- {
- html: '<iframe src="//www.youtube.com/embed/lmc21V-zBq0?list=PLpj0FBQgLGEr3mtZ5BTwtmSwF1dkPrPRM" frameborder="0" allowfullscreen></iframe>',
- caption: 'Woodkid - Run Boy Run (Official HD Video)'
- },
- {
- url: 'http://lorempixel.com/1024/1024/sports/2/',
- caption: 'Second Caption Text'
- },
- {
- url: 'http://lorempixel.com/1024/1024/sports/3/',
- },
- ],
- theme: 'dark',
- type: 'standalone'
- });
- $$('.pb-standalone-video').on('click', function () {
- myPhotoBrowserPopupDark.open();
- });
图片浏览器模版
让我们来看看图片浏览器可用于初始化时的模版
图片浏览器主模版
您可以通过template
参数传递定制的HTML模板。这是一个示例:
- <div class="photo-browser photo-browser-{{theme}}">
- <div class="view navbar-fixed toolbar-fixed">
- {{#unless material}}{{#if navbar}}
- navbarTemplate
- {{/if}}{{/unless}}
- <div class="page no-toolbar {{#unless navbar}}no-navbar{{/unless}} toolbar-fixed navbar-fixed" data-page="photo-browser-slides">
- {{#if material}}{{#if navbar}}
- navbarTemplate
- {{/if}}{{/if}}
- {{#if toolbar}}
- toolbarTemplate
- {{/if}}
- <div class="photo-browser-captions photo-browser-captions-{{js "this.captionsTheme || this.theme"}}">
- {{#each photos}}{{#if caption}}
- captionTemplate
- {{/if}}{{/each}}
- </div>
- <div class="photo-browser-swiper-container swiper-container">
- <div class="photo-browser-swiper-wrapper swiper-wrapper">
- {{#each photos}}
- {{#js_compare "this.html || ((typeof this === \'string\' || this instanceof String) && (this.indexOf(\'<\') >= 0 || this.indexOf(\'>\') >= 0))"}}
- objectTemplate
- {{else}}
- {{#if @root.lazyLoading}}
- photoLazyTemplate
- {{else}}
- photoTemplate
- {{/if}}
- {{/js_compare}}
- {{/each}}
- </div>
- </div>
- </div>
- </div>
- </div>
导航栏模版
这是导航栏的示例模版,你可以通过navbarTemplate
参数传递:
- <div class="navbar">
- <div class="navbar-inner">
- <div class="left sliding">
- <a href="#" class="link close-popup photo-browser-close-link {{#unless backLinkText}}icon-only{{/unless}} {{js "this.type === \'page\' ? \'back\' : \'\'"}}">
- <i class="icon icon-back {{iconsColorClass}}"></i>
- {{#if backLinkText}}<span>{{backLinkText}}</span>{{/if}}
- </a>
- </div>
- <div class="center sliding">
- <span class="photo-browser-current"></span>
- <span class="photo-browser-of">{{ofText}}</span>
- <span class="photo-browser-total"></span>
- </div>
- <div class="right"></div>
- </div>
- </div>
其中:
-
<a class="photo-browser-close-link">
- 点击时将关闭图片浏览器,并且解绑所有的监听器 -
<span class="photo-browser-current">
- 图片浏览器将在该元素中插入当前的活动图片序号 -
<span class="photo-browser-total">
- 图片浏览器将在该元素中插入幻灯片总数
工具栏模版
这是工具栏的示例模版,你可以通过toolbarTemplate
参数传递:
- <div class="toolbar tabbar">
- <div class="toolbar-inner">
- <a href="#" class="link photo-browser-prev">
- <i class="icon icon-prev {{iconsColorClass}}"></i>
- </a>
- <a href="#" class="link photo-browser-next">
- <i class="icon icon-next {{iconsColorClass}}"></i>
- </a>
- </div>
- </div>
它其实就是一个标签栏,其中:
-
<a class="photo-browser-next">
-带有photo-browser-next类的链接,可以充当下一个按钮 -
<a class="photo-browser-prev">
- 带有photo-browser-prev类的链接,可以充当上一个按钮
图片元素模版
这是一张幻灯片的模版,你可以通过photoTemplate
参数传递;
- <div class="photo-browser-slide swiper-slide">
- <span class="photo-browser-zoom-container">
- <img src="{{js "this.url || this"}}">
- </span>
- </div>
Lazy Photo Element Template
Template example of single photo slide element that you can pass in photoLazyTemplate
parameter:
- <div class="photo-browser-slide photo-browser-slide-lazy swiper-slide">
- <div class="preloader {{@root.preloaderColorClass}}">{{#if @root.material}}{{@root.materialPreloaderSvg}}{{/if}}</div>
- <span class="photo-browser-zoom-container">
- <img data-src="{{js "this.url || this"}}" class="swiper-lazy">
- </span>
- </div>
Object Element Template
Template example of single object slide element that you can pass in objectTemplate
parameter:
- <div class="photo-browser-slide photo-browser-object-slide swiper-slide">{{js "this.html || this"}}</div>
Single Caption Template
Template example of sinble caption element. You can pass in captionTemplate
parameter:
- <div class="photo-browser-caption" data-caption-index="{{@index}}">
- {{caption}}
- </div>