AMP

重要提示:此文档不适用于您当前选择的格式广告

amp-next-page

描述

用于文档级页面推荐的无限滚动体验。

 

必需脚本

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

用法

<amp-next-page> 组件一个接一个地加载内容页面,从而创建无限滚动体验。

配置和加载页面

在 JSON 配置中指定页面。使用 src 属性从远程 URL 加载 JSON 配置,或将其内联在 <amp-next-page><script> 子元素中。您可以同时指定远程 URL 和内联 JSON 对象,以加快建议加载速度。

文档作为 <amp-next-page> 元素的子元素追加到当前文档的末尾。为了防止页面内容向下移动,此组件必须是文档 <body> 的最后一个子元素。如果需要,任何页脚内容都应嵌入 <amp-next-page> 标记内(通过添加具有 footer 属性的容器),并且将在没有更多文章建议时显示。

下面的代码示例显示了一个文章的示例配置,该格式与内联和远程配置使用的格式相同

{
  "image": "https://example.com/image.jpg",
  "title": "This article shows next",
  "url": "https://example.com/article.amp.html"
}

每个页面对象必须具有以下键/值对

url 页面的字符串 URL。必须与当前文档位于同一来源。必要时,URL 将自动重写为指向 Google AMP 缓存。
title 页面的字符串标题,将在呈现推荐框时使用。
image 要在推荐框中显示的图像的字符串 URL。

内联配置

通过将 JSON 配置放置在子 <script> 元素中,将 JSON 配置内联到 <amp-next-page> 组件中。

<amp-next-page>
  <script type="application/json">
    [
      {
        "url": ...,
        "title": ...,
        "image": ...
      },
      ...
    ]
  </script>
</amp-next-page>

当仅使用内联配置时,默认情况下启用 deep-parsing(请参阅属性部分)。这允许它通过递归查看加载文档中 <amp-next-page> 标记内的内联配置来解析更多建议。

文档按照它们在 JSON 配置中出现的顺序呈现。amp-next-page 将原始宿主文档的 <amp-next-page> 配置中定义的所有文档建议排队,然后在用户滚动浏览它们时将已呈现的页面定义文档追加到队列中。

以下配置建议用户阅读另外两个文档。

<amp-next-page>
  <script type="application/json">
    [
      {
        "image": "https://example.com/image1.jpg",
        "title": "This article shows first",
        "url": "https://example.com/article1.amp.html"
      },
      {
        "image": "https://example.com/image2.jpg",
        "title": "This article shows second",
        "url": "https://example.com/article2.amp.html"
      }
    ]
  </script>
</amp-next-page>

从远程 URL 加载配置

使用 src 属性指向远程 JSON 配置。

<amp-next-page src="https://example.com/next-page-config.json"></amp-next-page>

按照下面的示例构建远程配置。此配置提供了另外两个文档,并告诉 amp-next-page 在用户滚动浏览这两个文档后查询 https://example.com/more-pages

{
  "pages": [
    {
      "image": "https://example.com/image1.jpg",
      "title": "This article shows first",
      "url": "https://example.com/article1.amp.html"
    },
    {
      "image": "https://example.com/image2.jpg",
      "title": "This article shows second",
      "url": "https://example.com/article2.amp.html"
    }
  ],
  "next": "https://example.com/more-pages"
}

远程配置需要服务器返回一个具有 pages 键/值对的 JSON 对象,并允许可选的 next 键/值对。

pages 页面数组。该数组包含上面定义的所有页面对象定义。
next(可选) 指向下一个远程 JSON 配置的字符串 URL。这应遵守与初始 URL 相同的规则,并实现 CORS 要求。)
URL 替换

amp-next-page src 允许所有标准的 URL 变量替换。有关更多信息,请参阅 替换指南。例如

<amp-next-page src="https://foo.com/config.json?RANDOM"></amp-next-page>

此 URL 可能会向类似 https://foo.com/config.json?0.8390278471201 的地址发出请求,其中 RANDOM 值是在每次展示时随机生成的。

推荐框(更多建议链接)

如果出现以下情况之一,<amp-next-page> 组件会呈现推荐框

  • 用户在下一个页面加载之前到达页面末尾。
  • 下一个页面加载失败。
  • 如果指定了 max-pages 属性,并且已达到显示的页面数。

推荐框包含指向其余页面的链接。默认推荐框呈现 JSON 配置中指定的 imagetitle。可以按照 样式 部分中指定的样式进行设置。

自定义推荐框

通过在 <amp-next-page> 组件中定义具有 recommendation-box 属性的元素来自定义推荐框。通过使用 amp-mustache 或其他模板引擎来模板化推荐框,从而显示其余页面。使用模板时,会将剩余文档的数组 pages 传递给模板,其中包括 titleurlimage

<amp-next-page src="https://example.com/config.json">
  <div recommendation-box class="my-custom-recommendation-box">
    Here are a few more articles:
    <template type="amp-mustache">
      <div class="recommendation-box-content">
{{#pages}}        <span class="title">{{title}}</span>
        <span class="url">{{url}}</span>
        <span class="image">{{image}}</span>
{{/pages}}      </div>
    </template>
  </div>
</amp-next-page>

分隔符

<amp-next-page> 组件在每个文档之间呈现分隔符。默认分隔符是一条全宽的灰色线。请参阅样式部分以更改默认样式。

自定义分隔符

或者,可以通过在 <amp-next-page> 组件内定义具有 separator 属性的元素来创建自定义分隔符。通过使用 amp-mustache 或其他模板引擎来模板化自定义分隔符,从而显示有关下一篇文章的信息。使用模板时,会将即将发布的文章的 titleurlimage 传递给模板。

<amp-next-page src="https://example.com/config.json">
  <div separator class="my-custom-separator">
    <template type="amp-mustache">
      <div class="my-custom-separator-content">
        <amp-img
          src="{{image}}"
          layout="fixed"
          height="16"
          width="16"
        ></amp-img>
        <span>Next article: {{title}}</span>
      </div>
    </template>
  </div>
</amp-next-page>

防止页面元素重复

使用 next-page-hide 属性隐藏多个加载页面中常见的元素。隐藏某些元素有助于创建整洁的无限滚动体验。此类注意事项包括

  • 避免堆叠常见的页面元素,例如页脚。
  • 避免在后续页面中重复页面标题
  • 防止多个侧边栏等。

当作为 <amp-next-page> 内的建议加载时,具有 next-page-hide 属性的元素设置为 display: none。当文档作为顶级宿主加载时,这些元素可见。

<header class="my-header" next-page-hide>
  <h2>Text here.</h2>
</header>

在某些情况下,您可能需要保留具有固定位置和多个实例的元素的最后一个实例。此类元素可能包括粘性广告、粘性页脚或通知横幅。在这种情况下,next-page-replace 属性会派上用场。要保留最后一个实例,请为每种类型的元素选择一个通用的标识值。在每个元素实例上,将该通用标识值用作 next-page-replace 属性的值。

在以下示例中,当用户向下滚动时,第一个粘性元素将被该类型的第二个实例替换。

在第一个文档上

<div class="sticky" next-page-replace="sticky-123">
  <h2>The second sticky will replace me once you scroll past my page</h2>
</div>

在第二个文档上

<div class="sticky" next-page-replace="sticky-123">
  <h2>I replaced the first instance of my type (sticky-123)</h2>
</div>

由于 <amp-next-page> 应该是 body 的最后一个元素,因此页脚内容(应在显示所有文档后显示)必须位于 <amp-next-page> 内。添加一个具有 footer 属性的容器元素,并将您的内容作为其子元素。

<amp-next-page>
  <script type="application/json">
    ...
  </script>
  <div footer>
    My footer content here
  </div>
</amp-next-page>

从 0.1 版本迁移

amp-next-page 的实验性 0.1 版本具有类似但更受限的 API。1.0 版本允许无限数量的建议,并具有高级功能,例如模板化分隔符和推荐框。要使用这些功能,请按照以下说明操作

  1. 更新您的 <script custom-element> 标记以链接到 amp-next-page1.0
  2. 确保 amp-next-page 是 body 元素的最后一个子元素,将曾经位于 <amp-next-page> 之后的任何页脚或其他组件移入具有 footer 属性的 <amp-next-page> 标记内的容器中。
  3. 如果您使用的是内联配置,则 JSON 配置现在是一个页面数组,而不是具有 pages 条目的对象。此外,您必须将每个页面的 ampUrl 键重命名为 url
    <amp-next-page>
      <!-- BEFORE: amp-next-page 0.1 -->
      <script type="application/json">
        {
          "pages": [
            {
              "image": "https://example.com/image1.jpg",
              "title": "This article shows first",
              "ampUrl": "https://example.com/article1.amp.html"
            }
          ],
          "hideSelectors": [".header", ".main footer", "#navigation"]
        }
      </script>
      <!-- AFTER: amp-next-page 1.0 -->
      <script type="application/json">
        [
          {
            "image": "https://example.com/image1.jpg",
            "title": "This article shows first",
            // `ampUrl` was renamed to `url`
            "url": "https://example.com/article1.amp.html"
          }
        ]
        // Instead of `hideSelectors`, use the `next-page-hide` attribute
      </script>
    </amp-next-page>

属性

src

src 属性指向返回 amp-next-page 的 JSON 配置的远程端点。这必须是 CORS HTTP 服务。URL 的协议必须是 HTTPS。

您的端点必须实现 AMP 中的 CORS 请求规范中指定的要求。

除非 <amp-next-page> 组件包含内联 JSON 配置,否则 src 属性是必需的属性。

max-pages(可选)

要加载并向用户显示的最大页面数。最大数量应小于页面总数。达到该数量后,<amp-next-page> 将显示推荐框。默认值为 Infinity

deep-parsing(可选)

deep-parsing 属性启用对后续加载的文档的 <amp-next-page> JSON 配置的递归解析。

<amp-next-page> 内联 JSON 配置时,这是默认行为。您可以通过设置 deep-parsing="false" 来禁用它。当 <amp-next-page> 指向远程 JSON 配置时,这不是默认行为。您可以通过设置 deep-parsing="true" 来启用它。

xssi-prefix(可选)

指定此属性后,amp-next-page 可以去除远程托管 JSON 解析之前的特定前缀。这对于包含 安全前缀(例如 )]})的 API 很有用,以帮助防止跨站点脚本攻击。

样式

<amp-next-page> 组件渲染一个默认的推荐框和分隔符。您可以按如下方式设置这两个元素的外观样式

设置默认推荐框的样式

您可以向默认的推荐框添加自定义 CSS 样式。它公开以下类

  • .amp-next-page-links,用于父容器元素
  • .amp-next-page-link,用于包含以下内容的单个文章
  • .amp-next-page-image,用于链接图像
  • .amp-next-page-text,用于链接文本

设置默认页面分隔符的样式

每个文档都加载一条全宽的灰色水平线,以将其与上一页分隔开。可以使用 CSS 和 .amp-next-page-separator 类来自定义默认分隔符

.amp-next-page-separator {
  background-color: red;
  height: 5px;
}

分析

<amp-next-page> 组件支持在托管页面以及后续加载的文章上进行分析。我们建议使用在独立文章上使用的相同分析触发器,包括基于滚动的触发器。

通过主机页面上的 <amp-pixel><amp-analytics> 支持跟踪页面浏览量。建议使用 <amp-analytics>useInitialPageSize 属性,以更准确地测量滚动触发器,否则只有在用户滚动经过所有子文档后,才会触发主机页面的 100% 触发点。请注意,这也将忽略其他扩展(例如展开嵌入式内容)引起的大小更改,因此某些滚动事件可能会过早触发。

主机页面上还提供了两个自定义分析事件,以指示页面之间的过渡。可以在 amp-analytics 配置中按如下方式跟踪这些事件

事件 触发时机
amp-next-page-scroll 用户滚动到新页面。
amp-next-page-click 用户单击推荐框中的文章。

这两个 <amp-next-page> 特定的触发器都提供变量 urltitletitleurl 指的是滚动到的页面或单击的文章。以下代码示例演示了它们的用法

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "nextpage": "https://foo.com/pixel?RANDOM&toURL=${toURL}"
      },
      "triggers": {
        "trackScrollThrough": {
          "on": "amp-next-page-scroll",
          "request": "nextpage"
        },
        "trackClickThrough": {
          "on": "amp-next-page-click",
          "request": "nextpage"
        }
      }
    }
  </script>
</amp-analytics>

辅助功能

默认推荐框和默认分隔符都具有通用的、非本地化的 aria-label 来描述它们的内容。如果此标签不令人满意,请考虑使用自定义的推荐框或分隔符元素来提高可访问性。

默认推荐框和默认分隔符都是键盘可聚焦的。当提供自定义分隔符时,如果存在,则保留其 tabindex,否则将向给定元素添加 tabindex0

版本说明

版本 描述
1.0 支持无限数量的页面推荐、缩小捆绑包大小、改进的 API、支持 amp-analytics、模板化分隔符和推荐框、更好地处理固定元素。

API 更改具有破坏性,请查看 迁移部分了解详细信息。
0.1 初始实验性实现。仅限于三个推荐文档

验证

请参阅 AMP 验证器规范中的 amp-next-page 规则

需要更多帮助?

您已经阅读本文档十几次了,但它并没有真正涵盖您的所有问题?也许其他人也有同感:请在 Stack Overflow 上与他们联系。

转到 Stack Overflow
发现错误或缺少功能?

AMP 项目强烈鼓励您的参与和贡献!我们希望您能成为我们开源社区的长期参与者,但也欢迎您针对您特别关注的问题做出一次性贡献。

转到 GitHub