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。results、binary-poll、slider、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 行，则所有选项的大小都会减小以适应芯片中的选项文本。

有关实时演示，请查看 二元投票 和 投票 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 验证器中的验证规则。