AMP
KO
English 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">이미지 표시</button>
methodName 선택 사항 기본 액션이 있는 요소에 사용됩니다.

대상 요소(targetId로 참조됨)가 표시하고 이벤트가 트리거될 시 실행하고자 하는 메소드입니다.

AMP에는 요소가 구현할 수 있는 기본 액션의 개념이 있습니다. 그러므로 methodName이 누락될 경우 AMP는 기본 메소드를 실행합니다.
arg=value 선택 사항 일부 액션에서는 문서화된 경우 인수가 허용될 수 있습니다. key=value 노테이션에서 인수는 괄호 사이에 정의됩니다. 허용 값은 다음과 같습니다:
  • 따옴표가 없는 단순한 문자열: simple-value
  • 따옴표가 있는 문자열: "string value" 또는 'string value'
  • 불 값: true 또는 false
  • 숫자: 11 또는1.1
  • 이벤트 데이터로 dot-syntax 참조: event.someDataVariableName

여러 이벤트 처리

세미콜론 ;으로 이벤트를 구분하여 요소의 여러 이벤트를 리스닝할 수 있습니다.

예시: on="submit-success:lightbox1;submit-error:lightbox2"

단일 이벤트의 여러 액션

쉼표 ','로 액션을 구분하여 동일한 이벤트의 여러 액션을 실행할 수 있습니다.

예시: on="tap:target1.actionA,target2.actionB"

전역으로 정의된 이벤트 및 액션

AMP는 모든 HTML 요소(AMP 요소 포함)에서 리스닝할 수 있는 tap 이벤트를 전역으로 정의합니다.

또한 AMP는 모든 HTML 요소에서 트리거할 수 있는 hide, show 및toggleVisibility 액션도 전역으로 정의합니다.

요소는 이전에 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마다 1회씩 실행하도록 조절됩니다. input 이벤트를 발생시키는 요소. change 이벤트 데이터와 동일.

amp-accordion > 섹션

이벤트 설명 데이터
expand 아코디언 섹션이 확장할 시 발생합니다. 없음.
collapse 아코디언 섹션이 축소할 시 발생합니다. 없음.

amp-carousel[type="slides"]

이벤트 설명 데이터
slideChange 캐러셀의 현재 슬라이드가 변경될 시 발생합니다. 
// Slide number.
event.index

amp-lightbox

이벤트 설명 데이터
lightboxOpen 라이트박스가 완전히 표시될 시 발생합니다. 없음
lightboxClose 라이트박스가 완전히 닫혔을 시 발생합니다. 없음

amp-list

이벤트 설명 데이터
changeToLayoutContainer amp-list 레이아웃을 layout="CONTAINTER"로 업데이트하여 동적 크기 변경을 허용합니다.
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-youtube

이벤트 설명 데이터
firstPlay(신뢰도 낮음) 사용자가 동영상을 최초로 재생할 시 발생합니다. 자동 재생 영상의 경우 사용자가 동영상과 상호작용하는 즉시 발생합니다. 신뢰도가 낮은 이벤트로 대부분의 액션을 트리거할 수 없습니다. amp-animation 액션처럼 신뢰도가 낮은 액션만 실행 가능합니다.
timeUpdate(신뢰도 낮음) 동영상 위치가 최초로 변경되었을 시 발생합니다. 이벤트 빈도는 AMP가 제어하며 현재 1초 간격으로 설정되어 있습니다. 신뢰도가 낮은 이벤트로 대부분의 액션을 트리거할 수 없습니다. amp-animation 액션처럼 신뢰도가 낮은 액션만 실행 가능합니다. {time, percent}time은 현재 시간을 초 단위로 표시하며 percent는 0-1 사이의 숫자이며 현재 위치를 전체 시간의 비율로 표시합니다.

양식

이벤트 설명 데이터
submit 양식 제출 시 발생합니다.
submit-success 양식 제출 응답이 성공적으로 완료될 경우 발생합니다. 
// Response JSON.
event.response
submit-error 양식 제출 응답이 오류일 경우 발생합니다. 
// Response JSON.
event.response
valid 양식이 유효할 경우 발생합니다.
invalid 양식이 유효하지 않을 경우 발생합니다.

요소별 액션

* (모든 요소)

액션 설명
hide 대상 요소를 숨깁니다.
show Shows the target element. If an autofocus element becomes visible as a result, it gains focus.
toggleVisibility 대상 요소의 가시성 옵션을 변경합니다. 결과적으로 autofocus 요소가 표시되면 포커스를 받습니다.
toggleClass(class=STRING, force=BOOLEAN) 대상 요소의 클래스 옵션을 변경합니다. force는 선택 사항이며 정의된 경우 클래스가 true로 설정되었을 시 추가만 가능하며 제거되지는 않도록, false로 설정되었을 시 제거만 가능하며 추가되지는 않도록 합니다.
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 애니메이션을 재생합니다.
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=n.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 (default) 액션을 트리거한 소스 이미지가 포함된 이미지 라이트박스를 엽니다.

amp-lightbox

액션 설명
open (default) 라이트박스를 엽니다.
close 라이트박스를 닫습니다.
액션 설명
open lightbox-gallery를 엽니다. 이미지 ID를 `on="tap:amp-lightbox-gallery.open(id='image-id')"`로 지정하면 다른 요소를 탭하여 트리거될 수도 있습니다.

amp-list

액션 설명
refresh src의 데이터를 새로고침하고 목록을 다시 렌더링합니다.

amp-live-list

액션 설명
update (default) 업데이트된 콘텐츠를 표시하도록 DOM 항목을 업데이트합니다.

amp-selector

액션 설명
clear 정의된 amp-selector의 모든 선택 항목을 삭제합니다.
selectUp(delta=INTEGER) 모든 선택 항목이 `delta` 값만큼 위로 이동합니다. 기본 `delta` 값은 -1로 설정되어 있습니다. 선택한 옵션이 없으면 선택한 상태가 마지막 옵션의 값이 됩니다.
selectDown(delta=INTEGER) 모든 선택 항목이 `delta` 값만큼 아래로 이동합니다. 기본 `delta` 값은 1로 설정되어 있습니다. 선택한 옵션이 없으면 선택한 상태가 첫 번째 옵션의 값이 됩니다.
toggle(index=INTEGER, value=BOOLEAN) `selected` 항목의 적용 옵션을 전환합니다. 선택한 속성이 없으면 이 액션이 속성을 추가합니다. 선택한 속성이 있으면 액션이 속성을 제거합니다. `value` 인수에 불 값을 포함하여 추가 또는 제거를 강제하거나 유지할 수 있습니다. `true` 값은 `selected` 속성 추가를 강제하고 이미 해당 속성이 있는 경우 제거하지 않습니다. `false` 값은 속성을 제거하지만 속성이 없는 경우 추가하지 않습니다.

amp-sidebar

액션 설명
open (default) 사이드바를 엽니다.
close 사이드바를 닫습니다.
toggle 사이드바 상태를 전환합니다.

amp-state

액션 설명
refresh `src` 속성의 데이터를 다시 가져오고 브라우저 캐시를 무시합니다.

amp-user-notification

액션 설명
dismiss (default) 참조된 사용자 알림 요소를 숨김 처리합니다.

동영상 요소

아래의 액션은 다음 AMP 동영상 요소에서 지원됩니다: amp-video, amp-youtube, amp-3q-player, amp-brid-player, amp-dailymotion, amp-delight-player, amp-ima-video.

액션 설명
play 동영상을 재생합니다.
pause 동영상을 중지합니다.
mute 동영상 소리를 끕니다.
unmute 동영상 소리를 다시 켭니다.
fullscreencenter 동영상을 전체 화면으로 표시합니다.

양식

액션 설명
clear 양식의 입력 필드의 값을 삭제합니다.
submit 양식을 제출합니다.

특정 대상

다음은 특정한 요건이 있는 AMP 시스템에서 제공하는 대상입니다.

대상: AMP

AMP 런타임이 제공하는 AMP 대상은 전체 문서에 적용되는 최상위 액션을 구현합니다.

액션 설명
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

현재 창에서 지정된 URL로 이동하며 지정된 경우 선택적 대상으로 이동합니다(현재 _top 및 _blank 만 지원). 새로 연 페이지에서 window.opener 액세스를 허용하기 위해 _blank 대상을 사용할 경우 opener 매개변수를 선택적으로 지정할 수 있습니다. 표준 URL 대체를 지원합니다.

주의: 웹 크롤러는 AMP.navigateTo를 인식할 수 없으므로 가능하다면 일반 <a> 링크 사용이 권장됩니다.
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)

허용된 경우 창 닫기를 시도하고 그렇지 않으면 navigateTo 액션과 유사하게 이동합니다. 이전 페이지의 새 창에서 창이 열려 닫아야 할 경우 혹은 창이 열리지 않아 이동해야 할 경우에 "뒤로" 버튼이 필요한 사용 사례에 유용합니다.

주의: 웹 크롤러는 AMP.closeOrNavigateTo를 인식할 수 없으므로 가능하다면 일반 <a> 링크 사용이 권장됩니다.
goBack 기록에서 뒤로 이동합니다.
print 출력 대화상자를 열어 현재 페이지를 출력합니다.
scrollTo(id=STRING, duration=INTEGER, position=STRING) 현재 페이지의 제공된 요소 ID로 스크롤하여 이동합니다.
optoutOfCid 모든 범위에서 클라이언트 ID 생성 옵션을 선택 해제합니다.
setState({foo: 'bar'})1

amp-bind가 필요합니다.

객체 리터럴을 바인딩 가능 상태로 병합합니다.
pushState({foo: 'bar'})1

amp-bind가 필요합니다.

객체 리터럴을 바인딩 가능한 상태로 병합하고 새 항목을 브라우저 기록 스택에 푸시합니다. 항목이 표시되면 이전 변수 값을 복원합니다(이 사례의 경우 foo).

1여러 액션과 함께 사용되는 경우 후속 액션은 호출 전 setState() 또는pushState()이 완료되도록 대기합니다. 이벤트당 하나의 setState() 또는 pushState()만이 허용됩니다.

대상: amp-access

amp-access 대상은 amp-access 컴포넌트가 제공합니다.

amp-access 대상은 다음과 같은 상황에 적합합니다.

  1. 대상에 임의의 ID를 지정할 수 없을 시 대상이 항상 amp-access일 경우.
  2. AMP 액세스 구성에 따라 amp-access 액션이 동적일 경우.

amp-access 대상 사용에 관련한 자세한 내용을 확인하세요.