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

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

用法

<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。

内联配置

通过将其放置在子 <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 版本迁移

amp-next-page 的实验性 0.1 版本具有类似但更受限制的 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 请求规范中指定的要求。

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

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 用于链接文本

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

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

.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