">文档：<amp-next-page> - amp.dev - AMP 框架
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"
}

远程配置要求服务器返回一个 JSON 对象，其中包含 pages 键/值对，并允许使用可选的 next 键/值对。

键 值
页面 页面数组。该数组包含如上所定义的所有页面对象定义。
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> 应该是正文的最后一个元素，因此页脚内容（应在显示所有文档后显示）必须位于 <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 是正文元素的最后一个子元素，将任何页脚或其他组件（过去在 <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，否则会向给定元素添加 tabindex 为 0。

版本说明

版本 说明
1.0 支持无限数量的页面推荐、减小的捆绑大小、改进的 API、支持 amp-analytics、模板分隔符和推荐框，以及对固定元素的更好处理。

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

验证

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

需要更多帮助吗？

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

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

AMP 项目强烈鼓励您参与和贡献！我们希望您成为我们开源社区的持续参与者，但我们也欢迎针对您特别热衷的问题进行一次性贡献。

前往 GitHub