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。在故事中，每個元件應具有唯一的 ID。

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 像素，如果使用 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：適用時的提示對齊方式 (具有提示的元素)。如果元件具有 transparent 樣式，或是二元投票，則預設為置中，否則預設為初始值。

主題

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 驗證器中的驗證規則。