在非 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>
包含 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 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>
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 播放器添加一个关闭图标。当在以灯箱或全屏视图显示播放器的实现中使用播放器时，建议这样做。
“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” 名称的控件对象，添加一个跳到播放器内部下一个故事的控件。此功能仅在桌面上可用，因为移动用户可以使用 “swipe” 手势跳到下一个故事。
“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)
load() 之前连接到 DOM。请参阅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 播放器正在显示您的故事，您必须通过入口点将它们介绍给您的网站用户。 以下指南将教您如何创建遵循最佳用户体验实践的入口点。