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 Story 中提供一组体验，例如测验或投票。

用法

amp-story-interactive 组件包含一组互动体验。通过定义以下元素之一来指定互动体验。为获得最佳效果，每个 amp-story-page 仅使用一个元素。

大多数元素都需要一个后端端点，该端点将存储每个交互的聚合数据，并在会话之间保留用户的选定选项。元素将从此端点获取每个选项的投票百分比以及用户的选择（如果有），并在用户选择一个选项后将其与选项一起显示。

要查看所有组件的实际效果，请查看示例 Story。

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 必需）

在 Story 中标识互动组件的元素 ID。用于组成发送到后端的 interactiveId。对于 Story 中的每个组件都应该是唯一的。

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 元素都使用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 验证器中的验证规则。