语言: 英文中文

图片浏览器(Photo Browser)

图片浏览器是一个像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>