跳到主要内容

文档

Lightbox

创建包含图片和视频的响应式灯箱画廊。

灯箱（Lightbox）组件完全响应式，支持触摸和滑动导航，在桌面端还支持鼠标拖拽。在幻灯片之间滑动时，动画会紧贴你的指尖或鼠标指针。快速点击上一张和下一张导航时，动画甚至会加速以跟上你的节奏。所有动画都经过硬件加速，性能更流畅。

用法

要应用该组件，请为容器添加 uk-lightbox 属性，这样容器内所有锚点都会变成灯箱链接。

<div uk-lightbox>
    <a href="image.jpg"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg">Open Lightbox</a>
</div>

Alt 属性

要为灯箱中的图片添加 alt 属性，请在锚点上设置 data-alt 属性。

<div uk-lightbox>
    <a href="image.jpg" data-alt="Image"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-alt="Image">Open Lightbox</a>
</div>

说明文字

要在灯箱底部显示说明文字，请在锚点上设置 data-caption 属性。

<div uk-lightbox>
    <a href="image.jpg" data-caption="Caption"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Caption">Open Lightbox</a>
</div>

注意 说明文字会以 HTML 渲染。内容清理（sanitization）是开发者的责任。

动画

默认情况下，灯箱画廊使用滑动动画。你可以设置 animation 选项来使用其他动画。可选值为 slide、fade 和 scale。

<div uk-lightbox="animation: fade">
    <a href="image.jpg"></a>
</div>
Slide
Fade
Scale
<div class="uk-h3">Slide</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="animation: slide">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

<div class="uk-h3">Fade</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="animation: fade">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

<div class="uk-h3">Scale</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="animation: scale">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

导航

默认情况下，灯箱会显示 Slidenav 组件的幻灯片导航。要隐藏该导航，请设置 slidenav: false 选项。要显示基于项目的导航，例如 Thumbnav 组件或 Dotnav 组件，请把 nav 选项设为 thumbnav 或 dotnav。

<div uk-lightbox="slidenav: false; nav: thumbnav">
    <a href="image.jpg"></a>
</div>
Thumbnav
Dotnav
<div class="uk-h3">Thumbnav</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="nav: thumbnav; slidenav: false">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

<div class="uk-h3">Dotnav</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="nav: dotnav; slidenav: false">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

计数器

要显示包含当前项目序号和项目总数的计数器，请添加 counter: true 选项。

<div uk-lightbox="counter: true">
    <a href="image.jpg"></a>
</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="counter: true">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

颜色模式

为了根据灯箱内容调整覆盖在内容上的控件颜色以获得更好的可见性，请使用 data-attrs 选项添加 Inverse 组件的 .uk-inverse-light 或 .uk-inverse.dark 类。

<div uk-lightbox>
    <a href="image.jpg" data-attrs="class: uk-inverse-light"></a>
</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="nav: thumbnav; slidenav: false">
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2" data-attrs="class: uk-inverse-light">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3" data-attrs="class: uk-inverse-dark">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

内容来源

灯箱并不局限于图片。其他媒体（例如视频）也可以显示。视频在不可见时会暂停，重新可见后会继续播放。要为视频显示封面图，请设置 data-poster 属性。

<div uk-lightbox>
    <a class="uk-button" href="video.mp4" data-poster="image.jpg"></a>
    <a class="uk-button" href="https://www.youtube.com/watch?v=c2pz2mlSfXA"></a>
    <a class="uk-button" href="https://vimeo.com/1084537"></a>
    <a class="uk-button" href="https://www.google.com/maps"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Image">Image</a>
    <a class="uk-button uk-button-default" href="https://yootheme.com/media/videos/yootheme-pro.mp4" data-caption="Video">Video</a>
    <a class="uk-button uk-button-default" href="https://www.youtube.com/watch?v=c2pz2mlSfXA" data-caption="YouTube">YouTube</a>
    <a class="uk-button uk-button-default" href="https://vimeo.com/1084537" data-caption="Vimeo">Vimeo</a>
    <a class="uk-button uk-button-default" href="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d4740.819266853735!2d9.99008871708242!3d53.550454675412404!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x0%3A0x3f9d24afe84a0263!2sRathaus!5e0!3m2!1sde!2sde!4v1499675200938" data-caption="Google Maps" data-type="iframe">Google Maps</a>
</div>

注意 在 YouTube 链接中使用 youtube-nocookie.com，灯箱会使用该域名来嵌入 YouTube 视频。

手动指定内容类型

灯箱通过 href 属性来判断所链接内容的类型。如果路径中没有定义文件扩展名，只需为 <a> 标签添加 data-type 属性。

提示 YouTube 和 Vimeo 的 URL 会被自动处理。

选项 说明
data-type="image" 内容类型为图片。
data-type="video" 内容类型为视频。
data-type="iframe" 内容类型为普通网站。

延迟隐藏控件

默认情况下，如果鼠标不移动，控件会在一小段时间后隐藏。设置 delay-controls: 0 选项可让控件始终显示。

<div uk-lightbox="delay-controls: 0">
    <a href="image.jpg"></a>
</div>
<div uk-lightbox="delay-controls: 0">
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Caption">Open Lightbox</a>
</div>

点击背景关闭

默认情况下，点击背景会关闭灯箱。要阻止这一行为，请设置 bg-close: false 选项。

<div uk-lightbox="bg-close: false">
    <a href="image.jpg"></a>
</div>
<div uk-lightbox="bg-close: false">
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Caption">Open Lightbox</a>
</div>

自定义属性

你可以使用 data-attrs 属性为灯箱内容项添加自定义属性。属性的传递方式与通常的组件选项相同，例如 data-attrs="width: 1280; height: 720;"

<div uk-lightbox>
    <a class="uk-button" href="https://www.youtube.com/watch?v=c2pz2mlSfXA" data-attrs="width: 1280; height: 720;"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="https://www.youtube.com/watch?v=c2pz2mlSfXA" data-caption="YouTube" data-attrs="width: 1280; height: 720;">YouTube</a>
</div>

自定义模板

这是默认的灯箱模板。

<div class="uk-lightbox uk-overflow-hidden">
    <div class="uk-lightbox-items"></div>
    <div class="uk-position-top-right uk-position-small uk-transition-fade" uk-inverse>
        <button class="uk-lightbox-close uk-close-large" type="button" uk-close></button>
    </div>
    <div class="uk-position-center-left uk-position-medium uk-transition-fade" uk-inverse>
        <a class="uk-lightbox-slidenav" href uk-slidenav-previous uk-lightbox-item="previous"></a>
    </div>
    <div class="uk-position-center-right uk-position-medium uk-transition-fade" uk-inverse>
        <a class="uk-lightbox-slidenav" href uk-slidenav-next uk-lightbox-item="next"></a>
    </div>
    <div class="uk-position-center-right uk-position-medium" uk-inverse uk-toggle="cls: uk-position-center-right uk-position-bottom-center; mode: media; media: @s">
        <ul class="uk-lightbox-thumbnav uk-thumbnav uk-thumbnav-vertical" uk-toggle="cls: uk-thumbnav-vertical; mode: media; media: @s"></ul>
        <ul class="uk-lightbox-dotnav uk-dotnav uk-dotnav-vertical" uk-toggle="cls: uk-dotnav-vertical; mode: media; media: @s"></ul>
    </div>
    <div class="uk-lightbox-counter uk-text-large uk-position-top-left uk-position-small uk-transition-fade" uk-inverse></div>
    <div class="uk-lightbox-caption uk-position-bottom uk-text-center uk-transition-slide-bottom uk-transition-opaque"></div>
</div>

要覆盖默认的灯箱模板，请添加 template: #ID 选项，把它链接到一个带有新灯箱布局的 template 元素。

<template id="js-lightbox-template">…</template>

<div uk-lightbox="template: #js-lightbox-template">…</div>
<template id="js-lightbox-template">
    <div class="uk-lightbox uk-overflow-hidden">
        <div class="uk-lightbox-items"></div>
        <div class="uk-position-top-right uk-position-small uk-transition-fade" uk-inverse>
            <button class="uk-lightbox-close uk-close-large" type="button" uk-close></button>
        </div>
        <div class="uk-position-bottom uk-position-medium uk-text-center uk-transition-fade" uk-inverse>
            <div class="uk-grid-small uk-width-auto uk-flex-inline uk-flex-middle" uk-grid>
                <div><a class="uk-lightbox-slidenav" href uk-slidenav-previous uk-lightbox-item="previous"></a></div>
                <div><div class="uk-lightbox-counter"></div></div>
                <div><a class="uk-lightbox-slidenav" href uk-slidenav-next uk-lightbox-item="next"></a></div>
            </div>
        </div>
    </div>
</template>

<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="template: #js-lightbox-template; counter: true">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

组件选项

这些选项都可以应用到组件属性上。多个选项之间用分号分隔。了解更多

选项 值 默认值 说明
animation String slide 灯箱动画模式（slide、fade 或 scale）。
autoplay Boolean false 灯箱自动播放。
autoplay-interval Number 7000 自动播放模式下切换幻灯片之间的延迟。
pause-on-hover Boolean false 悬停时暂停自动播放。
video-autoplay Boolean, String false 灯箱视频自动播放。值为 inline 时会自动播放视频，并使其静音且不显示控件。
counter Boolean false 灯箱显示计数器。
nav Boolean, String false 灯箱导航（dotnav、thumbnav）。
slidenav Boolean true 灯箱显示幻灯片导航控件。
index String, Number 0 要显示的灯箱项目。索引从 0 开始。
delay-controls Number 3000 控件淡出前的延迟时间，单位毫秒。设为 0 可防止控件隐藏。
toggle CSS selector a 切换选择器——点击时打开灯箱面板。

JavaScript

了解更多关于 JavaScript 组件的内容。

初始化

// To apply lightbox to a group of links
UIkit.lightbox(element, options);

// To dynamically initialize the lightbox panel
UIkit.lightboxPanel(panelOptions);

方法

该组件提供以下方法：

Show

UIkit.lightbox(element).show(index);

显示灯箱面板及其项目。

Hide

UIkit.lightbox(element).hide();

隐藏灯箱面板。

灯箱面板选项

如果你只想通过 JS API 直接使用灯箱面板，可以设置以下选项。

选项 值 默认值 说明
animation String slide 灯箱动画模式（slide、fade 或 scale）。
autoplay Boolean false 灯箱自动播放。
autoplay-interval Number 7000 自动播放模式下切换幻灯片之间的延迟。
pause-on-hover Boolean false 悬停时暂停自动播放。
video-autoplay Boolean, String false 灯箱视频自动播放。值为 inline 时会自动播放视频，并使其静音且不显示控件。
counter Boolean false 灯箱显示计数器。
nav Boolean, String false 灯箱导航（dotnav、thumbnav）。
slidenav Boolean true 灯箱显示幻灯片导航控件。
index Number 0 初始显示的项目。（从 0 开始）
velocity Number 2 动画速度（像素/毫秒）。
preload Number 1 预加载的项目数量。（当前激活项目的左右两侧）
items Array [] 要显示的项目数组，例如 [{source: 'images/size1.jpg', caption: '900x600'}]
template String Default markup 模板字符串。
delay-controls Number 3000 控件淡出前的延迟时间，单位毫秒。设为 0 可防止控件隐藏。
container String body 通过选择器定义目标容器，以指定灯箱应追加到 DOM 中的位置。

事件

以下事件会在绑定了该组件的元素上触发：

名称 说明
beforeshow 灯箱显示之前触发。
beforehide 灯箱隐藏之前触发。
show 灯箱显示之后触发。
shown 灯箱的显示动画完成之后触发。
hide 灯箱的隐藏动画开始之后触发。
hidden 灯箱隐藏之后触发。
itemload 项目加载时触发。
beforeitemshow 项目显示之前触发。
itemshow 项目显示之后触发。
itemshown 项目的显示动画完成之后触发。
beforeitemhide 项目隐藏之前触发。
itemhide 项目的隐藏动画开始之后触发。
itemhidden 项目的隐藏动画完成之后触发。

方法

该组件提供以下方法：

Show

UIkit.lightboxPanel(element).show(index);

显示灯箱面板及其项目。

名称 类型 默认值 说明
index String, Number 0 要显示的灯箱项目。索引从 0 开始。

Hide

UIkit.lightboxPanel(element).hide();

隐藏灯箱面板。

startAutoplay

UIkit.lightboxPanel(element).startAutoplay();

启动灯箱的自动播放。

stopAutoplay

UIkit.lightboxPanel(element).stopAutoplay();

停止灯箱的自动播放。

可访问性

Lightbox 组件遵循 Dialog（Modal）的 WAI-ARIA 设计模式和轮播的 WAI-ARIA 设计模式，并会自动设置恰当的 WAI-ARIA 角色、状态和属性。

上一页/下一页导航遵循按钮模式。

Close 组件会自动设置恰当的 WAI-ARIA 角色和属性。

键盘交互

可以通过以下按键从键盘访问灯箱画廊。

国际化

灯箱组件使用以下翻译字符串。了解更多关于翻译组件的内容。

Key 默认值 说明
next Next Slide 下一张幻灯片按钮的 aria-label。
previous Previous Slide 上一张幻灯片按钮的 aria-label。
slideLabel %s of %s 幻灯片的 aria-label。
close Close 关闭按钮的 aria-label。