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`	có	Đây là tên của sự kiện được yếu tố hiển thị.
`targetId`	có	Đâ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 HTMLInputElement và 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`	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

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

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.

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'})`¹	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'})`¹	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`).

¹Khi đượ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:

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.
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.

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

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

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

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

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

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

Yếu tố đầu vào

amp-accordion > phần

amp-carousel[type="slides"]

amp-lightbox

amp-list

amp-selector

amp-sidebar

amp-state

amp-video, amp-youtube

form

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

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

amp-audio

amp-bodymovin-animation

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

Yếu tố video

form

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

Mục tiêu: AMP

Mục tiêu: amp-access