AMP

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

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

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

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

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

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

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

语法 是否为必需项? 说明
eventName 元素公开的事件的名称。
targetId 元素的 DOM ID,或者是为了对事件做出响应而要执行操作的预定义特殊目标的 DOM ID。在以下示例中,targetIdamp-lightbox 目标 photo-slides 的 DOM ID。

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

事件 说明 数据
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 部分在 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) 前进到轮播中的指定幻灯片索引。

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()