应用在 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() === '';});在文本字段中每次按键都会触发此事件,因此请对任何耗时的操作进行防抖处理——例如网络请求、大量重新布局。
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 }); }});开启 自动滚动到第一条错误消息 后,应用已会滚动到第一个错误,因此您无需自行处理。请参阅小组件行为。
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。
- 您在此附加的代码需要由您自行维护;当主题或应用更新后店面出现异常时,它是首先需要检查的地方。
此页面对您有帮助吗?
感谢您的反馈! 告诉我们缺少了什么
报告问题