图片浏览器

图片浏览器是一个可以展示照片/图片集合的照片浏览器组件。可以缩放和平移照片(可选)。

图片浏览器使用Swiper 幻灯片组件在照片之间滑动。

图片浏览器应用方法

让我们看看相关的应用方法来使用图片浏览器

app.photoBrowser.create(parameters)- 创建图片浏览器实例

  • parameters - object 图片浏览器参数对象

方法返回创建的图片浏览器的实例

app.photoBrowser.destroy(el)- 销毁图片浏览器实例

  • el - HTMLElementstring (带 CSS 选择器) 或 object 图片浏览器元素或要销毁的图片浏览器实例

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

  • el - HTMLElementstring (带 CSS 选择器) 图片浏览器元素

方法返回图片浏览器的实例

例如

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

图片浏览器参数

让我们看看所有可用图片浏览器参数的列表

参数类型默认值描述
photos数组[]包含照片 URL 的数组或包含 "url"(或 "html")和 "caption" 属性的对象的数组
thumbs数组[]包含缩略图图像 URL 的数组,如果没有指定或空数组,将不会呈现缩略图
exposition布尔值true单击图片浏览器时启用禁用曝光模式
expositionHideCaptions布尔值false如果您还希望在曝光模式下隐藏标题,则设置为 true
swipeToClose布尔值true启用此参数后,可以通过向上/向下滑动关闭图片浏览器
popupPush布尔值false在打开时启用图片浏览器弹出窗口来推动后面的视图
routableModals布尔值false将打开的图片浏览器添加到路由历史记录中,这提供了通过回到路由历史记录关闭图片浏览器的能力,并将当前路由设置为图片浏览器模态。
url字符串photos/图片浏览器模态 URL,将被设置为当前路由
view对象如果要使用 "page" 图片浏览器类型或在启用 routableModals 时设置路由,则链接到已初始化的视图实例,默认情况下,如果未指定,它将在主视图中打开。
type字符串standalone定义如何打开图片浏览器,可以是 standalone(将作为带自定义过渡效果的覆盖层打开)、popup(将作为 弹出窗口 打开)、page(将注入到视图并作为新页面加载)
theme字符串light图片浏览器配色主题,可以是 lightdark
captionsTheme字符串标题配色主题,也可以是 lightdark,默认情况下等于 theme 参数
navbar布尔值true设置为 false 以移除图片浏览器的导航栏
toolbar布尔值true设置为 false 以移除图片浏览器的工具栏
pageBackLinkText字符串返回图片浏览器导航栏的后退链接上的文本
popupCloseLinkText字符串关闭弹出窗口或独立模式下,照片浏览器导航栏中关闭链接上的文本
navbarShowCount布尔值未定义定义是否在导航栏标题中显示“5 中的 3”文本。如果未指定(未定义),则当项目多于 1 个时会显示该文本
navbarOfText字符串'of'照片计数器中“of”的文本:“5 中的 3”
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 字符串
renderCaptionfunction(caption, index)呈现单个标题的函数,必须返回标题 HTML 字符串
renderObjectfunction(photo, index)呈现照片对象的函数,必须返回照片对象 HTML 字符串
renderLazyPhotofunction(photo, index)呈现延迟加载照片幻灯片的函数,必须返回幻灯片 HTML 字符串
renderPhotofunction(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>'
];

照片浏览器方法和属性

在初始化照片浏览器后,我们会在变量中(如上面的示例中的 photoBrowser 变量)有其初始化的实例,其中包含有用的方法和属性

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

照片浏览器事件

照片浏览器将在照片浏览器元素上触发以下 DOM 事件,以及在应用程序和照片浏览器实例上触发事件

DOM 事件

事件目标描述
photobrowser:open照片浏览器元素当照片浏览器开始打开动画时,将触发事件
photobrowser:opened照片浏览器元素当照片浏览器完成打开动画后,将触发事件
photobrowser:close照片浏览器元素当照片浏览器开始关闭动画时,将触发事件
photobrowser:closed照片浏览器元素当照片浏览器完成关闭动画后,将触发事件
photobrowser:beforedestroy照片浏览器元素当照片浏览器实例即将被销毁时,将触发事件

应用程序和照片浏览器实例事件

照片浏览器实例在自身实例和应用程序实例中发出事件。应用程序实例事件具有相同名称,前缀为 photoBrowser

事件目标描述
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' 作为参数事件。
openphotoBrowser当 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>