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

AMP 电子邮件中的操作和事件

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

本文档介绍适用于 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

事件 说明 数据
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) 提取数据失败时触发。 无

表单

事件 说明 数据
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) 切换目标元素的类。force 为可选项，如果定义该属性，可确保在该属性设为 true 时仅添加类而不移除类，在该属性设为 false 时仅移除类而不添加类。
focus 使目标元素获得焦点。要取消焦点，可以 focus 其他元素（通常为父元素）。出于无障碍功能考虑，我们强烈建议将焦点置于 body/documentElement，而不要取消焦点。

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) 前进到轮播中的指定幻灯片索引。

amp-image-lightbox

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

amp-lightbox

操作 说明
open (default) 打开灯箱。
close 关闭灯箱。

amp-list

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

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 切换边栏的状态。

表单

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

特殊目标

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

目标：AMP

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

操作 说明
setState({foo: 'bar'})1

需要 amp-bind。

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

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