Eventos
Os cinco eventos que a aplicação dispara na loja online, cada um com um exemplo prático.
A aplicação dispara estes eventos em document, por isso escute-os com document.addEventListener. Coloque o código num recurso do tema ou em theme.liquid, acima de </body>.
| Evento | detail | Disparado quando |
|---|---|---|
gpoRenderCompleted | { form, product } | As opções terminaram de ser renderizadas |
gpoElementChanged | {} | O cliente alterou uma opção |
gpoProductPriceUpdated | {} | O preço apresentado foi recalculado |
gpoValidated | { success } | A validação foi executada ao adicionar ao carrinho |
gpoAddedToCart | {} | O artigo e os respetivos suplementos chegaram ao carrinho |
gpoRenderCompleted
Disparado assim que os campos das opções existem no DOM. É este o evento em que se deve basear. A aplicação renderiza de forma assíncrona, por isso o código executado em DOMContentLoaded é executado antes de as opções existirem e não encontra nada.
detail contém form, o formulário do produto em que as opções foram renderizadas, e product, o produto para o qual foram renderizadas.
document.addEventListener('gpoRenderCompleted', function (event) { const { form, product } = event.detail; if (!form) return; // nenhum conjunto de opções se aplica a este produto
// Já é seguro consultar os campos das opções form.querySelectorAll('.gpo-form__group').forEach(function (group) { group.classList.add('my-theme-option'); });});É disparado novamente sempre que as opções voltam a ser renderizadas — após uma mudança de variante em temas que voltam a renderizar o produto, ou depois de chamar GPOConfigs.initialize(). Escreva o handler de forma a que a sua execução repetida não cause problemas.
gpoElementChanged
Disparado sempre que o cliente altera uma opção: ao escrever num campo, escolher uma amostra ou marcar uma caixa de verificação.
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() === '';});É disparado a cada tecla premida num campo de texto, por isso aplique debounce a tudo o que for pesado — um pedido de rede, um novo cálculo de layout exigente.
gpoProductPriceUpdated
Disparado depois de a aplicação ter reescrito o preço apresentado para incluir as opções escolhidas pelo cliente. Utilize-o para manter a sua própria apresentação do preço sincronizada — uma barra fixa, um bloco de resumo, uma estimativa de pagamento em prestações.
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;});O preço mostrado na página é uma pré-visualização. O valor efetivamente cobrado ao cliente é aplicado pela Shopify no checkout, por isso nunca trate este valor como o montante final. Consulte Como os preços são aplicados.
gpoValidated
Disparado quando o cliente tenta adicionar ao carrinho e a aplicação verificou as opções. detail.success é false quando algo está errado — uma opção obrigatória vazia, um limite de caracteres excedido, seleções a menos.
document.addEventListener('gpoValidated', function (event) { if (event.detail.success) return;
// A adição ao carrinho foi bloqueada if (window.analytics) { window.analytics.track('Option validation failed', { product: window.GPOConfigs?.product?.handle }); }});A aplicação já se desloca até ao primeiro erro quando Deslocar automaticamente para a primeira mensagem de erro está ativado, por isso não precisa de o fazer. Consulte Comportamento do widget.
gpoAddedToCart
Disparado depois de o artigo e eventuais produtos suplemento terem sido adicionados. É neste momento que o carrinho mudou realmente, o que faz dele o sítio certo para abrir o carrinho e para a análise de dados.
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; });});Um suplemento associado a um produto é uma linha própria do carrinho, por isso uma única adição ao carrinho pode adicionar várias linhas. Leia novamente o carrinho em vez de presumir que foi adicionado um só artigo. Consulte Unir produto principal e suplementos.
Notas
- Os cinco precisam da incorporação da aplicação ativada. Sem ela, a aplicação nunca é executada e nada é disparado.
- Os eventos não transportam dados do cliente além dos que já estão na página. Leia window.GPOConfigs para obter o produto, o carrinho e o cliente.
- O código que associar aqui é da sua responsabilidade e é a primeira coisa a verificar quando a loja online se comporta de forma anómala após uma atualização do tema ou da aplicação.
Esta página foi útil?
Obrigado pelo seu feedback! Diga-nos o que faltou
Comunicar um problema