AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

重要提示：此文档不适用于您当前选择的格式 email！

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> 元素中，在 <amp-next-page> 组件中内联 JSON 配置。

<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 配置中指定的 image 和 title。可以按照样式部分中指定的方式设置其样式。

自定义推荐框

通过在 <amp-next-page> 组件内定义一个具有 recommendation-box 属性的元素来自定义推荐框。通过使用 amp-mustache 或其他模板引擎对推荐框进行模板化来显示剩余页面。使用模板时，剩余文档的数组 pages 将传递到模板，其中包括 title、url 和 image。

<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 或其他模板引擎对自定义分隔符进行模板化来显示有关下一篇文章的信息。使用模板时，即将到来的文章的 title、url 和 image 将传递到模板。

<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 版本迁移

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

  1. 更新您的 <script custom-element> 标记以链接到 amp-next-page 的 1.0 包
  2. 确保 amp-next-page 是 body 元素的最后一个子元素，将任何过去跟随 <amp-next-page> 的页脚或其他组件移动到 <amp-next-page> 标记内具有 footer 属性的容器内。
  3. 如果您使用的是内联配置，则 JSON 配置现在是页面 array 而不是具有 pages 条目的 object。此外，您必须将每个页面的 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> 特定触发器都提供变量 url 和 title。 title 和 url 指的是滚动到的页面或点击的文章。以下代码示例演示了它们的用法：

<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，否则将向给定元素添加 tabindex 为 0。

版本说明

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

API 更改是破坏性的，请查看 迁移部分 了解详细信息。
0.1 初始实验性实现。限制为三个推荐文档

验证

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

需要更多帮助？

您已经阅读此文档多次，但它并没有真正涵盖您的所有问题？也许其他人也有同样的感觉：在 Stack Overflow 上与他们联系。

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

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的长期参与者，但我们也欢迎您对特别感兴趣的问题进行一次性贡献。

转到 GitHub