在非 AMP 页面中集成 Web Story

Web Story 是一种全屏沉浸式内容体验，用户可以按照自己的节奏点击或滑动浏览。它们存在于开放网络上，有自己的 URL，因此很容易分享。本指南教你如何在非 AMP 页面中集成 Web Story 并将其呈现给读者。

<!DOCTYPE html>
<html>
  <head>
    <script
      async
      src="https://cdn.ampproject.org/amp-story-player-v0.js"
    ></script>
    <link
      href="https://cdn.ampproject.org/amp-story-player-v0.css"
      rel="stylesheet"
      type="text/css"
    />
    <style>
      header {
        height: 8vh;
        color: #545454;
        background-color: #DDB556;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      amp-story-player {
        margin: 1rem auto;
      }
    </style>
  </head>
  <body>
    <header>
      <h1>
        Page Header
      </h1>
    </header>
    <h1>
      Article Title
    </h1>
    <p>
      Doggo ipsum smol wow very biscit length boy, doing me a frighten. Borking
      doggo doggo heckin dat tungg tho, heckin good boys. Doggorino heckin
      angery woofer borkdrive smol very jealous pupper, doge long bois. Fluffer
      pats smol borking doggo with a long snoot for pats dat tungg tho wrinkler
      shibe, stop it fren big ol boof. Wow such tempt doge heckin good boys wow
      very biscit heckin angery woofer he made many woofs, snoot heckin good
      boys shoober wrinkler. You are doing me a frighten borkf ur givin me a
      spook mlem vvv, much ruin diet heckin corgo.
    </p>
    <amp-story-player style="width: 370px; height: 622px;">
      <script type="application/json">
        {
          "behavior": {
            "autoplay": true
          }
        }
      </script>

      <a
        href="https://preview.amp.dev/documentation/examples/introduction/stories_in_amp/"
      >
      <img data-amp-story-player-poster-img src="https://amp.org.cn/static/samples/img/story_dog2_portrait.jpg" width="370" height="622" loading="lazy">
        Stories in AMP - Hello World
      </a>
    </amp-story-player>
    <p>
      Such treat big ol pupper. Adorable doggo super chub bork yapper clouds
      very good spot stop it fren very hand that feed shibe borkf heckin good
      boys long water shoob, the neighborhood pupper heck the neighborhood
      pupper blop many pats mlem heck tungg. noodle horse. Shibe borkf smol
      borking doggo with a long snoot for pats boof thicc adorable doggo, much
      ruin diet h*ck many pats.
    </p>
  </body>
</html>

在 playground 中打开此代码片段

包含 Web Story 播放器

Web Story 依赖于 AMP Story Player，以 <amp-story-player> 元素的形式，在非 AMP 站点上集成和播放故事。通过在文档的 head 中包含以下两个脚本来实现 amp-story-player 元素

<script async src="https://cdn.ampproject.org/amp-story-player-v0.js"></script>

<link href="https://cdn.ampproject.org/amp-story-player-v0.css" rel="stylesheet" type="text/css">

第一个脚本导入 AMP Story Player 的逻辑。第二个脚本设置默认样式。

包含每个脚本后，在文档 body 中包含一个 <amp-story-player> 元素。

<amp-story-player style="width: 370px; height: 622px;">
      <a
        href="https://preview.amp.dev/documentation/examples/introduction/stories_in_amp/"
      >
      <img data-amp-story-player-poster-img src="https://amp.org.cn/static/samples/img/story_dog2_portrait.jpg" width="370" height="622" loading="lazy">
        Stories in AMP - Hello World
      </a>
  </amp-story-player>

设置 Web Story 播放器的大小

我们建议尽可能使 Web Story 播放器全屏显示。这可以让读者沉浸在故事内容中，同时添加播放器提供的额外功能。添加跳至下一个控件，以获得最佳的桌面全屏体验。

查看 lightbox Web Story Player codepen，了解如何创建沉浸式 Web Story 体验的示例。

在无法全屏显示的情况下，你可以像调整任何其他 HTML 元素一样调整 Web Story 播放器的大小。你可以在内联或使用其他元素的样式来定义故事播放器的宽度、高度和其他样式。

<body>
...
  <amp-story-player style="width: 370px; height: 622px;">
...
  </amp-story-player>
...
</body>

我们建议保持 69:116 的宽高比，以获得最佳的用户体验，但你可以定义任何宽度和高度。

响应式大小

故事播放器的响应方式与任何其他块元素相同。使用 CSS 来保持宽度和高度比，如下例所示：html

<amp-story-player style="width: 50vw; height: 84.05vw;">
  ...
</amp-story-player>

显示 Web Story

通过包含一个 <a> 标签（其中 href 属性指向 <amp-story-player> 元素内的所需 Web Story URL）来链接到 Web Story。href 端点可以是托管的 Web Story 的 URL 或相对路径。将故事的标题放在 <a> 标签内。

<!DOCTYPE html>
<html>
  <head>
    <script
      async
      src="https://cdn.ampproject.org/amp-story-player-v0.js"
    ></script>
    <link
      href="https://cdn.ampproject.org/amp-story-player-v0.css"
      rel="stylesheet"
      type="text/css"
    />
    <style>
      header {
        height: 8vh;
        color: #545454;
        background-color: #DDB556;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      amp-story-player {
        margin: 1rem auto;
      }
    </style>
  </head>
  <body>
    <header>
      <h1>
        Page Header
      </h1>
    </header>
    <h1>
      Article Title
    </h1>
    <amp-story-player style="width: 370px; height: 622px;">
      <a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s3">
        <img src="https://ss.makestories.io/get?story=-MHy2RL_9ZnDFYTFB2PY&version=1600916568756" loading="lazy" data-amp-story-player-poster-img width="370" height="622"></img>
      </a>
    </amp-story-player>
  </body>
</html>

在 playground 中打开此代码片段

提供占位符

通过添加一个 <img> 标签作为故事的 <a> 标签的子标签，并使用以下配置来包含代表性的海报图像。AMP Story Player 在加载完整故事时会显示此图像。

<amp-story-player style="width: 50vw; height: 83.35vw;">
  <a href="https://www.example.com/story.html">
    <img src="https://www.example.com/assets/cover1.html" loading="lazy" width="100%" height="100%" data-amp-story-player-poster-img>
    A title that describes this story.
  </a>
</amp-story-player>

为了获得最佳用户体验，我们强烈建议包含海报图像。如果不包含海报图像，故事播放器将显示带有灰色背景的加载微调器。

自动播放故事

默认情况下，当播放器在用户的视口中可见时，播放器中的第一个故事将自动开始播放。

你可以使用以下配置选择退出默认行为。这将阻止播放器中的第一个故事开始播放，直到你在播放器上调用 play()。

<amp-story-player>
  <script type="application/json">
  {
    "behavior": {
      "autoplay": false
    }
  }
</script>
 <a href="./story1.html"> ... </a>
 <a href="./story2.html"> ... </a>
  ...

指定多个 Web Story

在 <amp-story-player> 元素中包含所需数量的 <a> 标签，每个 href 属性都指向所需的 Web Story URL。

<!DOCTYPE html>
<html>
  <head>
    <script
      async
      src="https://cdn.ampproject.org/amp-story-player-v0.js"
    ></script>
    <link
      href="https://cdn.ampproject.org/amp-story-player-v0.css"
      rel="stylesheet"
      type="text/css"
    />
    <style>
      header {
        height: 8vh;
        color: #545454;
        background-color: #DDB556;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      amp-story-player {
        margin: 1rem auto;
      }
    </style>
  </head>
  <body>
    <header>
      <h1>
        Page Header
      </h1>
    </header>
    <h1>
      Article Title
    </h1>
    <amp-story-player style="width: 370px; height: 622px;">
      <a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s1"></a>
      <a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s2"></a>
      <a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s3"></a>
    </amp-story-player>
  </body>
</html>

在 playground 中打开此代码片段

Web Story 播放器显示第一个故事。在完成上一个故事后，它会自动向用户显示下一个故事的封面页，或者使用滑动动作来跳过。Web Story 播放器没有任何内置的 UI 功能来告知用户单个播放器中有多个故事。相反，构建用户入口点以显示可用的故事并允许用户选择。

循环故事包装

你可以通过将 circular-wrapping 操作添加到 JSON 配置来创建对一组故事的循环消费。当包含 circular-wrapping 时，Web Story 播放器会在用户完成最后一个故事后向用户显示第一个故事。

<amp-story-player>
 <script type="application/json">
   {
     "behavior": {
       "on": "end",
       "action": "circular-wrapping"
     }
   }
 </script>
 <a href="./story1.html"> ... </a>
 <a href="./story2.html"> ... </a>
  ...
</amp-story-player>

JSON 配置必须是 <amp-story-player> 元素的直接子元素，并包含 type="application/json" 属性。

个性化和无限的故事

你可以创建“无限滚动”体验，让用户在 Web Story 播放器中浏览它们。为此，请包含 fetch 操作并在 JSON 配置中指定一个端点。当用户接近最后一个加载的故事时，播放器会自动获取更多故事。你可以通过设置后端个性化系统并使用 fetch 操作来为用户提供服务，从而自定义为用户获取的故事。

<amp-story-player>
 <script type="application/json">
   {
     "behavior": {
       "on": "end",
       "action": "fetch",
       "endpoint": "https://example.com/my-endpoint.json?offset=${offset}"
     }
   }
 </script>
 <a href="./story1.html"> ... </a>
 <a href="./story2.html"> ... </a>
  ...

JSON 配置必须是 <amp-story-player> 元素的直接子元素，并包含 type="application/json" 属性。对于分页，请使用可选的 endpoint url 变量 ${offset} 来添加参数。Web Story 播放器将 ${offset} 替换为实际偏移量。例如，如果发布者提供 https://example.com/my-endpoint.json?offset=${offset} 并且 Web Story 播放器加载了 5 个故事，则它将发送 https://example.com/my-endpoint.json?offset=5。

响应

Web Story 播放器期望 JSON 作为响应，其中包含故事对象数组。

[
  {
    "href": "https://example.com/story3.html",
    "title": "My third cool story", // optional
    "posterImage": "https://example.com/assets/story3.png" // optional
  },
  {
    "href": "https://example.com/story4.html",
    "title": "My fourth cool story", // optional
    "posterImage": "https://example.com/assets/story4.png" // optional
  }
]

href

你的故事所在的 URL。

title（可选）

你的故事的标题。

posterImage（可选）

你的故事的海报图像。

自定义 Web Story 播放器 UI

你可以自定义 Web Story 播放器 UI 的控件。你可以添加新的控制按钮，并更改它们的位置或外观。控件配置为 JSON，其中 type="application/json" 作为 <amp-story-player> 元素的子元素。包含所需“控件”的数组。

<amp-story-player>

 <script type="application/json">
   {
     "controls": [
       {
         "name": "close",
         "position": "start"
       },
       {
         "name": "skip-to-next"
       }
     ]
   }
 </script>
<a href="./story1.html"> ... </a>
<a href="./story2.html"> ... </a>
</amp-story-player>

关闭控件

默认情况下，Web Story 播放器不包含关闭控件。你可以通过指定名称为“close”的控件对象，将关闭图标添加到 Web Story 播放器。当在灯箱或全屏视图中显示播放器的实现中使用播放器时，建议这样做。

“close”控件支持以下可自定义的属性

position：“start”或“end”。
- 在 LTR 语言中将图标放置在左侧（“start”）或右侧（“end”）。
- 在 RTL 语言中将图标放置在左侧（“end”）或右侧（“start”）。
visibility：“hidden”或“visible”（默认）。
- 切换控件的可见性。如果省略，则默认为可见。
backgroundImageUrl：带有 url 或数据字符串（转义）的字符串。
- 将图标图像更改为提供的 url 或数据字符串（对于内联 svg）。

当用户点击/轻触关闭按钮时，它会调度 amp-story-player-close 事件。

<amp-story-player>
 <script type="application/json">
   {
     "controls": [
       {
         "name": "close",
         "backgroundImageUrl": "data:image\/svg+xml;charset=utf-8,<\/svg>",
         "position": "start"
       }
     ]
   }
 </script>
<a href="./story1.html"> ... </a>
<a href="./story2.html"> ... </a>
</amp-story-player>

分享控件在所有故事中都可见，但你可以自定义外观和位置。

“share”控件支持以下可自定义的属性

position：“start”或“end”。
- 在 LTR 语言中将图标放置在左侧（“start”）或右侧（“end”）。
- 在 RTL 语言中将图标放置在左侧（“end”）或右侧（“start”）。
visibility：“hidden”或“visible”（默认）。
- 切换控件的可见性。如果省略，则默认为可见。
backgroundImageUrl：带有 url 或数据字符串（转义）的字符串。
- 将图标图像更改为提供的 url 或数据字符串（对于内联 svg）。

通过指定名称为“skip-to-next”的控件对象，添加一个跳到播放器内下一个故事的控件。此功能仅在桌面版上可用，因为移动用户可以使用“滑动”手势跳到下一个故事。

“skip-to-next”控件支持以下可自定义的属性

position：“start”或“end”。
- 在 LTR 语言中将图标放置在左侧（“start”）或右侧（“end”）。
- 在 RTL 语言中将图标放置在左侧（“end”）或右侧（“start”）。
visibility：“hidden”或“visible”（默认）。
- 切换控件的可见性。如果省略，则默认为可见。
backgroundImageUrl：带有 url 或数据字符串（转义）的字符串。
- 将图标图像更改为提供的 url 或数据字符串（对于内联 svg）。

自定义控件

通过指定以下必需属性，将自定义控件添加到 Web Story 播放器

name：带有控件名称的字符串。例如，“lightbox”。调度的事件将取决于此名称。自定义事件将是控件的名称，前缀为 amp-story-player-*. 例如 amp-story-player-lightbox。
backgroundImageUrl：带有 url 或数据字符串（转义）的字符串。
- 将图标图像更改为提供的 url 或数据字符串（对于内联 svg）。

 <script type="application/json">
   {
     "controls": [
       {
         "name": "custom-control",
         "backgroundImageUrl": "data:image\/svg+xml;charset=utf-8,<\/svg>"
       }
     ],
   }
 </script>

事件自定义控件的分发取决于 name 属性。事件以 “amp-story-player-” 为前缀，后跟自定义控件的名称。例如，“custom-control” 会分发事件 “amp-story-player-custom-control”。

const player = document.body.querySelector("amp-story-player");

// Listen to when the specified control was clicked.
player.addEventListener("amp-story-player-custom-control", () => {
  // This will trigger when the control with the "custom-control" name is clicked.
  performCustomAction();
});

您可以使用以下可选属性进一步个性化自定义控件：

position：“start”或“end”。
- 在从左到右 (LTR) 的语言中，将图标放置在左侧或右侧。
visibility：“hidden”或“visible”（默认）。
- 切换控件的可见性。如果省略，则默认为可见。

Web Story 播放器互动性

您可以调用 Web Story Player 的方法来以编程方式控制播放器。这些方法包括何时初始化播放器、静音音频和暂停故事。

const playerEl = document.body.querySelector('amp-story-player');
playerEl.play()

可用方法在 HTML 元素上公开。

const playerEl = document.querySelector('amp-story-player')

当动态创建播放器时，例如 document.createElement('amp-story-player')，您可以使用全局类变量 AmpStoryPlayer 手动加载播放器。

const player = new AmpStoryPlayer(window, playerEl)

在调用 load() 之前，必须将该元素连接到 DOM。

请参阅 Web Story Player 规范中的方法列表。

互动事件

Web Story Player 会分发您可以监听并做出反应的事件。使用这些事件来创建交互式体验和跟踪分析。完整的事件列表可以在 Web Story Player 规范中找到。

在下面的示例中，我们使用 page-attachment-close、page-attachment-open 和 amp-story-player-back 事件来更改页面上不同元素的背景。

player.addEventListener('page-attachment-close', () => {
  textEl.style.backgroundColor = 'blue';
})
player.addEventListener('page-attachment-open', () => {
  textEl.style.backgroundColor = 'red';
})
player.addEventListener('amp-story-back', () => {
  textEl.style.backgroundColor = 'green';
})

用户入口点

现在您的 Web Story Player 正在显示您的故事，您必须通过入口点将其引入您的网站用户。以下指南将教您如何创建遵循最佳用户体验实践的入口点。