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

nodisplay

示例

Lightbox Ad

说明	以完整视口“灯箱”模式显示元素。
必需的脚本	`<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-in`、`fly-in-bottom` 和 `fly-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

amp-lightbox 1.0 0.1