Pular para o conteúdo principal

Introdução

🎯 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 modelos de visualização a atributos de "Imagem" ou "Grupo de Imagens", você garante tamanhos e formatações consistentes que estão alinhados com os requisitos de design.

Os modelos de visualização configuram os parâmetros de imagem usados nos atributos, entregando imagens padronizadas de acordo com as especificações definidas no modelo de 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 modelos de visualização no painel de administração do OneEntry (Configurações > Modelos de 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 visualização
  • 📏 Tabelas de Tamanhos - Imagens de atributos de tamanho (Pequeno, Médio, Grande) com guias visuais
  • 🖼️ 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
  • 👗 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 exigem 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 modelo
  • 📊 Manutenção fácil - Altere o modelo no painel de administração
  • 🔄 Reutilizável - O mesmo modelo em todos os atributos
  • 🖼️ UX profissional - Imagens de atributos alinhadas e uniformes

✨ Conceitos Chave​

O que é um Modelo de Visualização?​

Um Modelo de Visualização é uma configuração de imagem para atributos de produtos:

  • Imagens de Atributos - Imagens associadas a atributos de produtos (cor, tamanho, material)
  • Tamanho de 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 modelo
  • Consistência - O mesmo modelo garante exibição uniforme de imagens de atributos

Estrutura do Modelo de Visualização​

Cada modelo de 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 modelo (use isso, não ID)
  • title - Nome do modelo 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 Modelo de 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 modelo, atualiza todos os atributos
Melhor UXExibição uniforme e profissional de atributos
Integração CDNEntrega otimizada de imagens de atributos
Configs ReutilizáveisO mesmo modelo para todas as amostras de cores

📋 O que você precisa saber​

Modelos de Visualização são Criados no Painel de Administração​

Você não pode criar modelos de 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 modelo e clique no ícone de engrenagem para configurar
  • Adicione conjuntos de parâmetros de 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 modelo padrão

O SDK é para buscar configurações de modelos de visualização, não para criá-las.

Modelos de Visualização vs Modelos​

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

RecursoTemplatePreviewsModelos
PropósitoVisualizações de imagens de atributosImagens de conteúdo geral
Caso de UsoAmostras de cores, 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, Modelos para conteúdo geral.

Aplicando Modelos a Imagens de Atributos​

O OneEntry otimiza automaticamente as imagens de atributos com base nos modelos de visualização.

Atribuição de Modelos de Visualização​

Os modelos de visualização são tipicamente atribuídos a tipos de atributos específicos.

Exibição Consistente de Atributos​

Use modelos de visualização para garantir uma exibição uniforme de imagens de atributos.

Estrutura do Modelo de Visualização:

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​

Modelos de Visualização são Criados no Painel de Administração​

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

Para criar/editar modelos de 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 modelo de visualização:

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

Você apenas referencia o marcador do modelo

Cache de Modelos de Visualização​

Modelos de 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 modelo de visualização para o mesmo tipo de atributo:

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

A consistência melhora a UX e parece profissional.

Tamanhos de Modelo Recomendados​

Tamanhos comuns de imagens de atributos:

  • Amostras de Cores: 50×50 a 100×100
  • 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
  • Visualizações de Acabamento: 75×75 a 100×100

Tecnologia LQIP​

Modelos de 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. 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 Modelos​

Para remover um modelo:

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

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

📊 Tabela de Referência Rápida​

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

❓ Perguntas Comuns (FAQ)​

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

TemplatePreviews são especificamente para imagens de atributos de produtos (amostras de cores, visualizações de materiais), enquanto Modelos 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 modelo de 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 modelos de visualização a diferentes tipos de atributos?​

Sim! Crie vários modelos de 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 modelo de visualização a imagens de atributos?​

Os modelos de visualização são aplicados automaticamente quando você os configura no painel de administração. Busque o modelo 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), 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 modelos de visualização - Reduza chamadas de API para dados que raramente mudam
  • Crie tamanhos consistentes - Mesmo tipo de atributo = mesmo tamanho de modelo
  • 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 modelos - Crie mapeamento de attributeType → modelo
  • 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

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

Definição do módulo TemplatePreviews​


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

🔗 Documentação Relacionada​