AMP 電子郵件中的動作和事件
重要提示：此文件不適用於您目前選取的網站格式！
此文件涵蓋 AMP 電子郵件格式的動作和事件。請參閱動作和事件，瞭解 AMP 網站、Web 故事和廣告的相關資訊。
on 屬性用於在元素上安裝事件處理常式。支援的事件取決於元素。
語法的值是一種簡單的特定領域語言，其形式為
eventName:targetId[.methodName[(arg1=value, arg2=value)]]
請參閱下表，瞭解語法每個部分的說明。
| 語法 | 是否必要？ | 描述 |
|---|---|---|
eventName | 是 | 這是元素公開的事件名稱。 |
targetId | 是 | 這是元素的 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 | 否 | 這是用於具有預設動作的元素。 這是目標元素 (由 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 | 在點擊/輕觸元素時觸發。 |
輸入元素
| 事件 | 描述 | 元素 | 資料 |
|---|---|---|---|
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(低信任度) | 在擷取資料失敗時觸發。 | 無 |
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) | 切換目標元素的類別。force 為選用引數，如有定義，則可確保在設為 true 時只會新增類別，但不會移除，而設為 false 時則只會移除，但不會新增。 |
toggleChecked(force=BOOLEAN) | 切換目標元素的勾選狀態。force 為選用引數，如有定義，則可確保產生的狀態與 force 的值相同。 |
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 (預設) | 開啟圖片燈箱，來源圖片是觸發動作的圖片。 |
amp-lightbox
| 動作 | 描述 |
|---|---|
open (預設) | 開啟燈箱。 |
close | 關閉燈箱。 |
amp-list
| 動作 | 描述 |
|---|---|
changeToLayoutContainer | 將 amp-list 的版面配置更新為 layout="CONTAINER"，以允許動態調整大小。 |
refresh | 從 src 重新整理資料，並重新呈現清單。 |
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 (預設) | 開啟側邊欄。 |
close | 關閉側邊欄。 |
toggle | 切換側邊欄的狀態。 |
form
| 動作 | 描述 |
|---|---|
clear | 清除表單輸入中的任何值。 |
submit | 提交表單。 |
特殊目標
以下是 AMP 系統提供的目標，具有特殊需求
目標：AMP
AMP 目標由 AMP 執行階段提供，並實作適用於整個文件的頂層動作。
| 動作 | 描述 |
|---|---|
setState({foo: 'bar'})1 | 需要 amp-bind。 將物件常值合併至可繫結狀態。 |
1與多個動作搭配使用時，後續動作會等待 setState() 完成後再叫用。每個事件僅允許單一 setState()。