amp-story-interactive

<script async custom-element="amp-story-interactive" src="https://cdn.ampproject.org/v0/amp-story-interactive-0.1.js"></script>

amp-story-interactive 元件在 Web Stories (網頁故事) 中提供一系列體驗，例如測驗或投票。

用法

amp-story-interactive 元件包含一系列互動體驗。透過定義以下其中一個元素，指定互動體驗。為了獲得最佳效果，每個 amp-story-page 僅使用一個元素。

大多數元素都需要後端端點，以儲存每個互動的彙整資料，以及在不同工作階段中保留使用者的選取選項。元素將從這個端點擷取每個選項的投票百分比以及使用者選取項目 (如果有的話)，並在使用戶選取選項後與選項一起顯示。

若要查看所有元件的實際運作情況，請查看範例故事。

amp-story-interactive-binary-poll

amp-story-interactive-binary-poll 元素提供雙選項投票使用者介面。使用者可以選取兩個有效選項之一。選取後，醒目顯示的選項會填滿容器並顯示總投票百分比。

不支援與 amp-story-interactive-results 配對，並且可以選擇性地包含提示。

<amp-story-interactive-binary-poll
  id="pizza-binary-poll"
  endpoint="https://backend.com/v1/interactives"
  prompt-text="Like Pizza?"
  option-1-text="Yes"
  option-1-confetti="🍕"
  option-2-text="No"
  option-2-confetti="🤢"
>
</amp-story-interactive-binary-poll>

amp-story-interactive-img-poll

amp-story-interactive-img-poll 元素提供具有 2-4 個選項的投票體驗，這些選項以網格顯示，其中所有選項都是有效的可選取圖片。選取後，每個選項都會顯示總投票百分比。

透過將 amp-story-interactive-img-poll 與 amp-story-interactive-results 配對，根據使用者投票答案顯示不同的類別。新增提示以提供額外背景資訊。

<amp-story-interactive-img-poll
    id="travel-poll"
    prompt-text="Where would you travel?"
    prompt-size="large"
    endpoint="https://backend.com/v1/interactives"
    option-1-image="tahoe.png"
    option-1-image-alt="Lake Tahoe"
    option-2-image="hk.png"
    option-2-image-alt="Hong Kong"
    option-3-image="hawaii.png"
    option-3-image-alt="Hawaii"
    option-4-image="grand-canyon.png"
    option-4-image-alt="Grand Canyon">
</amp-story-interactive-img-poll>

amp-story-interactive-img-quiz

amp-story-interactive-img-quiz 元素提供具有 2-4 個圖片選項的猜謎體驗，其中一個選項是正確答案。在使用者做出選擇後，它會顯示投票百分比。如果使用者選取正確答案，則會以綠色顯示，如果選取錯誤答案，則會以紅色顯示。

透過將 amp-story-interactive-img-quiz 與 amp-story-interactive-results 配對，根據使用者正確答案的百分比顯示不同的類別。新增提示以提供額外背景資訊。

<amp-story-interactive-img-quiz
    id="structure-quiz"
    prompt-text="Which of these structures is oldest?"
    prompt-size="large"
    endpoint="https://backend.com/v1/interactives"
    option-1-image="liberty.png"
    option-1-image-alt="Statue of Liberty"
    option-1-correct
    option-2-image="golden-gate.png"
    option-2-image-alt="Golden Gate Bridge"
    option-3-image="redeemer.png"
    option-3-image-alt="Christ the Redeemer"
    option-4-image="eiffel.png"
    option-4-image-alt="Eiffel Tower">
</amp-story-interactive-img-quiz>

amp-story-interactive-poll

amp-story-interactive-poll 元素提供具有 2-4 個選項的投票體驗，這些選項以垂直方式顯示，其中所有選項都是有效的。選取後，每個選項都會顯示總投票百分比。

透過將 amp-story-interactive-poll 與 amp-story-interactive-results 配對，根據使用者投票答案顯示不同的類別。新增提示以提供額外背景資訊。

<amp-story-interactive-poll
    id="season-poll"
    theme="dark"
    endpoint="https://backend.com/v1/interactives"
    prompt-text="Pick a season"
    option-1-text="Spring" option-1-confetti="🌼"
    option-2-text="Summer" option-2-confetti="☀️"
    option-3-text="Fall" option-3-confetti="🍁"
    option-4-text="Winter" option-4-confetti="☃️">
</amp-story-interactive-poll>

amp-story-interactive-quiz

amp-story-interactive-quiz 元素提供具有 2-4 個選項的猜謎體驗，其中一個選項是正確答案。在使用者做出選擇後，它會顯示投票百分比。如果使用者選取正確答案，則會以綠色顯示，如果選取錯誤答案，則會以紅色顯示。

透過將 amp-story-interactive-quiz 與 amp-story-interactive-results 配對，根據使用者正確答案的百分比顯示不同的類別。新增提示以提供額外背景資訊。

<amp-story-interactive-quiz
    id="arts-quiz"
    endpoint="https://backend.com/v1/interactives"
    prompt-text='Who was the artist that created the famous painting "The Last Supper"?'
    option-1-text="Michelangelo"
    option-2-text="Leonardo da Vinci" option-2-correct option-2-confetti="🎨"
    option-3-text="Rahael"
    option-4-text="Sandro Boticelli">
</amp-story-interactive-quiz>

amp-story-interactive-results

amp-story-interactive-result 元素會顯示根據使用者從先前投票或測驗中選取的選項定義的自訂狀態。這個元素需要使用先前頁面中的投票或測驗，才能計算基於答案的狀態。每個結果類別都可以包含圖片、標題和說明，以向使用者顯示。

每個類別都會指定其內容 option-{1/2/3/4}-{text/image/results-category} 屬性，其中 -results-category 是指類別的名稱，-image 是指如果選取該類別將顯示的圖片，而 -text 是指說明。

如果所有類別也指定 option-{1/2/3/4}-results-threshold，則結果可以從測驗饋送其狀態。如果沒有類別具有閾值，則狀態會計算從投票中選取的選項中的 option-{1/2/3/4}-results-category。

<amp-story-interactive-results
    theme="dark"
    prompt-text="You are a"
    option-1-results-category="Dog" option-1-image="dog.png"
    option-1-text="You always have energy and love being with friends. Outdoors is your favorite place"
    option-2-results-category="Cat" option-2-image="cat.png"
    option-2-text="Cats are great animals for WFH">
</amp-story-interactive-results>

amp-story-interactive-slider

amp-story-interactive-slider 元素提供用於範圍內值的投票體驗。使用者透過在軌跡上拖曳滑桿來與滑桿互動，並放開以投票。選取後，會顯示平均回應。

透過屬性 option-1-text 顯示選取的百分比或表情符號。不支援與 amp-story-interactive-results 配對，並且可以選擇性地包含提示。

<amp-story-interactive-slider
    style="--interactive-accent-color: #651ffe"
    prompt-text="How much do you like this product?"
    endpoint="https://backend.com/v1/interactives">
</amp-story-interactive-slider>

儲存並顯示使用者選擇

所有可選取的互動元素 (amp-story-interactive-binary-poll、amp-story-interactive-img-poll、amp-story-interactive-img-quiz、amp-story-interactive-poll、amp-story-interactive-quiz) 都會顯示選取每個選項的使用者百分比。使用 endpoint 屬性指定的後端將根據以下描述的 API 儲存互動的彙整資料。若要擷取互動元素的資料，必要的欄位為

• interactiveId：base64encode(CANONICAL_URL) + "+" + element.id
• interactiveType：來自 amp-story-interactive-abstract:48 的列舉
• endpoint：屬性 element.getAttribute("endpoint")
• ampId：識別工作階段的用戶端 ID，選填

然後，請求和回應為

// Getting the votes for an interactive.
// If no client param, selected will always be false
// (can be used to display the results on a dashboard).

GET_URL = "{endpoint}/{interactiveId}?type={interactiveType}&client={ampId}"

Response: {
"options": [
{"index": 0, "selected": false, "count": 0},
{"index": 1, "selected": false, "count": 5},
{"index": 2, "selected": false, "count": 7},
{"index": 3, "selected": false, "count": 2}
]
}

測驗和投票最多支援 4 個選項 (對應於答案)，滑桿支援 101 個選項 (對應於百分比 0-100)。

// Posting the vote for an interactive. Client param is required.

POST_URL = "{endpoint}/{interactiveId}:vote?type={interactiveType}&client={ampId}"
POST_BODY = {'option_selected': 1}

Response: No response necessary

後端需要在必要的元件 (binary-poll、poll、quiz) 上指定，並且可以由發布商、工具或其他人員部署。

使用者資訊對話方塊

amp-story-interactive 元件會向後端服務報告彙整的使用者回應統計資料。資訊對話方塊會向使用者說明如何處理和彙整他們的回應。

資訊對話方塊預設會顯示在 endpoint 屬性中傳遞的網址網域。後端擁有者可以將其網域新增到查詢檔案中，以便為使用者提供更清楚的資訊，說明如何使用和收集他們的資料，但這不是後端運作的必要條件。當使用列出的後端時，資訊對話方塊會顯示代表接收資料的實體的字串和「瞭解詳情」連結。後端擁有者可以在 disclaimer-backends-list.json 中包含其資訊供使用者參考，方法是在 GitHub 上提交提取請求。

有效的資訊欄位為

• learnMoreUrl：包含有關後端資料收集的更多資訊的頁面網址。
• entityName：代表接收資料的實體的字串。

屬性

來自 amp-story-interactive 的互動體驗元素共用 API 語言，用於自訂選項。

id (binary-poll、img-poll、img-quiz、poll、quiz、slider 類型為必填)

元素 ID，用於識別故事中的互動元件。用於組成傳送至後端的 interactiveId。對於故事中的每個元件應該是唯一的。

endpoint (binary-poll、img-poll、img-quiz、poll、quiz、slider 類型為必填)

後端的完整網址。儲存互動元素投票。

theme (選填)

控制晶片和文字的顏色。可以是 light (預設)、dark。

chip-style (img-poll、img-quiz、poll、quiz、results、slider 類型為選填)

控制元件的樣式。可以是 flat (預設)、shadow 或 transparent。Results、binary-poll、sliders、img-poll 和 img-quiz 元素不支援 shadow。

prompt-text (選填)

在元件頂部新增提示。使用 prompt-text 撰寫投票/測驗問題，或作為 amp-story-interactive-result 元素中類別的前置詞。

prompt-size (binary-poll、img-poll、img-quiz、poll、quiz、slider 類型為選填)

控制提示文字的 font-size。可以是 small、medium (預設)、large。大型提示最多可容納 3 行文字，其他尺寸最多可容納 4 行文字。

此屬性不適用於 amp-story-interactive-result 類別前置詞文字的樣式設定。

option-{1/2/3/4}-text (binary-poll、poll、quiz、results 類型為必填)

代表編號選項的字串。二元投票需要 2 個選項。投票和測驗可能包含 2 到 4 個選項。滑桿可能包含 1 個選項，用於選用的表情符號。

amp-story-interactive-result 元素使用此字串值作為類別說明。

option-{1/2/3/4}-image (img-poll、img-quiz 類型為必填，results 類型為選填)

圖片的路徑，代表編號選項，適用於 2 到 4 個選項之間的任何位置。

amp-story-interactive-result 元素使用此路徑作為視覺類別說明。

大型高品質圖片資產是不必要的，因為它們顯示在小型容器中，因此最好保持圖片資產小巧以增強效能。建議最小尺寸為 170 x 170 像素，如果正在使用結果元件，則最大尺寸為 250 x 250 像素。

option-{1/2/3/4}-image-alt (img-poll、img-quiz 類型為必填)

用於協助工具的對應選項的圖片文字說明。

option-{1/2/3/4}-confetti (binary-poll、img-poll、img-quiz、poll、quiz 類型為選填)

在選取選項時爆發爆炸動畫的表情符號。在測驗中，只有正確的選項才應具有紙屑。

option-{1/2/3/4}-results-category (img-poll 和 poll 類型為選填，results 類型為必填)

amp-story-interactive-results 元素上類別的名稱。在 prompt-text 之後和類別說明之前以大型文字顯示。如果未定義 option-{1/2/3/4}-results-threshold，則會顯示在整個故事中選取選項最多的類別。

在投票中，它會將選項連結到具有該名稱的結果 (如上所述)。字串必須完全符合才能連結選項。

範例

<amp-story-interactive-poll
    prompt-text="What's your favorite food"
    endpoint="https://backend.com/v1/interactives"
    option-1-results-category="Bunny" option-1-text="Carrots"
    option-2-results-category="Dog" option-2-text="Bones"
    option-3-results-category="Cat" option-3-text="Fish">
</amp-story-interactive-poll>

<!-- Each option in the poll above will count towards a category in the result's state, linked using the `option-{1/2/3/4}-results-category` attribute. Stories should have many polls with linked categories, but in this example we only show one. -->

<amp-story-interactive-results
    prompt-text="You are a"
    option-1-results-category="Dog" option-1-image="dog.png"
    option-2-results-category="Cat" option-2-image="cat.png"
    option-3-results-category="Bunny" option-3-image="bunny.png">
</amp-story-interactive-results>

option-{1/2/3/4}-results-threshold (results 類型為選填)

決定連結到測驗元素時 amp-story-interactive-results 類別的下限。元件會從正確回答問題的百分比 (介於 0 到 100 之間) 計算分數。它會顯示小於或等於分數的類別。如果所有閾值都高於分數，則會顯示分數最低的類別。如果任何選項存在閾值，則所有其他選項也需要閾值。

範例

<!-- State is "beginner" if less than 80% of the quizzes were correct, state is "expert" otherwise. -->

<amp-story-interactive-results
    prompt-text="Your level is"
    option-1-results-category="Beginner" option-1-image="beginner.png"
    option-1-results-threshold="0"
    option-2-results-category="Expert" option-2-image="expert.png"
    option-2-results-threshold="80">
</amp-story-interactive-results>

樣式設定

在 範例故事 中查看所有主題選項的實際運作情況。

CSS 變數

使用 CSS 變數和屬性設定所有 amp-story-interactive 元素的樣式。透過將類別指派給元素來覆寫預設變數。

• --interactive-accent-color：元件的強調色。
• --interactive-prompt-text-color：頂部文字 (在適用的情況下) 的顏色 (具有提示的元素或具有閾值的結果)。
• --interactive-prompt-background：頂部文字 (在適用的情況下) 的背景 (具有提示但沒有圖片的元素或具有閾值的結果)。可以是顏色 (包括透明) 或 CSS 漸層。
• --interactive-prompt-alignment：提示 (在適用的情況下) 的對齊方式 (具有提示的元素)。如果元件具有透明樣式或二元投票，則預設為置中，否則預設為初始對齊方式。

主題

theme 屬性控制元件的晶片顏色和文字顏色。可以是 light (預設) 或 dark。chip-style 屬性控制元件的樣式詳細資訊。可以是 flat (預設)、shadow 或 transparent。

尺寸設定

所有 amp-story-interactive 元素都使用 container 版面配置，因此可以操控寬度，但高度會自動計算。您可以將 font-size 覆寫為元素上的任何值 (以 rem、em 或其他單位表示)，並且元素將相應地縮放。您可以使用 CSS 將寬度覆寫為最大寬度和最小寬度之間的任何值 (如下所述) 以更新元素的縱橫比。

預設 font-size 為 3*var(--story-page-vmin)，以便元素佔據直向故事寬度的 75%，而與螢幕尺寸無關。

amp-story-interactive-poll 和 amp-story-interactive-quiz 元素的 min-width 為 14em，max-width 為 25em。amp-story-interactive-binary-poll、amp-story-interactive-img-poll、amp-story-interactive-img-quiz 和 amp-story-interactive-results 元素的 min-width 為 14em，max-width 為 18em。

amp-story-grid-layer[aspect-ratio] 內的尺寸設定

可以使用 aspect-ratio 圖層，以便透過在元件上以 em 或 % 設定字型大小，建立可完美縮放以適應不同螢幕尺寸的版面配置。使用者不應使用像素，它們無法根據不同的螢幕尺寸相應地縮放。

寬度可以設定為父項寬度的 em 或百分比，並且它的行為將完全一致 (同時將其保持在最小寬度和最大寬度之間)。

<amp-story-grid-layer template="fill" aspect-ratio="400:600">

  <div class="center-quiz">
    <amp-story-interactive-quiz
      style="font-size:0.2em"
      ...>
    </amp-story-interactive-quiz>
  </div>
</amp-story-grid-layer>

選項的自適應字型大小

投票和二元投票可以根據內容類型調整其字型大小。根據選項文字的行數，它們可以增加或減少字型大小。字型大小將預設為可容納所有測量文字的最大可能值。例如，如果其中一個選項需要小字型大小 (因為它有很多文字)，但其他選項不需要，則所有相關的文字元素都將使用小字型大小。請注意，這僅最佳化選項的內容以更好地適應，但它們不會變更元素的固有大小。

僅在選取後，二元投票才會顯示選項的不同字型大小。如果所有選項都是表情符號或具有簡短文字 (長度 <= 3)，則它們將保持大字型大小。如果至少其中一個選項的長度超過 3 個字元，但兩個選項都可以在一行中顯示，則元素將使用中字型大小；如果至少一個選項有兩行，則使用小字型大小。

投票也將根據內容調整選項的字型大小。如果所有選項都適合在一行中顯示，則它們將使用大字型大小。如果任何選項需要 2 行，則所有選項都將縮小尺寸以容納晶片中的選項文字。

如需即時示範，請查看 binary-poll 和 poll Codepen，並變更選項文字 (請務必在二元投票示範中選取「已回答」，以查看尺寸變更)。

動畫

透過在元素進入頁面或從選項選取轉換到資料顯示時新增動畫，來增強互動性。從 amp-story 動畫 中選取，並將 animate-in 屬性新增至所需的元素。

分析

amp-story-interactive 元件元素支援 amp-analytics。透過將 story-interactive 事件新增至您的設定，報告選取的選項

• storyInteractiveId：元素 ID
• storyInteractiveResponse：選取的選項
• storyInteractiveType：列舉 InteractiveType

<amp-analytics id="my-analytics">
  <script type="application/json">
    {
      "requests": {
        "interactive": "https://example.com/interactive?id=${storyInteractiveId}&response=${storyInteractiveResponse}"
      },
      "triggers": {
        "interactiveSelected": {
          "on": "story-interactive",
          "request": "interactive"
        }
      }
    }
  </script>
</amp-analytics>

無障礙考量

目前，此元件缺少鍵盤和螢幕閱讀器協助工具。

驗證

請參閱 amp-story-interactive 驗證器 中的驗證規則。