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

動作和事件

本文件涵蓋 AMP 網站、故事和廣告的動作和事件。請閱讀AMP 電子郵件中的動作和事件，以瞭解 AMP 電子郵件格式。

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 否 這適用於具有預設動作的元素。

這是目標元素 (由 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 在元素被點擊/輕觸時觸發。
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) 切換目標元素的類別。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

動作 說明
play play
pause 播放動畫。
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 (預設)

動作 說明
切換輪播的自動播放狀態。toggleOn 是選用的。 開啟圖片燈箱，來源圖片是觸發動作的圖片。
amp-lightbox 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。如果未選取任何選項，選取狀態將變成第一個選項的值。

動作 說明
切換輪播的自動播放狀態。toggleOn 是選用的。 toggle(index=INTEGER, value=BOOLEAN)
amp-lightbox 切換 selected 的應用。如果選取屬性不存在，此動作會新增它。如果選取屬性存在，此動作會移除它。您可以透過在 `value` 引數中包含布林值來強制並保持新增或移除。值為 `true` 將強制新增 `selected` 屬性，且即使已存在也不會移除它。值為 `false` 將移除屬性，但即使不存在也不會新增它。
amp-sidebar open

開啟側邊欄。

動作 說明
amp-list close

關閉側邊欄。

動作 說明
toggle 切換側邊欄的狀態。

amp-state

refresh

動作 說明
play 重新擷取 src 屬性的資料，同時忽略瀏覽器快取。
pause amp-user-notification
dismiss (預設) 隱藏參照的使用者通知元素。
amp-video 和其他影片元素 以下動作在 amp-video、amp-video-iframe 和 第三方影片播放器 (例如 amp-youtube) 中受到支援。
play 播放影片。

pause

動作 說明
update (預設) 暫停影片。
submit mute

將影片靜音。

unmute

取消影片靜音。

fullscreenenter

動作 說明
將影片設為全螢幕。

form

clear
清除表單輸入中的任何值。

submit

提交表單。
特殊目標 以下是 AMP 系統提供的目標，具有特殊需求
目標：AMP AMP 目標由 AMP 執行階段提供，並實作適用於整個文件的最上層動作。
navigateTo(url=STRING, target=STRING, opener=BOOLEAN) 將目前視窗導覽至給定的 URL，如果已給定，則導覽至選用的指定目標 (目前僅支援 _top 和 _blank)。使用 _blank 目標時，可以指定選用的 opener 參數，以允許新開啟的頁面存取 window.opener。
注意事項：建議盡可能使用一般的 <a> 連結，因為網路爬蟲程式無法辨識 AMP.navigateTo。 closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)
嘗試關閉視窗 (如果允許)，否則會以類似於 navigateTo 動作的方式導覽。適用於「返回」按鈕可能需要關閉視窗 (如果視窗是從上一個頁面在新視窗中開啟) 或導覽 (如果視窗不是開啟的) 的使用案例。

注意事項：建議盡可能使用一般的 <a> 連結，因為網路爬蟲程式無法辨識 AMP.closeOrNavigateTo。

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。

 optoutOfCid 針對所有範圍選擇退出用戶端 ID 產生。

setState({foo: 'bar'})1

需要 amp-bind。

將物件常值合併到可繫結狀態。

pushState({foo: 'bar'})1

  1. 需要 amp-bind。
  2. 將物件常值合併到可繫結狀態，並將新項目推送至瀏覽器歷史記錄堆疊。彈出項目將還原變數 (在此範例中為 foo) 的先前值。

copy(text='content')