在非 AMP 页面中集成 Web Stories
重要提示：此文档不适用于你当前选择的格式 电子邮件！
Web Stories 是一种全屏沉浸式内容体验，用户可以按照自己的节奏点击或单击浏览。它们存在于开放 Web 上，有自己的 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>
包含 Web Story 播放器
Web Stories 依赖于 AMP Story Player，以 <amp-story-player> 元素的形式，在非 AMP 站点上集成和播放故事。通过在文档头部包含以下两个脚本来实现 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 的逻辑。第二个脚本设置默认样式。
包含每个脚本后，在文档主体内包含一个 <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 播放器全屏显示。这可以让读者沉浸在故事内容中，同时添加播放器提供的额外功能。添加跳到下一个控件以获得最佳桌面全屏体验。
在无法全屏显示的情况下，你可以像调整其他 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>
提供占位符
通过添加一个 <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>
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>
事件自定义控件分派取决于名称属性。事件以“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，你必须通过入口点将其介绍给你的网站用户。以下指南将教你如何创建遵循最佳用户体验实践的入口点。