照片浏览器

相册浏览器是一个用于显示照片/图像集合的组件。照片可以缩放和平移(可选)。

相册浏览器使用Swiper滑块组件在照片之间滑动。

Photo Browser应用方法

让我们看看与相册浏览器相关的方法来使用它:

app.photoBrowser.create(参数)- 创建相册浏览器实例

  • 参数 - 对象. 带有相册浏览器参数的对象

方法返回创建的相册浏览器的实例

app.photoBrowser.destroy(el)- 销毁相册浏览器实例

  • el - HTMLElement字符串(使用 CSS 选择器) 或对象. 要销毁的相册浏览器元素或相册浏览器实例。

app.photoBrowser.get(el)- 通过 HTML 元素获取相册浏览器实例

  • el - HTMLElement字符串(使用 CSS 选择器)。相册浏览器元素。

方法返回相册浏览器的实例

例如:

var photoBrowser = app.photoBrowser.create({
  photos: [
    'path/to/photo-1.jpg',
    'path/to/photo-2.jpg'
  ],
});

Photo Browser参数

让我们看看所有可用相册浏览器参数的列表:

参数类型默认描述
photos数组[]包含照片 URL 的数组或包含 "url"(或 "html")和 "caption" 属性的对象数组。
thumbs数组[]包含缩略图图像 URL 的数组。如果未指定,或为空数组,则不会渲染缩略图
exposition布尔值true在点击相册浏览器时启用/禁用展览模式。
expositionHideCaptions布尔值false如果您还想在展览模式下隐藏标题,请将其设置为 true
swipeToClose布尔值true当启用此参数时,您可以用向上/向下滑动关闭相册浏览器
popupPush布尔值false启用相册浏览器弹出窗口在打开时将视图/页面推到后面
routableModals布尔值false将打开的相册浏览器添加到路由历史记录中,这提供了通过在路由历史记录中后退来关闭相册浏览器的功能,并将当前路由设置为相册浏览器模态
url字符串photos/相册浏览器模态 URL 将被设置为当前路由
view对象如果你想要使用“页面”类型的相册浏览器或设置路由,请提供初始化的 View 实例。默认情况下,如果未指定,它将在主视图中打开。routableModals将会以
type字符串standalone定义相册浏览器应如何打开。可以是standalone(将作为具有自定义过渡效果的覆盖层打开),popup (will be opened as 弹出形式打开,page(将注入到 View 并作为新页面加载)。
主题字符串light相册浏览器颜色主题,可以是lightdark
captionsTheme字符串标题颜色主题,也可以是lightdark. 默认等于themeparameter
navbar布尔值true设置为 false 以移除相册浏览器的 Navbar
toolbar布尔值true设置为 false 以移除相册浏览器的 Toolbar
pageBackLinkText字符串Back相册浏览器 Navbar 中的后退链接文本
popupCloseLinkText字符串Close在弹出窗口或作为 Standalone 打开时,相册浏览器 Navbar 中的关闭链接文本
navbarShowCount布尔值undefined定义是否应在 Navbar 标题中显示 "3 of 5" 文本。如果未指定(undefined),则如果有超过 1 个项目,它将显示此文本
navbarOfText字符串'of'照片计数中的 "of" 文本:"3 of 5"
iconsColor字符串之一默认颜色之一
swiper对象Swiper 参数。默认等于:
swiper: {
  initialSlide: 0,
  spaceBetween: 20,
  speed: 300,
  loop: false,
  preloadImages: true,
  keyboard: {
    enabled: true,
  },
  navigation: {
    nextEl: '.photo-browser-next',
    prevEl: '.photo-browser-prev',
  },
  zoom: {
    enabled: true,
    maxRatio: 3,
    minRatio: 1,
  },
  lazy: {
    enabled: true,
  },
},
virtualSlides布尔值true当启用时,Swiper 将使用虚拟幻灯片
closeByBackdropClick布尔值true当启用时,相册浏览器弹出窗口将在点击背景时关闭
渲染函数
renderNavbar函数渲染导航栏的函数,必须返回导航栏的 HTML 字符串
renderToolbar函数渲染工具栏的函数,必须返回工具栏的 HTML 字符串
renderCaption函数(caption,index)渲染单个标题的函数,必须返回标题的 HTML 字符串
renderObject函数(photo,index)渲染照片对象的函数,必须返回照片对象的 HTML 字符串
renderLazyPhoto函数(photo,index)渲染懒加载照片滑动的函数,必须返回滑动的 HTML 字符串
renderPhoto函数(photo,index)渲染照片作为 Swiper 滑动的函数,必须返回滑动的 HTML 字符串
renderPage函数渲染相册浏览器页面的函数,必须返回完整的页面 HTML 布局字符串
renderPopup函数渲染相册浏览器弹出窗口的函数,必须返回完整的弹出窗口 HTML 布局字符串
renderStandalone函数渲染相册浏览器独立模态的函数,必须返回完整的模态 HTML 布局字符串
事件
on对象

带有事件处理程序的对象。例如:

var photoBrowser = app.photoBrowser.create({
  ...
  on: {
    opened: function () {
      console.log('photo browser opened')
    }
  }
})

注意,所有以下参数都可以在photoBrowser属性用于为所有相册浏览器设置默认值。例如:

var app = new Framework7({
  photoBrowser: {
    type: 'popup',
  }
});

照片数组

当我们初始化相册浏览器时,我们需要在photos参数中传递包含照片/视频的数组。让我们看看这个数组的不同变化:

// If we need photo browser with just photos we may pass array with string urls:
var photos = [
    'image1.jpg',
    'image2.jpg',
    'image3.jpg',
    'image4.jpg',
];

//If we need to use caption for some of photos then each photo should be presented as object:
var photos = [
    {
        url: 'image1.jpg',
        caption: 'Caption 1'
    },
    {
        url: 'image2.jpg',
        caption: 'Second Caption'
    },
    // This one will be without caption
    {
        url: 'image3.jpg',
    },
    // This one will be also without caption
    'image4.jpg'
];

//If we need to use videos in some slides we need to pass HTML element of video element or iframe within "html" property:
var photos = [
    {
        url: 'image1.jpg',
        caption: 'Caption 1'
    },
    // Video element with caption
    {
        html: '<video src="video1.mp4"></video>',
        caption: 'Video Caption'
    },
    // This one is embedded video without caption
    {
        html: '<iframe src="..."></iframe>',
    },
    // This one will be also video without caption
    '<video src="video2.mp4"></video>'
];

Photo Browser方法与属性

初始化相册浏览器后,我们在变量中拥有其初始化的实例(例如photoBrowser示例中使用的变量)中拥有颜色选择器的初始化实例,其中包含有用的方法和属性:

属性
photoBrowser.app链接到全局应用实例
photoBrowser.el相册浏览器 HTML 元素
photoBrowser.$el包含相册浏览器 HTML 元素的 Dom7 实例
photoBrowser.activeIndex当前活动照片滑动的索引号
photoBrowser.exposedtrue如果相册浏览器处于展示模式
photoBrowser.openedtrue如果相册浏览器当前已打开
photoBrowser.url相册浏览器 URL(传递在url参数中)
photoBrowser.view相册浏览器视图(传递在view参数中)或找到的父视图
photoBrowser.swiper包含所有可用 Swiper 方法和属性的初始化 Swiper 实例photoBrowser.params
photoBrowser.params包含初始化参数的对象
方法
photoBrowser.open(index)在具有等于 "index" 参数索引号的相册浏览器上打开。如果未指定 "index" 参数,它将在最后一个关闭的相册上打开。
photoBrowser.close()关闭相册浏览器
photoBrowser.expositionToggle()切换展览模式
photoBrowser.expositionEnable()启用展览模式
photoBrowser.expositionDisable()禁用展览模式
photoBrowser.destroy()销毁相册浏览器实例
photoBrowser.on(事件上触发, 处理程序)添加事件处理程序
photoBrowser.once(事件上触发, 处理程序)添加在触发后将被移除的事件处理程序
photoBrowser.off(事件上触发, 处理程序)移除事件处理程序
photoBrowser.off(事件上触发)移除指定事件的所有处理程序
photoBrowser.emit(事件上触发, ...args)在实例上触发事件

相册浏览器事件

相册浏览器将在相册浏览器元素上触发以下 DOM 事件,以及在应用和相册浏览器实例上触发事件:

DOM 事件

事件Target描述
photobrowser:open相册浏览器元素当相册浏览器开始其打开动画时将触发事件
photobrowser:opened相册浏览器元素相册浏览器完成打开动画后,将触发此事件
photobrowser:close相册浏览器元素当相册浏览器开始其关闭动画时将触发事件
photobrowser:closed相册浏览器元素相册浏览器完成关闭动画后,将触发此事件
photobrowser:beforedestroy相册浏览器元素在相册浏览器实例将被销毁之前将触发事件

应用和Photo Browser实例事件

相册浏览器实例在自身实例和应用实例上触发事件。应用实例事件具有相同名称,以photoBrowser.

事件Target描述
swipeToClosephotoBrowser当用户使用向上/向下滑动关闭相册浏览器时将触发事件。
tapphotoBrowserSwiper事件. 当用户点击/触摸 Swiper 时将触发事件。接收 'touchend' 事件作为参数。
clickphotoBrowserSwiper事件. 当用户点击/触摸 Swiper 时将触发事件。接收 'touchend' 事件作为参数。
doubleTapphotoBrowserSwiper事件. 当用户在 Swiper 的容器中双击时将触发事件。接收 'touchend' 事件作为参数
doubleClickphotoBrowserSwiper事件. 当用户在 Swiper 的容器中双击时将触发事件。接收 'touchend' 事件作为参数
slideChangephotoBrowserSwiper事件. 当当前活动的滑动改变时将触发事件
transitionStartphotoBrowserSwiper事件. 在过渡开始时将触发事件。
transitionEndphotoBrowserSwiper事件. 过渡结束后将触发事件。
slideChangeTransitionStartphotoBrowserSwiper事件. 在动画到其他滑动(下一个或上一个)开始时将触发事件。
slideChangeTransitionEndphotoBrowserSwiper事件. 动画到其他滑动(下一个或上一个)结束后将触发事件。
lazyImageLoadphotoBrowserSwiper事件. 在图像懒加载开始时将触发事件
lazyImageReadyphotoBrowserSwiper事件. 当懒加载图像加载完成时将触发事件
touchStartphotoBrowserSwiper事件. 当用户触摸Swiper时,将触发事件。接收'touchstart'事件作为参数。
touchMoveOppositephotoBrowserSwiper事件. 当用户在Swiper上触摸并朝与方向参数相反的方向移动手指时,将触发事件。接收'touchmove'事件作为参数。
touchEndphotoBrowserSwiper事件. 当用户释放Swiper时,将触发事件。接收'touchend'事件作为参数。
open为前缀photoBrowser当Photo Browser开始其打开动画时,将触发事件。作为参数,事件处理程序接收photoBrowser实例
photoBrowserOpenapp
openedphotoBrowser当Photo Browser完成其打开动画后,将触发事件。作为参数,事件处理程序接收photoBrowser实例
photoBrowserOpenedapp
closephotoBrowser当Photo Browser开始其关闭动画时,将触发事件。作为参数,事件处理程序接收photoBrowser实例
photoBrowserCloseapp
closedphotoBrowser当Photo Browser完成其关闭动画后,将触发事件。作为参数,事件处理程序接收photoBrowser实例
photoBrowserClosedapp
beforeDestroyphotoBrowser在Photo Browser实例将被销毁之前,将触发事件。作为参数,事件处理程序接收photoBrowser实例
photoBrowserBeforeDestroyapp

CSS 变量

以下是相关CSS 变量(CSS 自定义属性) 的列表。

:root {
  --f7-photobrowser-bg-color: #fff;
  --f7-photobrowser-bars-bg-color: rgba(var(--f7-bars-bg-color-rgb), 0.95);
  --f7-photobrowser-bars-text-color: var(--f7-bars-text-color);
  --f7-photobrowser-bars-link-color: var(--f7-bars-link-color);
  --f7-photobrowser-caption-font-size: 13px;
  --f7-photobrowser-caption-font-weight: 500;
  --f7-photobrowser-caption-light-text-color: #000;
  --f7-photobrowser-caption-dark-text-color: #fff;
  --f7-photobrowser-exposed-bg-color: #000;
  --f7-photobrowser-dark-bg-color: #000;
  --f7-photobrowser-dark-bars-bg-color: rgba(27, 27, 27, 0.8);
  --f7-photobrowser-dark-bars-text-color: #fff;
  --f7-photobrowser-dark-bars-link-color: #fff;
}

示例

photo-browser.html
<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner sliding">
        <div class="title">Photo Browser</div>
      </div>
    </div>
    <div class="page-content">
      <div class="block block-strong-ios block-outline-ios">
        <p>Photo Browser is a standalone and highly configurable component that allows to open window with photo viewer
          and navigation elements with the following features:</p>
        <ul>
          <li>Swiper between photos</li>
          <li>Multi-gestures support for zooming</li>
          <li>Toggle zoom by double tap on photo</li>
          <li>Single click on photo to toggle Exposition mode</li>
        </ul>
      </div>
      <div class="block block-strong-ios block-outline-ios">
        <p>Photo Browser could be opened in a three ways - as a Standalone component (Popup modification), in Popup, and
          as separate Page:</p>
        <div class="grid grid-cols-3 grid-gap">
          <a class="button button-fill" @click=${openStandalone}>Standalone</a>
          <a class="button button-fill" @click=${openPopup}>Popup</a>
          <a class="button button-fill" @click=${openPage}>Page</a>
        </div>
      </div>
      <div class="block block-strong-ios block-outline-ios">
        <p>Photo Browser supports 2 default themes - default Light (like in previous examples) and Dark theme. Here is a
          Dark theme examples:</p>
        <div class="grid grid-cols-3 grid-gap">
          <a class="button button-fill" @click=${openStandaloneDark}>Standalone</a>
          <a class="button button-fill" @click=${openPopupDark}>Popup</a>
          <a class="button button-fill" @click=${openPageDark}>Page</a>
        </div>
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $f7, $on }) => {
    const photos = [
      {
        url: 'img/beach.jpg',
        caption: 'Amazing beach in Goa, India'
      },
      'http://placekitten.com/1024/1024',
      'img/lock.jpg',
      {
        url: 'img/monkey.jpg',
        caption: 'I met this monkey in Chinese mountains'
      },
      {
        url: 'img/mountains.jpg',
        caption: 'Beautiful mountains in Zhangjiajie, China'
      }
    ];
    const thumbs = [
      'img/beach.jpg',
      'http://placekitten.com/1024/1024',
      'img/lock.jpg',
      'img/monkey.jpg',
      'img/mountains.jpg'
    ]

    let standalone;
    let popup;
    let page;
    let standaloneDark;
    let popupDark;
    let pageDark;

    const openStandalone = () => {
      standalone.open();
    }
    const openPopup = () => {
      popup.open();
    }
    const openPage = () => {
      page.open();
    }
    const openStandaloneDark = () => {
      standaloneDark.open();
    }
    const openPopupDark = () => {
      popupDark.open();
    }
    const openPageDark = () => {
      pageDark.open();
    }
    $on('pageInit', () => {
      // Create PBs when page init
      standalone = $f7.photoBrowser.create({
        photos: photos,
        thumbs: thumbs,
      });
      popup = $f7.photoBrowser.create({
        photos: photos,
        thumbs: thumbs,
        type: 'popup',
      });
      page = $f7.photoBrowser.create({
        photos: photos,
        thumbs: thumbs,
        type: 'page',
        backLinkText: 'Back',
      });
      standaloneDark = $f7.photoBrowser.create({
        photos: photos,
        thumbs: thumbs,
        theme: 'dark',
      });
      popupDark = $f7.photoBrowser.create({
        photos: photos,
        thumbs: thumbs,
        type: 'popup',
        theme: 'dark',
      });
      pageDark = $f7.photoBrowser.create({
        photos: photos,
        thumbs: thumbs,
        type: 'page',
        backLinkText: 'Back',
        theme: 'dark',
      });
    });
    $on('pageBeforeRemove', () => {
      // Destroy PBs on page remove
      standalone.destroy();
      popup.destroy();
      page.destroy();
      standaloneDark.destroy();
      popupDark.destroy();
      pageDark.destroy();
    });

    return $render;
  };
</script>