AMP
KO
English Deutsch Français العربية Español Italiano Indonesia 日本語 Português Русский Türkçe 中文

amp-lightbox-gallery

Description

Provides a "lightbox” experience. Upon user interaction, a UI component expands to fill the viewport until it is closed by the user.

Required Scripts

<script async custom-element="amp-lightbox-gallery" src="https://cdn.ampproject.org/v0/amp-lightbox-gallery-0.1.js"></script>

Overview

The amp-lightbox-gallery component provides a "lightbox” experience for AMP components (e.g., amp-img, amp-carousel). When the user interacts with the AMP element, a UI component expands to fill the viewport until it is closed by the user. Currently, only images are supported.

Usage

To use amp-lightbox-gallery, ensure the required script is included in your <head> section, then add the lightbox attribute on an <amp-img> or <amp-carousel> element. A typical usage looks like this:

<amp-img src="cat.jpg" width="100" height="100" lightbox></amp-img>
<amp-img src="dog.jpg" width="100" height="100" lightbox></amp-img>
<amp-img src="bird.jpg" width="100" height="100" lightbox></amp-img>

Tapping on any <amp-img> opens the image in a lightbox gallery. The lightbox gallery does image-handling (e.g., zoom and pan), enables swiping to navigate between images, and offers a thumbnail gallery view for browsing all picture thumbnails in a grid.

<amp-carousel
  lightbox
  width="1600"
  height="900"
  layout="responsive"
  type="slides"
>
  <amp-img src="image1" width="200" height="100"></amp-img>
  <amp-img src="image1" width="200" height="100"></amp-img>
  <amp-img src="image1" width="200" height="100"></amp-img>
</amp-carousel>

You can add the lightbox attribute on an <amp-carousel> to lightbox all of its children. Currently, the <amp-lightbox-gallery> component only supports carousels containing <amp-img> as children. As you navigate through the carousel items in the lightbox, the original carousel slides are synchronized so that when the lightbox is closed, the user ends up on the same slide as the were originally on. Currently, only the type='slides' carousel is supported.

Captions

Optionally, you can specify a caption for each element in the lightbox. These fields are automatically read and displayed by the <amp-lightbox-gallery> in the following order of priority:

  • figcaption (if the lightboxed element is the child of a figure)
  • aria-describedby
  • alt
  • aria-label
  • aria-labelledby

Example 1: Using figcaption for description

In this example, <amp-lightbox-gallery> displays the figcaption value as its description, showing "Toront's CN tower was ....".

<figure>
  <amp-img
    id="hero-img"
    lightbox="toronto"
    src="https://picsum.photos/1600/900?image=1075"
    layout="responsive"
    width="1600"
    height="900"
    alt="Picture of CN tower."
  >
  </amp-img>
  <figcaption class="image">
    Toronto's CN tower was built in 1976 and was the tallest free-standing
    structure until 2007.
  </figcaption>
</figure>

Example 2: Using alt for description

In this example, <amp-lightbox-gallery> displays the alt value as its description, showing "Picture of CN tower".

<amp-img
  id="hero-img"
  lightbox="toronto"
  src="https://picsum.photos/1600/900?image=1075"
  layout="responsive"
  width="1600"
  height="900"
  alt="Picture of CN tower"
>
</amp-img>

Thumbnail API

Lightboxed items have a thumbnail gallery view. You can optionally specify a thumbnail item for your lightboxed element via the attribute lightbox-thumbnail-id that references the id of an <amp-img> element with layout="nodisplay".

Example: using lightbox-thumbnail-id to specify a thumbnail

<amp-youtube
  width="480"
  height="270"
  layout="responsive"
  data-videoid="lBTCB7yLs8Y"
  lightbox-thumbnail-id="my-thumbnail-img"
>
</amp-youtube>

<amp-img
  id="my-thumbnail-img"
  width="200"
  height="200"
  layout="nodisplay"
  src="https://picsum.photos/200/200?image=1074"
>
</amp-img>

If no thumbnail is specified, <amp-img> elements will be cropped per object-fit: cover, <amp-video> will use the image src specified in its poster attribute, and placeholder images will be used for lightboxed elements that have one.

Analytics events

To track usage of amp-lightbox-gallery, please use one of the following analytics events:

lightboxOpened

This event tracks when the lightbox is opened when the user clicks on a lightboxed <amp-img>.

You can track this event using the following code snippet:

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "open": "https://foo.com/open"
      },
      "triggers": {
        "trackLightboxOpened": {
          "on": "lightboxOpened",
          "request": "open"
        }
      }
    }
  </script>
</amp-analytics>

thumbnailsViewToggled

This event tracks when the thumbnails view is triggered by clicking on the trigger when the user is in the lightbox view.

You can track this event using the following code snippet:

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "thumb": "https://foo.com/thumb"
      },
      "triggers": {
        "trackThumbnailsViewToggled": {
          "on": "thumbnailsViewToggled",
          "request": "thumb"
        }
      }
    }
  </script>
</amp-analytics>

descriptionOverflowToggled

This event tracks when the user toggles the description by clicking on the description to expand/collapse it, tracking engagement with the description for the lightboxed image.

You can track this event using the following code snippet:

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "descOverflow": "https://foo.com/descOverflow"
      },
      "triggers": {
        "trackDescriptionOverflowed": {
          "on": "descriptionOverflowToggled",
          "request": "descOverflow"
        }
      }
    }
  </script>
</amp-analytics>
도움이 더 필요하신가요?

이 문서를 수십 번 읽었음에도 여전히 궁금한 점이 남아 있나요? 다른 개발자들도 같은 심정일지 모릅니다. Stack Overflow에서 소통해 보세요.

Stack Overflow로 이동
버그나 누락된 기능을 발견하셨나요?

AMP 프로젝트는 여러분의 참여와 기여를 적극 환영합니다! 오픈 소스 커뮤니티를 통해 지속적으로 활동해 주셔도 좋지만 관심 있는 주제에 한 번만 기여하셔도 큰 도움이 됩니다.

GitHub로 이동하기