AMP

Hành động và sự kiện

Tài liệu này bàn về các hành động và sự kiện cho các website, câu chuyện và quảng cáo trong AMP. Đọc Hành động và sự kiện trong email AMP cho định dạng email AMP.

Thuộc tính on (bật) được sử dụng để cài đặt bộ xử lý sự kiện cho các yếu tố. Các sự kiện được hỗ trợ tùy thuộc vào yếu tố.

Giá trị cho cú pháp là một ngôn ngữ đơn giản dành riêng cho lĩnh vực của biểu mẫu:

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

Xem bảng dưới đây để biết mô tả về từng phần của cú pháp.

Cú pháp Bắt buộc? Mô tả
eventName Đây là tên của sự kiện được yếu tố hiển thị.
targetId Đây là DOM ID cho yếu tố, hoặc một mục tiêu đặc biệt được định nghĩa sẵn mà bạn muốn thực thi một hành động hoặc để đáp lại sự kiện. Trong ví dụ sau, targetId là DOM ID của mục tiêu amp-lightbox, photo-slides.
<amp-lightbox id="photo-slides"></amp-lightbox> <button on="tap:photo-slides">Show Images</button>
methodName không Dành cho các yếu tố với hành động mặc định.

Đây là phương thức được yếu tố mục tiêu (tham chiếu bởi targetId) hiển thị và bạn muốn thực thi khi sự kiện được kích hoạt.

AMP có một khái niệm về một hành động mặc định mà các yếu tố có thể triển khai. Vậy nên khi bỏ sót methodName, AMP sẽ thực thi phương thức mặc định đó.

arg=value không Một số hành động, nếu được ghi chép, có thể chấp nhận các tham số. Các tham số được định nghĩa giữa các ngoặc đơn trong chú thích key=value. Các giá trị được chấp nhận là:
  • các chuỗi đơn giản không được trích dẫn: simple-value
  • các chuỗi được trích dẫn: "string value" hoặc 'string value'
  • giá trị boolean: true hoặc false
  • số: 11 hoặc 1.1
  • Tham chiếu cú pháp dấu chấm cho dữ liệu sự kiện: event.someDataVariableName

Xử lý nhiều sự kiện

Bạn có thể lắng nghe nhiều sự kiện trên một yếu tố bằng cách chia tách các sự kiện bằng dấu chấm phẩy ;.

Ví dụ: on="submit-success:lightbox1;submit-error:lightbox2"

Nhiều hành động cho một sự kiện

Bạn có thể thực thi nhiều hành động lần lượt cho cùng một sự kiện bằng cách chia tách các hành động với một dấu phẩy ','.

Ví dụ: on="tap:target1.actionA,target2.actionB"

Các sự kiện và hành động được định nghĩa toàn cục

AMP định nghĩa một sự kiện tap (chạm) trên toàn cục mà bạn có thể lắng nghe trên mọi yếu tố HTML (bao gồm các yếu tố AMP).

AMP cũng định nghĩa các hành động hide (ẩn), show (hiển thị) và toggleVisibility (bật/tắt hiển thị) trên toàn cục mà bạn có thể kích hoạt trên mọi yếu tố HTML.

Một yếu tố chỉ có thể được hiển thị nếu trước đó nó đã bị ẩn bởi một hành động hide hoặc toggleVisibility, hoặc bằng cách sử dụng thuộc tính hidden (ẩn). Hành động show (hiển thị) không hỗ trợ các yếu tố bị ẩn bởi display:none (hiển thị:không) của CSS hoặc layout=nodisplay (bố cục=không hiển thị) của AMP.

Ví dụ, những việc sau có thể được thực hiện trong AMP:

<div id="warning-message">Warning...</div>

<button on="tap:warning-message.hide">Cool, thanks!</button>

Các sự kiện cụ thể của yếu tố

* - tất cả yếu tố

Sự kiện Mô tả
tap Kích hoạt khi yếu tố được nhấn/chạm vào.

Yếu tố đầu vào

Sự kiện Mô tả Yếu tố Dữ liệu
change Kích hoạt khi giá trị của yếu tố được thay đổi và cam kết.

Thuộc tính dữ liệu sao chép các thuộc tính trong 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 Kích hoạt khi giá trị của yếu tố được thay đổi. Điều này tương tự như sự kiện change (thay đổi) tiêu chuẩn, nhưng chỉ kích hoạt khi 300ms đã trôi qua sau khi giá trị của dữ liệu đầu vào đã ngừng thay đổi. Các yếu tố kích hoạt sự kiện input (nhập liệu). Giống như dữ liệu sự kiện change (thay đổi).
input-throttled Kích hoạt khi giá trị của yếu tố được thay đổi. Điều này tương tự như sự kiện change (thay đổi) tiêu chuẩn, nhưng bị hạn chế chỉ kích hoạt tối đa một lần sau mỗi 100ms trong khi giá trị của dữ liệu đầu vào đang thay đổi. Các yếu tố kích hoạt sự kiện input (nhập liệu). Giống như dữ liệu sự kiện change (thay đổi).

amp-accordion > phần

Sự kiện Mô tả Dữ liệu
expand Kích hoạt khi một phần accordion được mở rộng. Không có.
collapse Kích hoạt khi một phần accordion được thu hẹp. Không có.

amp-carousel[type="slides"]

Sự kiện Mô tả Dữ liệu
slideChange Kích hoạt khi slide hiện tại của băng chuyền được thay đổi.
// Slide number. event.index

amp-lightbox

Sự kiện Mô tả Dữ liệu
lightboxOpen Kích hoạt khi lightbox được hiển thị hoàn toàn. Không có
lightboxClose Kích hoạt khi lightbox được đóng hoàn toàn. Không có

amp-list

Sự kiện Mô tả Dữ liệu
changeToLayoutContainer Cập nhật bố cục của amp-list thành layout="CONTAINTER" để cho phép đổi kích cỡ năng động.
fetch-error(low-trust) Kích hoạt khi truy xuất dữ liệu thất bại. Không có

amp-selector

Sự kiện Mô tả Dữ liệu
select Kích hoạt khi một tùy chọn được chọn hoặc bỏ chọn.
// Target element's "option" attribute value. event.targetOption
// Array of "option" attribute values of all selected elements. event.selectedOptions

amp-sidebar

Sự kiện Mô tả Dữ liệu
sidebarOpen Kích hoạt khi thanh bên được mở hoàn toàn sau khi quá trình chuyển tiếp kết thúc. Không có
sidebarClose Kích hoạt khi thanh bên được đóng hoàn toàn sau khi quá trình chuyển tiếp kết thúc. Không có

amp-state

Sự kiện Mô tả Dữ liệu
fetch-error(low-trust) Kích hoạt khi truy xuất dữ liệu thất bại. Không có

amp-video, amp-youtube

Sự kiện Mô tả Dữ liệu
firstPlay(low-trust) Kích hoạt lần đầu tiên video được người dùng phát. Ở các video tự động phát, việc này được kích hoạt ngay khi người dùng tương tác với video. Đây là sự kiện có mức tin tưởng thấp, điều này có nghĩa nó không thể kích hoạt hầu hết các hành động; chỉ các hành động có mức tin tưởng thấp như amp-animation mới có thể được chạy.
timeUpdate(low-trust) Kích hoạt khi vị trí phát của một video được thay đổi. Tần suất của sự kiện được AMP kiểm soát và hiện được đặt ở chu kỳ 1 giây. Đây là sự kiện có mức tin tưởng thấp, điều này có nghĩa nó không thể kích hoạt hầu hết các hành động; chỉ các hành động có mức tin tưởng thấp như amp-animation mới có thể được chạy. {time, percent}time indicates the current time in seconds, percent is a number between 0 and 1 and indicates current position as percentage of total time.

form

Sự kiện Mô tả Dữ liệu
submit Kích hoạt khi biểu mẫu được gửi đi.
submit-success Kích hoạt khi gửi biểu mẫu thành công.
// Response JSON.
event.response
submit-error Kích hoạt khi gửi biểu mẫu thất bại.
// Response JSON.
event.response
valid Kích hoạt khi biểu mẫu là hợp lệ.
invalid Fired when the form is invalid.

Các hành động dành riêng cho yếu tố

* (tất cả yếu tố)

Hành động Mô tả
hide Hides the target element.
show Shows the target element. If an autofocus element becomes visible as a result, it gains focus.
toggleVisibility Bật/tắt hiển thị yếu tố mục tiêu. Nếu một yếu tố autofocus (tự động lấy tiêu điểm) được hiển thị, nó sẽ được lấy tiêu điểm.
toggleClass(class=STRING, force=BOOLEAN) Bật/tắt lớp của yếu tố mục tiêu. force (bắt buộc) là tùy chọn, nhưng nếu được định nghĩa, nó đảm bảo lớp này chỉ được thêm mà không bị xóa nếu đặt thành true (đúng), và chỉ bị xóa nhưng không được thêm nếu đặt thành false (sai).
scrollTo(duration=INTEGER, position=STRING) Cuộn một yếu tố vào màn hiển thị với một hình hoạt họa mượt mà.
duration (thời lượng) là không bắt buộc. Quy định thời lượng của hình hoạt họa tính theo mili giây. Nếu không quy định, một số tương đương với chênh lệch tốc độ cuộn thấp hơn hoặc bằng 500 mili giây sẽ được sử dụng.
position (vị trí) là không bắt buộc. Một trong các giá trị top (trên cùng), center (ở giữa) hoặc bottom (dưới cùng) (mặc định là top). Quy định vị trí của yếu tố tương đối với màn hiển thị sau khi cuộn.
Như một biện pháp thực hành tiên tiến nhất về hỗ trợ tiếp cận, ghép yếu tố này với một cuộc gọi focus() để tập trung vào yếu tố đang được cuộn đến.
focus Lấy tiêu điểm vào yếu tố mục tiêu. Để bỏ tiêu điểm, focus (tập trung) vào một yếu tố khác (thường là yếu tố cha). Chúng tôi đặc biệt khuyến cáo không giảm tiêu điểm bằng cách tập trung vào body/documentElement vì lý do hỗ trợ tiếp cận.

amp-audio

Hành động Mô tả
play Phát âm thanh. Không hoạt động nếu yếu tố là con của <amp-story>.
pause Tạm dừng âm thanh. Không hoạt động nếu yếu tố là con của <amp-story>.

amp-bodymovin-animation

Hành động Mô tả
play Phát hình hoạt họa.
pause Tạm dừng hình hoạt họa.
stop Dừng hình hoạt họa.
seekTo(time=INTEGER) Đặt currentTime của hình hoạt họa thành giá trị được quy định và tạm dừng hình hoạt họa.
seekTo(percent=[0,1]) Sử dụng giá trị phần trăm được cho để xác định currentTime của hình hoạt họa thành giá trị được quy định và tạm dừng hình hoạt họa.

amp-accordion

Hành động Mô tả
toggle(section=STRING) Bật/tắt trạng thái expanded (mở rộng) và collapsed (thu hẹp) của các phần amp-accordion. Khi được gọi mà không có tham số, nó sẽ bật/tắt tất cả các phần của accordion. Kích hoạt trên một phần cụ thể bằng cách cung cấp ID phần: on="tap:myAccordion.toggle(section=
expand(section=STRING) Mở rộng các phần của accordion. Nếu một phần đã được mở rộng rồi, nó vẫn sẽ được mở rộng. Khi được gọi mà không có tham số, nó sẽ mở rộng tất cả các phần của accordion. Kích hoạt trên một phần cụ thể bằng cách cung cấp ID phần: on="tap:myAccordion.expand(section='section-id')".
collapse(section=STRING) Thu hẹp các phần của accordion. Nếu một phần đã được thu hẹp rồi, nó vẫn sẽ được thu hẹp. Khi được gọi mà không có tham số, nó sẽ thu hẹp tất cả các phần của accordion. Kích hoạt trên một phần cụ thể bằng cách cung cấp ID phần: on="tap:myAccordion.collapse(section='section-id')".

amp-carousel[type="slides"]

Hành động Mô tả
goToSlide(index=INTEGER) Chuyển băng chuyền đến một thứ tự slide cụ thể.
toggleAutoplay(toggleOn=true|false) Bật/tắt trạng thái tự động phát của băng chuyền. toggleOn là không bắt buộc.

amp-image-lightbox

Hành động Mô tả
open (default) Mở lightbox ảnh với ảnh nguồn là ảnh đã kích hoạt hành động này.

amp-lightbox

Hành động Mô tả
open (default) Mở lightbox.
close Đóng lightbox.
Hành động Mô tả
open Mở thư viện lightbox. Có thể được kích hoạt bằng cách chạm vào một yếu tố khác, nếu bạn quy định id ảnh: `on="tap:amp-lightbox-gallery.open(id='image-id')"`.

amp-list

Hành động Mô tả
refresh Làm mới dữ liệu từ src và render lại danh sách.

amp-live-list

Hành động Mô tả
update (default) Cập nhật các mục DOM để hiển thị nội dung được cập nhật.

amp-selector

Hành động Mô tả
clear Xóa tất cả các lựa chọn từ một amp-selector đã quy định.
selectUp(delta=INTEGER) Di chuyển lựa chọn về phía trước theo giá trị của `delta`. `delta` mặc định được đặt là -1. Nếu không có tùy chọn nào được chọn, trạng thái được chọn sẽ trở thành giá trị của tùy chọn gần nhất.
selectDown(delta=INTEGER) Di chuyển lựa chọn về phía sau theo giá trị của `delta`. `delta` mặc định được đặt là 1. Nếu không có tùy chọn nào được chọn, trạng thái được chọn sẽ trở thành giá trị của tùy chọn đầu tiên.
toggle(index=INTEGER, value=BOOLEAN) Bật/tắt mục `selected` (được chọn). Nếu không có thuộc tính được chọn, hành động này sẽ bổ sung nó. Nếu có thuộc tính được chọn, hành động này sẽ xóa nó. Bạn có thể bắt buộc và duy trì thêm hoặc xóa bằng cách thêm một giá trị boolean trong tham số `value` (giá trị). Một giá trị `true` (đúng) sẽ bắt buộc thêm thuộc tính `selected` (được chọn) và không xóa nó nếu nó đã được chọn. Một giá trị `false` (sai) sẽ xóa thuộc tính, và không thêm nó nếu nó không được chọn.

amp-sidebar

Hành động Mô tả
open (default) Mở thanh bên.
close Đóng thanh bên.
toggle Bật/tắt trạng thái của thanh bên.

amp-state

Hành động Mô tả
refresh Truy xuất lại dữ liệu tại thuộc tính `src`, đồng thời bỏ qua bộ nhớ đệm của trình duyệt.

amp-user-notification

Hành động Mô tả
dismiss (default) Ẩn yếu tố thông báo người dùng được tham chiếu.

Yếu tố video

Các hành động dưới đây được hỗ trợ trong các yếu tố video AMP sau đây: amp-video, amp-youtube, amp-3q-player, amp-brid-player, amp-dailymotion, amp-delight-player, amp-ima-video.

Hành động Mô tả
play Phát video.
pause Tạm dừng video.
mute Tắt tiếng video.
unmute Bỏ tắt tiếng video.
fullscreencenter Hiển thị video toàn màn hình.

form

Hành động Mô tả
clear Xóa mọi giá trị dữ liệu đầu vào của biểu mẫu.
submit Gửi biểu mẫu.

Mục tiêu đặc biệt

Sau đây là các mục tiêu được cung cấp bởi hệ thống AMP với các yêu cầu đặc biệt:

Mục tiêu: AMP

Mục tiêu AMP được cung cấp bởi thời gian chạy AMP và triển khai các hành động ở cấp độ cao nhất, áp dụng cho toàn tài liệu.

Hành động Mô tả
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

Điều hướng cửa sổ hiện tại đến URL được cho, đến mục tiêu được quy định (không bắt buộc) nếu được cho (hiện tại chỉ hỗ trợ _top (trên cùng) và _blank (trống)). Tham số opener (mở) có thể được quy định khi sử dụng mục tiêu là _blank (trống) để cho phép các trang mới được mở truy cập window.opener. Hỗ trợ thay thế URL tiêu chuẩn.

Lưu ý: Nên sử dụng các liên kết <a> bất cứ khi nào có thể bởi AMP.navigateTo không được các web crawler công nhận.

closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)

Cố đóng cửa sổ nếu được cho phép, nếu không, nó sẽ điều hướng tương tự như Hành động navigateTo. Hữu ích cho các trường hợp sử dụng ở đó một nút "Quay lại" có thể là cần thiết để đóng cửa sổ nếu nó được mở trong một cửa sổ mới từ trang trước đó hoặc điều hướng nếu nó không được mở.

Lưu ý: Sử dụng bình thường<a> liên kết được khuyến nghị nếu có thể vì AMP.closeOrNavigateTo không được trình thu thập dữ liệu web nhận dạng.

goBack Về trang trước trong lịch sử.
print Mở Hộp thoại In để in trang hiện tại.
scrollTo(id=STRING, duration=INTEGER, position=STRING) Cuộn đến ID yếu tố được cung cấp trên trang hiện tại.
optoutOfCid Hủy tạo ID Máy khách cho tất cả phạm vi.
setState({foo: 'bar'})1

Yêu cầu amp-bind.

Hợp nhất một object literal vào một trạng thái ràng buộc được.

pushState({foo: 'bar'})1

Yêu cầu amp-bind.

Hợp nhất một object literal vào một trạng thái ràng buộc được và đẩy một mục mới vào danh sách lịch sử trình duyệt. Việc đẩy mục này sẽ khôi phục các giá trị trước đó của biến số (trong ví dụ này là foo).

1Khi được sử dụng với nhiều hành động, các hành động sau đó sẽ chờ setState() hoặc pushState() hoàn thành trước khi kích hoạt. Chỉ một setState() hoặc pushState() được cho phép cho mỗi sự kiện.

Mục tiêu: amp-access

Mục tiêu amp-access được cung cấp bởi thành phần amp-access.

Mục tiêu amp-access là mục tiêu đặc biệt vì các lý do sau:

  1. Bạn không thể cung cấp ID tùy chỉnh cho mục tiêu này. Mục tiêu này luôn là amp-access.
  2. Các hành động cho amp-access là năng động tùy thuộc vào cấu trúc của Cấu hình Truy cập AMP.

Xem chi tiết về việc sử dụng mục tiêu amp-access.