AMP

amp-lightbox

 
You can now use this component outside valid AMP documents using the Bento version of this component. Learn more in the Bento guide.

Description

以完整视口“灯箱”模式显示元素。

 

Required Scripts

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

Supported Layouts

说明 以完整视口“灯箱”模式显示元素。
必需的脚本 <script async custom-element="amp-lightbox" src="https://cdn.ampproject.org/v0/amp-lightbox-0.1.js"></script>
支持的布局 nodisplay
示例 请参阅 AMP By Example 的 amp-lightbox 示例。

行为

amp-lightbox 组件可定义以完整视口叠加层/模式显示的子元素。当用户点按或点击某个元素(例如按钮)时,所点击元素的 on 属性中引用的 amp-lightbox ID 会触发灯箱占据整个视口并显示 amp-lightbox 的子元素。

按键盘上的 Esc 键可关闭灯箱。或者,在灯箱中的一个或多个元素上设置 on 属性并将其方法设为 close,即可在用户点按或点击元素后关闭灯箱。

<button on="tap:quote-lb">See Quote</button>
<amp-lightbox id="quote-lb" layout="nodisplay">
  <blockquote>"Don't talk to me about JavaScript fatigue" - Horse JS</blockquote>
  <button on="tap:quote-lb.close">Nice!</button>
</amp-lightbox>

要在灯箱中显示图片,还可使用 <amp-image-lightbox> 组件。

属性

animate-in(可选) 定义打开灯箱的动画样式。默认情况下,该属性将设为 fade-in。有效值为 fade-infly-in-bottomfly-in-top

注意fly-in-* 动画预设会修改 amp-lightbox 元素的 transform 属性。切勿依赖于直接转换 amp-lightbox 元素。如果您需要应用转换,请改为在嵌套元素上进行设置。
close-button(在 AMPHTML 广告中,为必需属性) 在灯箱顶部呈现关闭按钮标头。只有对于 AMPHTML 广告,才需要使用此属性,并且此属性仅适用于此类广告。
id(必需) 灯箱的专属标识符。
layout(必需) 必须设为 nodisplay
scrollable(可选) scrollable 属性存在时,灯箱内容可在溢出灯箱高度时滚动。

注意:在 AMPHTML 广告中使用 <amp-lightbox> 时,不允许使用 scrollable 属性。如需了解详情,请参阅在 AMPHTML 广告中使用 amp-lightbox 部分。
scrollable(可选)

样式设置

可以使用标准 CSS 对 amp-lightbox 进行样式设置。

操作

amp-lightbox 提供以下操作,它们可以使用 AMP on 语法触发

操作 说明
open(默认) 打开灯箱。
close 关闭灯箱。

在 AMPHTML 广告中使用 amp-lightbox

用于 AMPHTML 广告的 amp-lightbox 组件是实验性组件,仍处于积极开发阶段。要在 AMPHTML 广告中使用 amp-lightbox,请启用 amp-lightbox-a4a-proto 实验

在常规 AMP 文档与在用 AMPHTML 编写的广告中使用 amp-lightbox 存在一些差异:

需要使用 close-button

对于 AMPHTML 广告,close-button 为必需的属性。此属性会导致标头呈现在灯箱顶部。标头包含关闭按钮和显示“Ad”的标签。需要使用此标头才能执行以下操作:

  • 为 AMPHTML 广告打造一致且可预测的用户体验。
  • 确保灯箱的退出点始终存在,否则广告素材可能会通过灯箱高效拦截主文档内容。

对于 AMPHTML 广告,close-button 为必需的属性,且此属性只能在 AMPHTML 广告中使用。在常规 AMP 文档中,您可以在任意需要的位置呈现关闭按钮(作为 <amp-lightbox> 内容的一部分)。

不允许使用可滚动的灯箱

AMPHTML 广告不允许使用可滚动的灯箱。

透明背景

在 AMPHTML 广告中使用 <amp-lightbox> 时,<body> 元素的背景将变为透明,这是因为 AMP runtime 会在灯箱展开之前调整广告素材内容的大小和对齐方式。这样做是为了防止广告素材在灯箱打开时发生视觉“跳转”。如果您的广告素材需要背景,请在中间容器(例如完整尺寸的 <div>)而非 <body> 上进行设置。

当 AMPHTML 广告在第三方环境(例如,非 AMP 文档)中运行时,广告素材相对于视口居中,然后展开。这是因为第三方 iframe 需要依赖 postMessage API 来启用帧大小调整(异步调整)等功能,因此,先使广告素材居中可在不发生视觉跳转的情况下平稳转换。

AMPHTML 广告的灯箱转换示例

在下面的示例中,我们展示了灯箱元素上设置了 animate-in="fly-in-bottom" 属性的 AMPHTML 广告在友好型 iframe 以及在第三方 iframe 中的转换效果。

在友好型 iframe 中(例如来自 AMP 缓存)


在第三方 iframe 中(例如在 AMP 缓存之外)


验证

请参阅 AMP 验证工具规范中的 amp-lightbox 规则

需要更多帮助?

您已多次阅读本文档,但它仍未能涵盖您的所有问题?也许其他人也这么觉得:在 Stack Overflow 上与他们联系。

前往 Stack Overflow
发现错误或缺少功能?

AMP 项目强烈鼓励您参与并做出贡献!我们希望您能成为我们开放源代码社区的持续参与者,但我们也欢迎您对所热衷问题做出一次性贡献。

前往 GitHub