Criar uma vitrine de produtos

Este tutorial cria uma vitrine de até quatro produtos com estoque, ordenados pelo menor preço. Comece com um tema exportado e preserve o JavaScript do pacote.

1. Declare a composição

No template mapeado como Home no theme.json, acrescente o item abaixo ao array sections, preservando as outras sections. O exemplo mostra o documento mínimo completo; não substitua sua Home inteira se quiser manter o restante da página.

{
  "sections": [
    {
      "id": "vitrine_exemplo",
      "type": "vitrine_exemplo",
      "dataSources": {
        "products": {
          "type": "products",
          "query": {
            "source": "catalog",
            "inStock": true,
            "orderBy": "price_asc",
            "limit": 4
          }
        }
      }
    }
  ]
}

id identifica essa instância; type aponta para sections/vitrine_exemplo.liquid. Critérios comerciais ficam em dataSources; o visual permanece em Liquid e CSS.

2. Crie a section

Crie sections/vitrine_exemplo.liquid:

<section class="example-showcase" aria-labelledby="{{ section.id }}-title">
  <h2 id="{{ section.id }}-title">Conheça nossos produtos</h2>
  {% if section.data.products.status == 'ready' %}
    <div class="example-showcase-grid">
      {% for product in section.data.products.items %}
        {% render 'card_exemplo', product: product %}
      {% else %}
        <p>Nenhum produto disponível nesta seleção.</p>
      {% endfor %}
    </div>
  {% else %}
    <p>Esta seleção não está disponível no momento.</p>
  {% endif %}
</section>

O servidor fornece os resultados em section.data.products. O estado restricted informa que a seleção não está disponível naquele contexto. Uma seleção vazia continua vazia; a section mostra uma mensagem própria.

3. Crie o component do card

Crie components/card_exemplo.liquid:

<article class="example-product-card">
  <a href="{{ product.url | storefront_url }}">
    {% if product.mainImage %}
      <img src="{{ product.mainImage.url }}" alt="{{ product.name }}" loading="lazy">
    {% else %}
      <span class="example-product-placeholder">Imagem indisponível</span>
    {% endif %}
    <h3>{{ product.name }}</h3>
  </a>
  {% if product.priceVisible and product.price %}
    <p>
      {% if product.hasVariablePrices %}A partir de {% endif %}
      {{ product.price | money }}
    </p>
  {% else %}
    <p>Consulte as condições deste produto</p>
  {% endif %}
</article>

O argumento product é passado explicitamente. O card trata imagem ausente e preço indisponível, respeita preços variáveis e leva o visitante ao detalhe. A compra e a seleção de variantes continuam no fluxo da plataforma.

Este tutorial usa a edição externa por ZIP, que permite incluir components. A IA do editor tem permissões diferentes e só altera components existentes.

4. Adicione a apresentação

Acrescente este CSS ao final de assets/theme.css:

.example-showcase {
    max-width: 1200px;
    margin: 0 auto;
    padding: 32px 20px;
}

.example-showcase-grid {
    display: grid;
    grid-template-columns: repeat(2, minmax(0, 1fr));
    gap: 20px;
}

.example-product-card {
    padding: 16px;
    border: 1px solid #dce4e9;
    border-radius: 12px;
}

.example-product-card a {
    color: inherit;
    text-decoration: none;
}

.example-product-card a:focus-visible {
    outline: 3px solid #087a58;
    outline-offset: 4px;
}

.example-product-card img {
    width: 100%;
    aspect-ratio: 1;
    object-fit: contain;
}

.example-product-placeholder {
    display: grid;
    place-items: center;
    aspect-ratio: 1;
    background: #f2f5f7;
}

@media (min-width: 900px) {
    .example-showcase-grid {
        grid-template-columns: repeat(4, minmax(0, 1fr));
    }
}

As classes são escolhas deste exemplo. Você pode alterar tipografia, cores, espaçamento e estrutura, preservando o contrato de dados.

5. Confira o resultado

Importe o ZIP atualizado e visualize a Home. Com produtos elegíveis, você deve ver até quatro cards; sem itens, uma mensagem. Confira o layout em celular e desktop e abra o detalhe de um produto pelo card.

Consulte Testar e publicar antes de ativar a revisão.