操作和事件
本文档涵盖了 AMP 网站、故事和广告的操作和事件。阅读 AMP 电子邮件中的操作和事件 以了解 AMP 电子邮件格式。
on 属性用于在元素上安装事件处理程序。支持的事件取决于元素。
语法值是一种简单的特定于域的语言，形式为
eventName:targetId[.methodName[(arg1=value, arg2=value)]]
请参阅下表了解语法各部分的描述。
| 语法 | 是否必需？ | 描述 |
|---|---|---|
eventName | 是 | 这是元素公开的事件的名称。 |
targetId | 是 | 这是元素的 DOM id，或您希望在响应事件时对其执行操作的预定义特殊目标。在以下示例中，targetId 是 amp-lightbox 目标的 DOM id，即 photo-slides。 <amp-lightbox id="photo-slides"></amp-lightbox> <button on="tap:photo-slides">Show Images</button> |
methodName | 否 | 这是针对具有默认操作的元素。 这是目标元素（由 AMP 有一个元素可以实现的默认操作的概念。因此，当省略 |
arg=value | 否 | 如果记录了一些操作，则它们可能接受参数。参数在 key=value 表示法中的括号内定义。可接受的值为
|
处理多个事件
您可以通过用分号 ; 分隔事件来侦听元素上的多个事件。
示例：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 | 当点击/轻触元素时触发。 |
copy-success | 当内容/文本成功复制到剪贴板时触发。 |
copy-error | 复制内容时出错时触发。如果复制内容时出错，event.data.type 将设置为 error 值。如果浏览器不支持复制方法，event.data.type 将设置为 browser 值。 |
输入元素
| 事件 | 描述 | 元素 | 数据 |
|---|---|---|---|
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 事件类似，但仅在输入值停止更改 300 毫秒后才触发。 | 触发 input 事件的元素。 | 与 change 事件数据相同。 |
input-throttled | 当元素的值更改时触发。这与标准 change 事件类似，但当输入值更改时，它会限制每 100 毫秒最多触发一次。 | 触发 input 事件的元素。 | 与 change 事件数据相同。 |
amp-accordion > section
| 事件 | 描述 | 数据 |
|---|---|---|
expand | 手风琴部分展开时触发。 | 无。 |
collapse | 手风琴部分折叠时触发。 | 无。 |
amp-carousel[type="slides"]
| 事件 | 描述 | 数据 |
|---|---|---|
slideChange | 当轮播的当前幻灯片发生变化时触发。 | // Slide number. event.index |
amp-lightbox
| 事件 | 描述 | 数据 |
|---|---|---|
lightboxOpen | 当灯箱完全可见时触发。 | 无 |
lightboxClose | 当灯箱完全关闭时触发。 | 无 |
amp-list
| 事件 | 描述 | 数据 |
|---|---|---|
fetch-error（低信任度） | 当获取数据失败时触发。 | 无 |
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（低信任度） | 当获取数据失败时触发。 | 无 |
amp-video 和其他视频元素
以下事件由 amp-video、amp-video-iframe 和 第三方视频播放器（如 amp-youtube）分派。
| 事件 | 描述 | 数据 |
|---|---|---|
firstPlay（低信任度） | 当用户第一次播放视频时触发。对于自动播放视频，此事件在用户与视频交互后立即触发。此事件是低信任度的，这意味着它无法触发大多数操作；只能运行低信任度的操作，例如 amp-animation 操作。 | |
timeUpdate（低信任度） | 当视频的播放位置发生变化时触发。事件的频率由 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 | 隐藏目标元素。 |
show | 显示目标元素。如果结果中显示了 autofocus 元素，则该元素将获得焦点。 |
toggleVisibility | 切换目标元素的可见性。如果结果中显示了 autofocus 元素，则该元素将获得焦点。 |
toggleClass(class=STRING, force=BOOLEAN) | 切换目标元素的 class。force 是可选的，如果已定义，则确保如果设置为 true，则仅添加 class 而不删除 class；如果设置为 false，则仅删除 class 而不添加 class。 |
toggleChecked(force=BOOLEAN) | 切换目标元素的选中状态。force 是可选的，如果已定义，则确保结果状态与 force 的值相同。 |
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 | 关闭灯箱。 |
amp-lightbox-gallery
| 操作 | 描述 |
|---|---|
open | 打开灯箱画廊。如果指定图像 ID，可以通过点击另一个元素来触发：`on="tap:amp-lightbox-gallery.open(id='image-id')"`。 |
amp-list
| 操作 | 描述 |
|---|---|
changeToLayoutContainer | 将 amp-list 的布局更新为 layout="CONTAINER" 以允许 动态调整大小。 |
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-video 和其他视频元素
以下操作在 amp-video、amp-video-iframe 和 第三方视频播放器（如 amp-youtube）中受支持。
| 操作 | 描述 |
|---|---|
play | 播放视频。 |
pause | 暂停视频。 |
mute | 静音视频。 |
unmute | 取消静音视频。 |
fullscreenenter | 将视频切换到全屏。 |
form
| 操作 | 描述 |
|---|---|
clear | 清除表单输入中的所有值。 |
submit | 提交表单。 |
特殊目标
以下是 AMP 系统提供的具有特殊要求的目标
目标：AMP
AMP 目标由 AMP 运行时提供，并实现适用于整个文档的顶级操作。
| 操作 | 描述 | ||
|---|---|---|---|
navigateTo(url=STRING, target=STRING, opener=BOOLEAN) | 将当前窗口导航到给定的 URL，如果给定，则导航到可选指定的 target（当前仅支持 注意事项：建议尽可能使用正常的 | ||
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN) | 如果允许，则尝试关闭窗口，否则它会导航到类似于 警告：建议尽可能使用正常的 | ||
goBack(navigate=BOOLEAN) | 在历史记录中返回。`navigate`是可选的，如果设置为true，则允许跨文档导航，类似于[history.back](https://mdn.org.cn/en-US/docs/Web/API/History/back)。 | ||
print | 打开打印对话框以打印当前页面。 | ||
| scrollTo(id=STRING, duration=INTEGER, position=STRING) | 滚动到当前页面上提供的元素 ID。 | ||
| optoutOfCid | 选择退出所有范围的客户端 ID 生成。 | ||
setState({foo: 'bar'})1 | 需要amp-bind。 将一个对象字面量合并到可绑定状态中。 | ||
pushState({foo: 'bar'})1 | 需要amp-bind。 将一个对象字面量合并到可绑定状态中，并将一个新条目推送到浏览器历史记录堆栈中。弹出该条目将恢复变量的先前值（在本例中为 | ||
copy(text='content') | 将任何内容复制到剪贴板。 | toggleTheme() | 在调用时切换 body 元素上的 amp-dark-mode 类，并将用户偏好设置到 localStorage 中。基于prefers-color-scheme值，默认情况下 amp-dark-mode 类被添加到 body 中。在 body 标记上使用data-prefers-dark-mode-class属性来覆盖要用于暗模式的类。 |
1当与多个操作一起使用时，后续操作将在调用之前等待setState()或pushState()完成。每个事件只允许一个setState()或pushState()。
目标：amp-access
amp-access目标由amp-access组件提供。
amp-access目标由于以下原因而特殊
- 你不能给这个目标一个任意的 ID。目标始终是
amp-access。 amp-access的操作是动态的，具体取决于AMP Access 配置的结构。
有关使用amp-access目标的详细信息，请参见详细信息。