跳转到内容
安装应用
简体中文

事件

应用在店面上触发的五个事件,每个都附有完整示例。

应用在 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。
  • 您在此附加的代码需要由您自行维护;当主题或应用更新后店面出现异常时,它是首先需要检查的地方。

此页面对您有帮助吗?

报告问题