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 imagem de atributo - 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 todo o 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 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 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 Atributo - 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 uma exibição uniforme de imagens de atributos

Estrutura do Modelo de Visualização​

Cada modelo de visualização tem esta estrutura:

{
  id: 3,                                      // Identificador único
  title: 'Modelos de Visualização',           // Nome do modelo (não único)
  identifier: 'preview-templates',            // Marcador do modelo (único)
  proportions: {                              // Conjuntos de parâmetros de imagem
    default: {                                // Configuração padrão do modelo
      horizontal: {                           // Para imagens horizontais
        width: 234,                           // Largura em pixels
        height: 324,                          // Altura em pixels
        alignmentType: 'middleBottom'         // Tipo de centralização (eixo de compressão)
      },
      vertical: {                             // Para imagens verticais
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // Para imagens quadradas
        side: 3,                              // Comprimento do lado em pixels
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // Número da versão
  attributeValues: {},                        // Dados adicionais de atributos
  position: 1,                                // Posição de exibição
  isUsed: false,                              // Status de uso
  attributeSetIdentifier: null                // Conjunto de atributos associado
}

Campos Chave:

  • identifier - Marcador único para referência do modelo (use isso, não 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. Crie o modelo de visualização no painel de administração
   (Defina o tamanho para as imagens de atributos)
   ↓
2. Atribua o modelo ao tipo de atributo
   (por exemplo, o atributo "Cor" usa "color_swatch")
   ↓
3. Busque modelos via SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. Aplique o modelo às imagens de atributos
   (Use o marcador do modelo nas URLs das imagens)
   ↓
5. Exibição consistente de imagens de atributos
   (Todas as amostras de cores do mesmo tamanho)

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:

Painel de Administração do OneEntry → Configurações → Modelos de Visualização → Criar Modelo → Definir Nome/Marcador → Configurar Parâmetros → Salvar

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

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 às 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á-los.

Para criar/editar modelos de visualização: Use o Painel de Administração do OneEntry.

Otimização de Imagem de Atributo​

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​

Os 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) e depois a substitui pela imagem de qualidade total. Isso fornece feedback visual instantâneo e melhora o desempenho percebido, especialmente em conexões lentas.

Posso atribuir modelos de visualização diferentes 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 às 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 → 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

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​