Pular para o conteúdo
Instalar aplicação
Português (Portugal)

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>.

EventodetailDisparado 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?

Comunicar um problema