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

重要事項：本文件不適用於您目前選取的格式 stories！

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 屬性從遠端網址載入 JSON 設定，或將其內嵌於 <amp-next-page> 的 <script> 子元素中。您可以同時指定遠端網址和內嵌 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>

從遠端網址載入設定

使用 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 設定的字串網址。這應遵守與初始網址相同的規則，並實作 CORS 需求)。
網址替換

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

<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 要求規格中指定的必要條件。

除非 <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，否則會將 0 的 tabindex 新增至指定的元素。

版本注意事項

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

API 變更具有重大變更，請參閱移轉章節以瞭解詳細資訊。
0.1 初始實驗性實作。限制為三個建議文件

驗證

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

需要更多協助嗎？

您已閱讀這份文件十幾次，但它仍然沒有真正涵蓋您的所有問題嗎？或許其他人也有相同的感受：在 Stack Overflow 上與他們聯繫。

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

AMP 專案非常鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的持續參與者，但我們也歡迎針對您特別感興趣的問題提供一次性的貢獻。

前往 GitHub