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 屬性中傳遞的 URL 網域。後端擁有者可以將其網域新增到查閱檔案中，以便為使用者提供更清晰的資訊，說明其資料的使用和收集方式，但這不是後端運作的必要條件。當使用列出的後端時，資訊對話方塊會顯示一個字串，代表接收資料的實體和「瞭解詳情」連結。後端擁有者可以在 disclaimer-backends-list.json 中包含其使用者的資訊，方法是在 GitHub 上提交提取請求。

有效的資訊欄位為

• learnMoreUrl：包含有關後端資料收集的更多資訊的頁面 URL。
• 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 必填)

後端的完整 URL。儲存互動式元素投票。

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 像素，如果使用 results 元件，則最大尺寸為 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 驗證器中的驗證規則。