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 seu projeto. Ao aplicar templates de pré-visualização a atributos de "Imagem" ou "Grupo de Imagens", você entrega imagens dimensionadas e recortadas de forma consistente de acordo com a configuração do template - em imagens de produtos, imagens de variantes e imagens baseadas em 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. O SDK é somente leitura: você não pode criar templates de pré-visualização através dele.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { TemplatePreviews } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Busque templates de pré-visualização e leia suas proporções:

// Fetch all preview templates, localized to English.
const previews = await TemplatePreviews.getTemplatePreviews("en_US");

previews.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.proportions.default.square);
});

// Or fetch a single preview template by its marker.
const swatch = await TemplatePreviews.getTemplatePreviewByMarker("color_swatch", "en_US");
console.log(swatch.proportions.default.horizontal);

✨ Conceitos Chave​

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

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

  • Marcador (identifier) - Identificador único para referência do template (use isso, não o ID)
  • Título (title) - Nome do template exibido no painel de administração (não único)
  • Proporções (proportions) - Conjuntos de parâmetros de imagem por orientação (horizontal, vertical, quadrado)
  • Alinhamento (alignmentType) - Como as imagens são recortadas/centralizadas

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

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;   // { width, height, alignmentType }
      vertical: IProportion | null;     // { width, height, alignmentType }
      square: ISquare;                  // { side, alignmentType }
    };
  };
  identifier: string;
  version: number;
  attributeValues: IAttributeValues;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

Um valor de proporções de exemplo:

{
  default: {
    horizontal: { width: 234, height: 324, alignmentType: "middleBottom" },
    vertical:   { width: 2,   height: 3,   alignmentType: "leftTop" },
    square:     { side: 3,    alignmentType: "leftTop" },
  },
}

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

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

📋 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 (Configurações > Templates de Pré-visualização). Cada template precisa de um Nome (não único) e um Marcador único, além de conjuntos de proporções para três orientações de imagem:

  • Horizontal - largura, altura, tipo de alinhamento
  • Vertical - largura, altura, tipo de alinhamento
  • Quadrado - comprimento do lado, tipo de alinhamento

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

Use marcadores, não IDs​

Referencie templates de pré-visualização pelo seu marcador (identifier) em seu código - os marcadores são estáveis entre ambientes. Use getTemplatePreviewByMarker(marker) para um único template e getTemplatePreviews() para todos eles.

TemplatePreviews vs Templates​

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

RecursoTemplatePreviewsTemplates
PropósitoPré-visualizações de imagens de atributosExibição de conteúdo geral
Caso de UsoAmostras de cores, pré-visualizações de materiaisImagens de destaque, layouts de produtos
EscopoApenas atributos de produtosPáginas, blocos, produtos

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

Cache​

Templates de pré-visualização raramente mudam - armazene em cache (localStorage/sessionStorage no frontend, Redis/memória no backend; ~1 hora de TTL é um ponto de partida razoável).

📊 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
getTemplatePreviewByMarker()Obter um template de pré-visualização por marcadorBuscar uma 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 a exibição de conteúdo geral (páginas, blocos, 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 a orientação de uma imagem e aplica o conjunto de proporções correspondente (horizontal, vertical ou square).

Posso atribuir templates de pré-visualização diferentes 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 cada um ao tipo de atributo apropriado para renderização consistente.

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

Busque o template via getTemplatePreviewByMarker() e use suas proporções para renderizar imagens de atributos com tamanhos consistentes. A atribuição de um template a um tipo de atributo é feita no painel de administração.

🎓 Melhores Práticas​

  • Use marcadores, não IDs - os marcadores são estáveis entre ambientes.
  • Use marcadores semânticos - color_swatch, não preview_1.
  • Mapeie atributos para templates - mantenha um template por tipo de atributo para consistência.
  • Armazene em cache templates de pré-visualização - reduza chamadas à API para dados que raramente mudam.

🔗 Documentação Relacionada​