應用程式會在 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。
- 您在這裡附加的程式碼需要由您自行維護;在佈景主題或應用程式更新後店面運作異常時,這也是第一個要檢查的地方。
這個頁面有幫助嗎?
感謝您的意見回饋! 告訴我們缺少了什麼
回報問題