AMP

操作和事件

Important: this documentation is not applicable to your currently selected format stories!

本文档介绍适用于 AMP 网站、故事和广告的操作和事件。有关 AMP 电子邮件格式,请参阅 AMP 电子邮件中的操作和事件

on 属性用于在元素上安装事件处理脚本。受支持的事件取决于元素。

语法的值是一种简单的域特定语言,形式为:

eventName:targetId[.methodName[(arg1=value, arg2=value)]]

有关语法中各个部分的说明,请参见下表。

语法 是否为必需项? 说明
eventName 元素公开的事件的名称。
targetId 元素的 DOM ID,或者是为了对事件做出响应而要执行操作的预定义特殊目标的 DOM ID。在以下示例中,targetIdamp-lightbox 目标 photo-slides 的 DOM ID。
<amp-lightbox id="photo-slides"></amp-lightbox>
<button on="tap:photo-slides">Show Images</button>
methodName 适用于具有默认操作的元素。

这是由目标元素(targetId 引用)公开并且您要在事件被触发时执行的方法。

AMP 提供了元素可以实现的默认操作的概念。因此,如果忽略 methodName,AMP 将执行默认方法。

arg=value 有些操作(如果已记录)可以接受参数。这些参数的定义方式是使用括号将 key=value 表示法括起来。接受的值包括:
  • 简单的无引号字符串:simple-value
  • 带引号字符串:"string value"'string value'
  • 布尔值:truefalse
  • 数值:111.1
  • 以句点语法形式对事件数据的引用:event.someDataVariableName

处理多个事件

使用分号 ; 将各个事件隔开,可以侦听元素上的多个事件。

示例:on="submit-success:lightbox1;submit-error:lightbox2"

一个事件的多项操作

使用逗号“,”将各个操作隔开,可以按顺序对同一事件执行多项操作。

示例:on="tap:target1.actionA,target2.actionB"

全局定义的事件和操作

AMP 定义了全局 tap 事件,您可以在任何 HTML 元素(包括 AMP 元素)上侦听该事件。

AMP 还定义了全局 hideshowtoggleVisibility 操作,您可以在任何 HTML 元素上触发这些操作。

仅当元素先前是通过 hidetoggleVisibility 操作或者是使用 hidden 属性进行隐藏的,才能显示该元素。使用 show 操作,无法显示通过 CSS display:none 或 AMP layout=nodisplay 隐藏起来的元素。

例如,可以在 AMP 中编写以下程序:

<div id="warning-message">Warning...</div>

<button on="tap:warning-message.hide">Cool, thanks!</button>

元素特有的事件

* - 所有元素

事件 说明
tap 点击/点按元素时触发。

输入元素

事件 说明 元素 数据
change 更改和提交元素的值时触发。

数据属性会镜像 HTMLInputElementHTMLSelectElement 中的相应属性。

input
event.min
event.max
event.value
event.valueAsNumber
input[type="radio"],
input[type="checkbox"]
event.checked
select
event.min
event.max
event.value
input-debounced 在元素的值发生更改时触发。该事件与标准的 change 事件类似,但它仅在输入值停止更改并且经过 300ms 后才会触发。 可触发 input 事件的元素。 change 事件数据相同。
input-throttled 在元素的值发生更改时触发。该事件与标准的 change 事件类似,但仅局限于在输入值发生更改时每 100ms 最多触发一次。 可触发 input 事件的元素。 change 事件数据相同。

amp-accordion > 部分

事件 说明 数据
expand 在手风琴式组件部分展开时触发。 无。
collapse 在手风琴式组件部分折叠时触发。 无。

amp-carousel[type="slides"]

事件 说明 数据
slideChange 在轮播的当前幻灯片更改时触发。
// Slide number.
event.index

amp-lightbox

事件 说明 数据
lightboxOpen 在灯箱完全可见时触发。
lightboxClose 在灯箱完全关闭时触发。

amp-list

事件 说明 数据
changeToLayoutContainer amp-list 布局更新为 layout="CONTAINTER",以便重新动态调整大小
fetch-error(low-trust) 提取数据失败时触发。

amp-selector

事件 说明 数据
select 选择或取消选择选项时触发。
// Target element's "option" attribute value.
event.targetOption
// Array of "option" attribute values of all selected elements.
event.selectedOptions

amp-sidebar

事件 说明 数据
sidebarOpen 过渡结束后边栏完全打开时触发。
sidebarClose 过渡结束后边栏完全关闭时触发。

amp-state

事件 说明 数据
fetch-error(low-trust) 提取数据失败时触发。

amp-video、amp-youtube

事件 说明 数据
firstPlay(low-trust) 用户首次播放视频时触发。在自动播放视频中,只要用户与视频互动,就会触发该事件。此事件可信度低,意味着它无法触发大部分操作,只能执行可信度低的操作,例如 amp-animation 操作。
timeUpdate(low-trust) 视频的播放位置发生更改时触发。事件发生频率由 AMP 控制,目前的时间间隔设置为 1 秒。此事件可信度低,意味着它无法触发大部分操作,只能执行可信度低的操作,例如 amp-animation 操作。 {time, percent}time 表示当前时间(以秒计),percent 为介于 0 和 1 之间的数值,表示当前所在位置占总时间的百分比。

form

事件 说明 数据
submit 提交表单时触发。
submit-success 提交表单成功时触发。
// Response JSON.
event.response
submit-error 提交表单出错时触发。
// Response JSON.
event.response
valid 表单有效时触发。
invalid 表单无效时触发。

元素特有的操作

*(所有元素)

操作 说明
hide Hides the target element.
show 显示目标元素。如果 autofocus 元素最终显示,它将获得焦点。
toggleVisibility 切换目标元素的可见性。如果 autofocus 元素最终显示,它将获得焦点。
toggleClass(class=STRING, force=BOOLEAN) 切换目标元素的类。force 为可选项,如果定义该属性,可确保在该属性设为 true 时仅添加类而不移除类,在该属性设为 false 时仅移除类而不添加类。
scrollTo(duration=INTEGER, position=STRING) 将元素滚动到显示流畅的动画。
duration 为可选项,用于指定动画的时长(以毫秒计)。如果未指定此属性,将使用相对于滚动差值不大于 500 毫秒的量。
position 为可选项,值为 topcenterbottom 之一(默认值为 top)。指定元素在滚动后相对于视口的位置。
无障碍功能的最佳做法是,将此属性与 focus() 的调用进行配对,以将焦点置于要滚动到的元素。
focus 使目标元素获得焦点。要取消焦点,可以 focus 其他元素(通常为父元素)。出于无障碍功能考虑,我们强烈建议将焦点置于 body/documentElement,而不要取消焦点。

amp-audio

操作 说明
play 播放音频。如果 <amp-audio> 元素是 <amp-story> 的子级,则该操作为空操作。
pause 暂停音频。如果 <amp-audio> 元素是 <amp-story> 的子级,则该操作为空操作。

amp-bodymovin-animation

操作 说明
play 播放动画。
pause 暂停动画。
stop 停止动画。
seekTo(time=INTEGER) 将动画的 currentTime 设为指定的值,并暂停动画。
seekTo(percent=[0,1]) 使用给定的百分比值将动画的 currentTime 设为指定的值,并暂停动画。

amp-accordion

操作 说明
toggle(section=STRING) amp-accordion 部分在 expandedcollapsed 状态之间切换。调用该操作时,如果不指定参数,将切换手风琴式组件的所有部分。如果提供部分 ID,则切换特定部分:on="tap:myAccordion.toggle(section='section-id')"
expand(section=STRING) 展开手风琴式组件的各个部分。如果某个部分已展开,则该部分保持展开状态。调用该操作时,如果不指定参数,将展开手风琴式组件的所有部分。如果指定部分 ID,则展开特定部分:on="tap:myAccordion.expand(section='section-id')"
collapse(section=STRING) 折叠手风琴式组件的各个部分。如果某个部分已折叠,则该部分保持折叠状态。调用该操作时,如果不指定参数,将折叠手风琴式组件的所有部分。如果指定部分 ID,则折叠特定部分:on="tap:myAccordion.collapse(section='section-id')"

amp-carousel[type="slides"]

操作 说明
goToSlide(index=INTEGER) 前进到轮播中的指定幻灯片索引。
toggleAutoplay(toggleOn=true|false) 切换轮播的自动播放状态。toggleOn 为可选项。

amp-image-lightbox

操作 说明
open (default) 打开图片灯箱,其中的源图片为触发该操作的图片。

amp-lightbox

操作 说明
open (default) 打开灯箱。
close 关闭灯箱。
操作 说明
open 打开灯箱图库。如果指定图片 ID,则点按其他元素可以触发该操作:`on="tap:amp-lightbox-gallery.open(id='image-id')"`。

amp-list

操作 说明
refresh 刷新 src 中的数据,并重新呈现列表。

amp-live-list

操作 说明
update (default) 更新 DOM 项以显示更新后的内容。

amp-selector

操作 说明
clear 清除已定义 amp-selector 中的所有选择。
selectUp(delta=INTEGER) 将选择上移 `delta` 的值。默认 `delta` 设为 -1。如果未选择任何选项,则选定状态将成为最后一个选项的值。
selectDown(delta=INTEGER) 将选择下移 `delta` 的值。默认 `delta` 设为 1。如果未选择任何选项,则选定状态将成为第一个选项的值。
toggle(index=INTEGER, value=BOOLEAN) 切换 `selected` 的应用。如果缺少 select 属性,此操作将添加该属性。如果 select 属性存在,此操作将移除该属性。在 `value` 参数中添加布尔值,可以强制并保持该属性的添加或移除。值为 `true` 时,将强制添加 `selected` 属性,如果该属性已存在,则不移除它。值为 `false` 时,将移除该属性,如果缺少该属性,则不添加该属性。

amp-sidebar

操作 说明
open (default) 打开边栏。
close 关闭边栏。
toggle 切换边栏的状态。

amp-state

操作 说明
refresh 忽略浏览器缓存时,重新提取 `src` 属性的数据。

amp-user-notification

操作 说明
dismiss (default) 隐藏所引用的用户通知元素。

视频元素

以下 AMP 视频元素支持下表列出的操作:amp-videoamp-youtubeamp-3q-playeramp-brid-playeramp-dailymotionamp-delight-playeramp-ima-video

操作 说明
play 播放视频。
pause 暂停视频。
mute 将视频静音。
unmute 取消视频静音。
fullscreencenter 全屏播放视频。

表单

操作 说明
clear 清除表单中输入的所有值。
submit 提交表单。

特殊目标

以下目标由 AMP 系统提供并具有特殊的要求:

目标:AMP

AMP 目标由 AMP 运行时提供,可实现适用于整个文档的顶级操作。

操作 说明
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

从当前窗口转到给定网址的可选指定目标(如果已给定)(目前仅支持 _top_blank )。opener 参数为可选参数,可以在以下情况下指定:使用 _blank 目标让新打开的页面访问 window.opener。支持标准网址替换

注意事项:建议尽可能使用正常的 <a> 链接,因为 AMP.navigateTo 无法被网页抓取工具识别。

closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)

尝试关闭窗口(如果允许),否则进行浏览,这与 navigateTo 操作类似。适用于以下用例:如果通过前一个页面在新窗口中打开一个窗口,可能需要使用“Back”按钮关闭该窗口;如果未打开窗口,可能需要使用“Back”按钮进行浏览。

注意事项:建议尽可能使用正常的 <a> 链接,因为 AMP.closeOrNavigateTo 无法被网页抓取工具识别。

goBack 回溯历史记录。
print 打开“Print”对话框以打印当前页面。
scrollTo(id=STRING, duration=INTEGER, position=STRING) 滚动到当前页面上所提供的元素 ID。
optoutOfCid 取消针对所有范围生成客户端 ID。
setState({foo: 'bar'})1

需要 amp-bind

将对象字面量合并到可绑定状态。

pushState({foo: 'bar'})1

需要 amp-bind

将对象字面量合并到可绑定状态,并将新条目推送到浏览器历史记录堆栈。如果弹出该条目,变量将恢复先前的值(在本例中为 foo)。

1多项操作配合使用时,后续操作将等到 setState()pushState() 完成后再调用。每个事件只允许使用一个 setState()pushState()

目标:amp-access

amp-access 目标由 amp-access 组件提供。

amp-access 目标较为特殊,原因如下所述:

  1. 您不能为此目标指定任意 ID。该目标始终为 amp-access
  2. 根据 AMP 访问配置的结构,amp-access 的操作为动态操作。

有关 amp-access 目标的用法,请参阅详细信息