跳到內容
安裝應用程式
繁體中文

事件

應用程式在店面上觸發的五個事件,每個都附有實際範例。

應用程式會在 document 上觸發這些事件,因此請使用 document.addEventListener 監聽。請將程式碼放在佈景主題資源中,或放在 theme.liquid 的 </body> 上方。

事件detail觸發時機
gpoRenderCompleted{ form, product }選項完成渲染時
gpoElementChanged{}顧客變更選項時
gpoProductPriceUpdated{}重新計算顯示價格時
gpoValidated{ success }加入購物車時執行驗證
gpoAddedToCart{}商品及其附加項已加入購物車時

gpoRenderCompleted

在選項欄位出現在 DOM 中後觸發。這是建置功能時應該使用的事件。 應用程式以非同步方式渲染,因此在 DOMContentLoaded 時執行的程式碼會在選項出現之前執行,找不到任何東西。

detail 包含 form(選項渲染所在的商品表單)以及 product(選項所屬的商品)。

document.addEventListener('gpoRenderCompleted', function (event) {
const { form, product } = event.detail;
if (!form) return; // 此商品沒有適用的選項組
// 現在可以安全地查詢選項欄位
form.querySelectorAll('.gpo-form__group').forEach(function (group) {
group.classList.add('my-theme-option');
});
});

每當選項重新渲染時都會再次觸發,例如在會重新渲染商品的佈景主題上切換子類後,或在您呼叫 GPOConfigs.initialize() 之後。請確保處理函式執行兩次也不會造成問題。

gpoElementChanged

每次顧客變更選項時觸發:在欄位中輸入、選擇色票、勾選核取方塊。

document.addEventListener('gpoElementChanged', function () {
const engraving = document.querySelector('[name="properties[Engraving text]"]');
const note = document.querySelector('.my-engraving-note');
if (!engraving || !note) return;
note.hidden = engraving.value.trim() === '';
});

在文字欄位中每按一個鍵都會觸發,因此任何耗費資源的動作(網路請求、大量重新排版)都請加上防抖(debounce)處理。

gpoProductPriceUpdated

在應用程式改寫顯示價格以納入顧客所選的選項後觸發。可用來讓您自己的價格顯示保持同步,例如固定列、摘要區塊、分期付款估算。

document.addEventListener('gpoProductPriceUpdated', function () {
const main = document.querySelector('[data-gpo-product-unit-price]');
const sticky = document.querySelector('.my-sticky-bar .price');
if (main && sticky) sticky.textContent = main.textContent;
});

頁面上顯示的價格只是預覽。顧客實際支付的金額是由 Shopify 在結帳時套用,因此絕對不要把這個數字當作最終金額。請參閱定價的套用方式。

gpoValidated

在顧客嘗試加入購物車且應用程式已檢查選項時觸發。當有問題時(必填選項為空、超過字元數限制、選擇數量太少),detail.success 為 false。

document.addEventListener('gpoValidated', function (event) {
if (event.detail.success) return;
// 加入購物車已被阻擋
if (window.analytics) {
window.analytics.track('Option validation failed', {
product: window.GPOConfigs?.product?.handle
});
}
});

開啟 Auto-scroll to first error message(自動捲動至第一則錯誤訊息)時,應用程式已會捲動到第一個錯誤,因此您不需要自行處理。請參閱小工具行為。

gpoAddedToCart

在商品及任何附加項商品都已加入後觸發。此時購物車才真正發生變化,因此這裡是開啟購物車與進行分析追蹤的正確位置。

document.addEventListener('gpoAddedToCart', function () {
fetch(window.Shopify.routes.root + 'cart.js')
.then(function (res) { return res.json(); })
.then(function (cart) {
document.querySelector('.my-cart-count').textContent = cart.item_count;
});
});

以商品為基礎的附加項是獨立的購物車品項,因此一次加入購物車可能會新增多個品項。請重新讀取購物車,而不要假設只加入了一個商品。請參閱合併主商品與附加項。

注意事項

  • 這五個事件都需要啟用應用程式嵌入。未啟用時應用程式完全不會執行,也不會觸發任何事件。
  • 這些事件不會攜帶頁面上已有資料以外的任何顧客資料。商品、購物車與顧客資料請讀取 window.GPOConfigs。
  • 您在這裡附加的程式碼需要由您自行維護;在佈景主題或應用程式更新後店面運作異常時,這也是第一個要檢查的地方。

這個頁面有幫助嗎?

回報問題