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 的域。后端所有者可以将他们的域添加到查找文件中，以便为用户提供更清晰的信息，说明他们的数据是如何被使用和收集的，但这并不是后端工作的必需。当使用列出的后端时，信息对话框会显示一个字符串，表示接收数据的实体和一个“了解更多”链接。后端所有者可以通过在 GitHub 上提交拉取请求，将他们的用户信息包含在 disclaimer-backends-list.json 中。

有效的信息字段是

• 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。结果、binary-poll、滑块、img-poll 和 img-quiz 元素不支持阴影。

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 元素都使用 容器布局，因此可以操作宽度，但高度会自动计算。您可以将元素的 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] 内的尺寸

可以通过在组件上以 em 或 % 设置字体大小，从而使用 aspect-ratio 层来创建可以与不同屏幕尺寸完美缩放的布局。用户不应使用像素，它们不会随不同的屏幕尺寸相应缩放。

宽度可以设置为父宽度的 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 验证器 中查看验证规则。