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 頁面的字串網址。必須與目前文件位於相同來源。網址會在必要時自動改寫，以指向 Google AMP 快取。
title 頁面的字串標題，會在呈現推薦框時使用。
image 要在推薦框中顯示的圖片字串網址。

內嵌設定

將 JSON 設定內嵌在 <amp-next-page> 組件中，方法是將其放在子項 <script> 元素內。

<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 相同的規則，並實作 CORS 需求。)
URL 替換

amp-next-page src 允許所有標準 URL 變數替換。如需更多資訊，請參閱「替換指南」。例如

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

這個網址可能會向類似 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 屬性隱藏多個已載入頁面中共用的元素。隱藏特定元素有助於建立整潔的無限滾動體驗。這類考量包括

  • 避免堆疊共用的頁面元素，例如頁尾。
  • 避免後續頁面中出現重複的頁首
  • 避免多個側邊欄等等。

具有 next-page-hide 屬性的元素在 <amp-next-page> 內以建議載入時，會設為 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 版遷移

實驗性 0.1 版的 amp-next-page 具有類似但更受限制的 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 服務。網址的協定必須是 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

設定預設頁面分隔符的樣式

每個文件都會載入全寬灰色水平線，以將其與前一頁分隔開來。您可以透過 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，否則會將 0 的 tabindex 新增至指定的元素。

版本注意事項

版本 說明
1.0 支援無限數量的頁面推薦、縮減組合包大小、改善 API、支援 amp-analytics、範本化分隔符和推薦框，以及更妥善地處理固定元素。

API 變更屬於重大變更，詳情請參閱「遷移」章節。
0.1 初始實驗性實作。僅限三個建議文件

驗證

請參閱 AMP 驗證工具規格中的 amp-next-page 規則。

需要更多協助嗎？

您已閱讀本文件數十次，但內容似乎未涵蓋您的所有問題？或許其他人也有相同感受：請在 Stack Overflow 上與他們交流。

前往 Stack Overflow
發現錯誤或缺少功能？

AMP 專案大力鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的長期參與者，但我們也歡迎針對您特別關注的問題提供一次性貢獻。

前往 GitHub