Pular para o conteúdo principal

Introdução

Busque templates de pré-visualização que padronizam o tamanho e a formatação de imagens para atributos de produtos.

Mais informações sobre templates de pré-visualização no painel de administração do OneEntry: https://doc.oneentry.cloud/docs/templates/templates_preview/

🎯 O que este módulo faz?​

O módulo TemplatePreviews permite que você padronize os parâmetros de imagem em todo o seu projeto. Ao aplicar templates de pré-visualização a atributos de "Imagem" ou "Grupo de Imagens", você garante tamanhos e formatações consistentes que se alinham com os requisitos de design.

Templates de pré-visualização configuram os parâmetros de imagem usados nos atributos, entregando imagens padronizadas de acordo com as especificações definidas no template de pré-visualização. Isso garante uma exibição consistente de imagens em imagens de produtos, imagens de variantes e imagens baseadas em atributos.

Pense nisso como seu configurador de imagens de atributos - você cria templates de pré-visualização no painel de administração do OneEntry (Configurações > Templates de Pré-visualização), e este módulo busca essas configurações para que os atributos de produtos com imagens sejam renderizados de forma consistente em seu catálogo.

📖 Explicação Simples​

Toda aplicação de e-commerce precisa de imagens de produtos consistentes em todos os atributos:

  • 🎨 Amostras de Cores - Variantes de cor do produto (Vermelho, Azul, Verde) com imagens de pré-visualização
  • 📏 Tabelas de Tamanhos - Imagens de atributos de tamanho (Pequeno, Médio, Grande) com guias visuais
  • 🖼️ Pré-visualizações de Materiais - Imagens de atributos de material (Couro, Algodão, Seda) com texturas
  • 💎 Opções de Acabamento - Imagens de acabamento de superfície (Brilhante, Fosco, Satinado) com exemplos visuais
  • 👗 Pré-visualizações de Padrões - Imagens de atributos de padrão (Listrado, Sólido, Floral) com amostras
  • 🏷️ Galerias de Atributos - Tamanhos de imagem consistentes para todos os atributos de produtos

O problema com imagens de atributos inconsistentes

Problemas:

  • 🎨 Exibição inconsistente - Imagens de atributos diferentes têm tamanhos diferentes
  • 📊 Difícil de manter - Alterações requerem edição de múltiplos componentes
  • 🔄 Sem reutilização - A mesma lógica de dimensionamento duplicada em todos os lugares
  • 🖼️ Pobre UX - Imagens de atributos parecem desalinhadas e não profissionais

A solução TemplatePreviews

Benefícios:

  • 🎨 Exibição consistente - Todas as imagens de atributos usam o mesmo template
  • 📊 Manutenção fácil - Altere o template no painel de administração
  • 🔄 Reutilizável - O mesmo template para todos os atributos
  • 🖼️ UX profissional - Imagens de atributos alinhadas e uniformes

✨ Conceitos Chave​

O que é um Template de Pré-visualização?​

Um Template de Pré-visualização é uma configuração de imagem para atributos de produtos:

  • Imagens de Atributo - Imagens associadas a atributos de produtos (cor, tamanho, material)
  • Tamanho de Pré-visualização - Dimensões para exibição de imagens de atributos
  • Configurações de Corte - Como cortar imagens de atributos
  • Marcador - Identificador único para referência do template
  • Consistência - O mesmo template garante exibição uniforme de imagens de atributos

Estrutura do Template de Pré-visualização​

Cada template de pré-visualização tem esta estrutura:

{
  id: 3,                                      // Unique identifier
  title: 'Preview Templates',                 // Template name (non-unique)
  identifier: 'preview-templates',            // Template marker (unique)
  proportions: {                              // Image parameter sets
    default: {                                // Default template configuration
      horizontal: {                           // For horizontal images
        width: 234,                           // Width in pixels
        height: 324,                          // Height in pixels
        alignmentType: 'middleBottom'         // Centering type (compression axis)
      },
      vertical: {                             // For vertical images
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // For square images
        side: 3,                              // Side length in pixels
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // Version number
  attributeValues: {},                        // Additional attribute data
  position: 1,                                // Display position
  isUsed: false,                              // Usage status
  attributeSetIdentifier: null                // Associated attribute set
}

Campos Chave:

  • identifier - Marcador único para referência do template (use isso, não ID)
  • title - Nome do template exibido no painel de administração
  • proportions - Configuração de imagem para diferentes orientações
  • alignmentType - Define como as imagens são cortadas/centralizadas

Fluxo de Trabalho do Template de Pré-visualização​

1. Create preview template in admin panel
   (Define size for attribute images)
   ↓
2. Assign template to attribute type
   (e.g., "Color" attribute uses "color_swatch")
   ↓
3. Fetch templates via SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. Apply template to attribute images
   (Use template marker in image URLs)
   ↓
5. Consistent attribute image display
   (All color swatches same size)

Por que usar o Módulo TemplatePreviews?​

BenefícioDescrição
Atributos ConsistentesTodas as imagens de atributos do mesmo tamanho
Otimização de ImagemRedimensionamento e compressão automáticos
Manutenção FácilAltere o template, atualiza todos os atributos
Melhor UXExibição uniforme e profissional de atributos
Integração CDNEntrega otimizada de imagens de atributos
Configs ReutilizáveisO mesmo template para todas as amostras de cor

📋 O que você precisa saber​

Templates de Pré-visualização são Criados no Painel de Administração​

Você não pode criar templates de pré-visualização via SDK - eles são criados no painel de administração do OneEntry:

OneEntry Admin Panel → Settings → Preview Templates → Create Template → Set Name/Marker → Configure Parameters → Save

Processo de Criação:

  • Forneça um Nome (identificador não único)
  • Forneça um Marcador (identificador único)
  • Clique em "Criar" para finalizar

Configuração:

  • Selecione o template e clique no ícone de engrenagem para configurar
  • Adicione conjuntos de parâmetros de pré-visualização para três orientações de imagem:
    • Vertical - Largura, Altura, Tipo de Centralização
    • Horizontal - Largura, Altura, Tipo de Centralização
    • Quadrado - Comprimento do lado, Tipo de Centralização
  • Designe um conjunto de parâmetros como o template padrão

O SDK é para buscar configurações de templates de pré-visualização, não para criá-los.

Templates de Pré-visualização vs Templates​

TemplatePreviews são especificamente para imagens de atributos de produtos:

RecursoTemplatePreviewsTemplates
PropósitoPré-visualizações de imagens de atributosImagens de conteúdo geral
Caso de UsoAmostras de cores, pré-visualizações de materiaisImagens hero, fotos de produtos
EscopoApenas atributos de produtosPáginas, blocos, produtos
Exemploamostra de cor 50×50banner hero 1920×1080

Melhor prática: Use TemplatePreviews para imagens de atributos, Templates para conteúdo geral.

Aplicando Templates a Imagens de Atributos​

O OneEntry otimiza automaticamente as imagens de atributos com base nos templates de pré-visualização.

Atribuição de Template de Pré-visualização​

Templates de pré-visualização são tipicamente atribuídos a tipos de atributos específicos.

Exibição Consistente de Atributos​

Use templates de pré-visualização para garantir uma exibição uniforme de imagens de atributos.

Estrutura do TemplatePreview:

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;
      vertical: IProportion | null;
      square: ISquare;
    };
  };
  identifier: string;
  version: number;
  attributeValues: AttributeType;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

💡 Notas Importantes​

Templates de Pré-visualização são Criados no Painel de Administração​

Lembre-se: O SDK é para buscar configurações de templates de pré-visualização, não para criá-los.

Para criar/editar templates de pré-visualização: Use o Painel de Administração do OneEntry.

Otimização de Imagens de Atributos​

O CDN do OneEntry otimiza automaticamente as imagens de atributos com base nas configurações do template de pré-visualização:

  • Redimensionamento automático
  • Conversão de formato (JPEG, PNG, WebP)
  • Compressão
  • Corte
  • Cache

Você apenas referencia o marcador do template

Cache de Template de Pré-visualização​

Templates de pré-visualização raramente mudam - implemente cache:

  • Frontend: localStorage, sessionStorage
  • Backend: Redis, cache de memória
  • TTL: 1 hora recomendada

Exibição Consistente de Atributos​

Use o mesmo template de pré-visualização para o mesmo tipo de atributo:

  • Todos os atributos de cor → template color_swatch
  • Todos os atributos de material → template material_preview
  • Todos os atributos de padrão → template pattern_thumbnail

A consistência melhora a UX e parece profissional.

Tamanhos de Template Recomendados​

Tamanhos comuns de imagens de atributos:

  • Amostras de Cores: 50×50 a 100×100
  • Pré-visualizações de Materiais: 80×80 a 150×150
  • Miniaturas de Padrões: 60×60 a 120×120
  • Tabelas de Tamanhos: 100×80 a 200×150
  • Pré-visualizações de Acabamento: 75×75 a 100×100

Tecnologia LQIP​

Templates de pré-visualização usam a tecnologia Low-Quality Image Placeholder (LQIP) para desempenho de carregamento ideal:

Como funciona:

  • Retorna uma estrutura de array de dois elementos:
    1. Miniatura - formato WebP, otimizado para carregamento rápido (alguns centenas de bytes)
    2. Pré-visualização Gerada - imagem de resolução total que substitui a miniatura após o carregamento

✅ Benefícios:

  • Exibição instantânea com miniatura
  • Transição suave para qualidade total
  • Redução do consumo de largura de banda
  • Melhor experiência do usuário

Excluindo Templates​

Para remover um template:

  1. Selecione o template no painel de administração
  2. Clique no ícone de excluir
  3. Confirme a remoção

Nota: Apenas templates não utilizados podem ser excluídos.

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getTemplatePreviews()Obter todos os templates de pré-visualizaçãoListar todos os templates de atributos disponíveis
getTemplatesPreviewByMarker()Obter template de pré-visualização por marcadorBuscar configuração de template específica

❓ Perguntas Comuns (FAQ)​

Qual é a diferença entre TemplatePreviews e Templates?​

TemplatePreviews são especificamente para imagens de atributos de produtos (amostras de cores, pré-visualizações de materiais), enquanto Templates lidam com imagens de conteúdo geral (banners hero, fotos de produtos). Use TemplatePreviews apenas para imagens específicas de atributos.

Como configuro tamanhos diferentes para imagens horizontais, verticais e quadradas?​

No painel de administração, configure as três orientações para cada template de pré-visualização. O sistema detecta automaticamente a orientação da imagem e aplica as proporções apropriadas (horizontal, vertical ou quadrada).

O que é LQTP e por que isso importa?​

LQIP (Low-Quality Image Placeholder) carrega primeiro uma miniatura pequena (alguns centenas de bytes), depois a substitui pela imagem de alta qualidade. Isso fornece feedback visual instantâneo e melhora o desempenho percebido, especialmente em conexões lentas.

Posso atribuir diferentes templates de pré-visualização a diferentes tipos de atributos?​

Sim! Crie múltiplos templates de pré-visualização com marcadores diferentes (por exemplo, color_swatch, material_preview, pattern_thumbnail) e atribua-os aos tipos de atributos apropriados para renderização consistente.

Como aplico um template de pré-visualização a imagens de atributos?​

Templates de pré-visualização são aplicados automaticamente quando você os configura no painel de administração. Busque o template via getTemplatesPreviewByMarker() e use as proporções para renderizar imagens de atributos com tamanhos consistentes.

Quais são os tamanhos recomendados para imagens de atributos?​

Mantenha as imagens de atributos pequenas: 50-150px para desempenho ideal. Tamanhos comuns: Amostras de cores (50×50 a 100×100), Pré-visualizações de materiais (80×80 a 150×150), Miniaturas de padrões (60×60 a 120×120).

🎓 Melhores Práticas​

  • Use marcadores, não IDs - Marcadores são estáveis em diferentes ambientes
  • Cache templates de pré-visualização - Reduza chamadas de API para dados que raramente mudam
  • Crie tamanhos consistentes - Mesmo tipo de atributo = mesmo tamanho de template
  • Use formato WebP - Melhor compressão para imagens de atributos
  • Defina configurações de qualidade - Equilibre qualidade vs tamanho do arquivo (80-90 recomendado)
  • Mapeie atributos para templates - Crie mapeamento de tipo de atributo → template
  • Use marcadores semânticos - color_swatch, não preview_1
  • Teste em dispositivos móveis - Garanta que as imagens de atributos fiquem boas em telas pequenas

Definição do módulo TemplatePreviews​


const { TemplatePreviews } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​