- 處理多個事件
- 一個事件的多個動作
- 全域定義的事件和動作
- 元素特定的事件
- 元素特定的動作
- * (所有元素)
- amp-audio (音訊)
- amp-bodymovin-animation (Bodymovin 動畫)
- amp-accordion (手風琴選單)
- amp-carousel[type="slides"] (輪播跑馬燈 [類型="幻燈片"])
- amp-image-lightbox (圖片燈箱)
- amp-lightbox (燈箱)
- amp-lightbox-gallery (燈箱藝廊)
- amp-list (列表)
- amp-live-list (即時列表)
- amp-selector (選擇器)
- amp-sidebar (側邊欄)
- amp-state (狀態)
- amp-user-notification (使用者通知)
- amp-video 和其他影片元素
- form (表單)
- 特殊目標
動作和事件
此文件涵蓋 AMP 網站、故事和廣告的動作和事件。請閱讀AMP 電子郵件中的動作和事件，以了解 AMP 電子郵件格式。
on 屬性用於在元素上安裝事件處理常式。支援的事件取決於元素。
此語法的數值是一種簡單的網域特定語言，格式如下
eventName:targetId[.methodName[(arg1=value, arg2=value)]]
請參閱下表以了解語法各部分的說明。
| 語法 | 是否必要？ | 說明 |
|---|---|---|
eventName (事件名稱) | 是 | 這是元素公開的事件名稱。 |
targetId (目標 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 (方法名稱) | 否 | 這適用於具有預設動作的元素。 這是目標元素 (由 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(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-video、amp-video-iframe 和 第三方影片播放器 (例如 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 (隱藏) | 隱藏目標元素。 |
show (顯示) | 顯示目標元素。如果 autofocus 元素 因此變成可見，則它會取得焦點。 |
toggleVisibility (切換可見性) | 切換目標元素的可見性。如果 autofocus 元素 因此變成可見，則它會取得焦點。 |
toggleClass(class=STRING, force=BOOLEAN) (切換類別) (類別=字串，強制=布林值) | 切換目標元素的類別。force 是選用項目，如果已定義，則確保類別僅會新增但不會移除 (如果設定為 true)，並且僅會移除但不會新增 (如果設定為 false)。 |
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 (Bodymovin 動畫)
| 動作 | 說明 |
|---|---|
play (播放) | play (播放) |
pause (暫停) | pause (暫停) |
stop (停止) | 停止動畫。 |
seekTo(time=INTEGER) (跳轉至) (時間=整數) | 將動畫的 currentTime (目前時間) 設定為指定的值並暫停動畫。 |
seekTo(percent=[0,1]) (跳轉至) (百分比=[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) (切換自動播放) (切換開啟=true|false) | 切換輪播跑馬燈的自動播放狀態。toggleOn 為選用項目。 |
amp-image-lightbox (圖片燈箱)
| 動作 | 說明 |
|---|---|
open (開啟) (預設) | 開啟圖片燈箱，來源圖片是觸發動作的圖片。 |
amp-lightbox (燈箱)
| 動作 | 說明 |
|---|---|
open (開啟) (預設) | open (開啟) |
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 (更新) (預設) | 更新 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 (開啟) (預設) | open (開啟) |
close (關閉) | close (關閉) |
toggle (切換) | 切換側邊欄的狀態。 |
amp-state (狀態)
| 動作 | 說明 |
|---|---|
refresh (重新整理) | refetch (重新擷取) |
在忽略瀏覽器快取的情況下，重新擷取 src 屬性中的資料。
| 動作 | 說明 |
|---|---|
amp-user-notification (使用者通知) | dismiss (關閉) (預設) |
amp-video 和其他影片元素
以下動作在 amp-video、amp-video-iframe 和 第三方影片播放器 (例如 amp-youtube) 中受到支援。
| 動作 | 說明 |
|---|---|
play (播放) | play (播放) |
pause (暫停) | pause (暫停) |
mute (靜音) | 將影片靜音。 |
unmute (取消靜音) | 取消影片靜音。 |
fullscreenenter (進入全螢幕) | 將影片設為全螢幕。 |
form (表單)
| 動作 | 說明 |
|---|---|
clear (清除) | clear (清除) |
submit (提交) | submit (提交) |
特殊目標
以下是 AMP 系統提供的目標，它們具有特殊需求
目標：AMP
AMP 目標由 AMP 執行階段提供，並實作適用於整個文件的最上層動作。
| 動作 | 說明 | ||
|---|---|---|---|
navigateTo(url=STRING, target=STRING, opener=BOOLEAN) (導覽至) (網址=字串，目標=字串，開啟器=布林值) | 將目前視窗導覽至指定的網址，如果已指定，則導覽至選用的指定目標 (目前僅支援 注意事項： 建議盡可能使用一般的 | ||
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN) (關閉或導覽至) (網址=字串，目標=字串，開啟器=布林值) | 如果允許，則嘗試關閉視窗，否則它會以類似於 注意事項： 建議盡可能使用一般的 | ||
goBack(navigate=BOOLEAN) (返回) (導覽=布林值) | 在歷史記錄中返回。navigate 為選用項目，如果設定為 true，則允許跨文件導覽，類似於 [history.back](https://developer.mozilla.org/en-US/docs/Web/API/History/back)。 | ||
print (列印) | 開啟「列印」對話方塊以列印目前頁面。 | ||
| scrollTo(id=STRING, duration=INTEGER, position=STRING) (捲動至) (ID=字串，持續時間=整數，位置=字串) | 捲動至目前頁面上提供的元素 ID。 | ||
| optoutOfCid (退出用戶端 ID) | 退出所有範圍的用戶端 ID 產生。 | ||
setState({foo: 'bar'})1 | 需要 amp-bind。 將物件常值合併到可繫結狀態。 | ||
pushState({foo: 'bar'})1 | 需要 amp-bind。 將物件常值合併到可繫結狀態，並將新項目推送至瀏覽器歷史記錄堆疊。彈出項目將還原變數 (在此範例中為 | ||
copy(text='content') (複製) (文字='內容') | 將任何內容複製到剪貼簿。 | toggleTheme() (切換主題) | 在呼叫時切換 body 元素上的 amp-dark-mode 類別，並將使用者偏好設定設為 localStorage。amp-dark-mode 類別依預設會根據 prefers-color-scheme 值新增至 body。在 body 標籤上使用 data-prefers-dark-mode-class 屬性來覆寫用於深色模式的類別。 |
1當與多個動作一起使用時，後續動作將等待 setState() 或 pushState() 完成後再叫用。每個事件僅允許單一 setState() 或 pushState()。
目標：amp-access (AMP 存取權)
amp-access 目標由 amp-access 元件提供。
amp-access 目標因以下原因而特殊
- 您無法為此目標指定任意 ID。目標永遠是
amp-access。 amp-access的動作是動態的，具體取決於 AMP 存取權設定的結構。
請參閱關於使用 amp-access 目標的詳細資訊。