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

操作和事件

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。在以下示例中，targetId 为 amp-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'
  • 布尔值：true 或 false
  • 数值：11 或 1.1
  • 以句点语法形式对事件数据的引用：event.someDataVariableName

处理多个事件

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

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

一个事件的多项操作

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

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

全局定义的事件和操作

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

AMP 还定义了全局 hide、show 和 toggleVisibility 操作，您可以在任何 HTML 元素上触发这些操作。

仅当元素先前是通过 hide 或 toggleVisibility 操作或者是使用 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 更改和提交元素的值时触发。

数据属性会镜像 HTMLInputElement 和 HTMLSelectElement 中的相应属性。

 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 为可选项，值为 top、center 或 bottom 之一（默认值为 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 部分在 expanded 和 collapsed 状态之间切换。调用该操作时，如果不指定参数，将切换手风琴式组件的所有部分。如果提供部分 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-video、amp-youtube、amp-3q-player、amp-brid-player、amp-dailymotion、amp-delight-player、amp-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 目标的用法，请参阅详细信息。