AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

在非 AMP 页面中集成 Web Stories

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

 
<!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 Stories 依赖于 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 播放器 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

通过在 <amp-story-player> 元素中包含一个 <a> 标签，并将 href 属性指向所需的 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 故事播放器在加载完整故事时会显示此图像。

<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> 元素的子项。包含所需 "controls" 的数组。

<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 播放器。当在以 lightbox 或全屏视图显示播放器的实现中使用播放器时，建议这样做。

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

  • 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>

分享控件

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

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

  • 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 播放器的方法以编程方式控制播放器。这些方法包括何时初始化播放器、使音频静音以及暂停故事。

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)

元素必须先连接到 DOM，然后才能调用 load()。

请参阅Web Story 播放器规范中的方法列表。

交互式事件

Web Story 播放器会分派您可以侦听和响应的事件。使用这些事件来创建交互式体验并跟踪分析。事件的完整列表可以在Web Story 播放器规范中找到。

在下面的示例中，我们使用 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 播放器，您必须通过入口点将它们介绍给您的网站用户。以下指南将教您如何创建遵循最佳 UX 实践的入口点。