Aller au contenu principal

Introduction

Récupérez des modèles d'aperçu qui standardisent la taille et le format des images pour les images d'attributs de produit.

Plus d'informations sur les modèles d'aperçu dans le panneau d'administration OneEntry : https://doc.oneentry.cloud/docs/templates/templates_preview/

🎯 Que fait ce module ?​

Le module TemplatePreviews vous permet de standardiser les paramètres d'image dans votre projet. En appliquant des modèles d'aperçu aux attributs "Image" ou "Groupe d'Images", vous fournissez des images dimensionnées et recadrées de manière cohérente selon la configuration du modèle - pour les images de produit, les images de variante et les images basées sur des attributs.

Vous créez des modèles d'aperçu dans le panneau d'administration OneEntry (Paramètres > Modèles d'Aperçu), et ce module récupère ces configurations afin que les attributs de produit avec images s'affichent de manière cohérente. Le SDK est en lecture seule : vous ne pouvez pas créer de modèles d'aperçu par son intermédiaire.

🚀 Démarrage Rapide​

Initialisez le module depuis defineOneEntry :


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

Récupérez les modèles d'aperçu et lisez leurs proportions :

// 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);

✨ Concepts Clés​

Qu'est-ce qu'un Modèle d'Aperçu ?​

Un Modèle d'Aperçu (ITemplatesPreviewEntity) est une configuration d'image pour les attributs de produit :

  • Marqueur (identifier) - Identifiant unique pour la référence du modèle (utilisez ceci, pas l'ID)
  • Titre (title) - Nom du modèle affiché dans le panneau d'administration (non-unique)
  • Proportions (proportions) - Ensembles de paramètres d'image par orientation (horizontale, verticale, carrée)
  • Alignement (alignmentType) - Comment les images sont recadrées/centrées

Structure du Modèle d'Aperçu​

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;
}

Un exemple de valeur proportions :

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

Flux de Travail du Modèle d'Aperçu​

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)

📋 Ce Que Vous Devez Savoir​

Les modèles d'aperçu sont créés dans le panneau d'administration​

Vous ne pouvez pas créer de modèles d'aperçu via le SDK - ils sont créés dans le panneau d'administration OneEntry (Paramètres > Modèles d'Aperçu). Chaque modèle nécessite un Nom (non-unique) et un Marqueur unique, plus des ensembles de proportions pour trois orientations d'image :

  • Horizontal - largeur, hauteur, type d'alignement
  • Vertical - largeur, hauteur, type d'alignement
  • Carré - longueur de côté, type d'alignement

Le SDK est destiné à récupérer les configurations de modèles d'aperçu, pas à les créer.

Utilisez des marqueurs, pas des IDs​

Référez-vous aux modèles d'aperçu par leur marqueur (identifier) dans votre code - les marqueurs sont stables à travers les environnements. Utilisez getTemplatePreviewByMarker(marker) pour un modèle unique et getTemplatePreviews() pour tous.

TemplatePreviews vs Templates​

Les TemplatePreviews sont spécifiquement pour les images d'attributs de produit :

FonctionnalitéTemplatePreviewsTemplates
ObjectifPrévisualisations d'images d'attributsAffichage de contenu général
Cas d'utilisationÉchantillons de couleur, prévisualisations de matériauxImages héroïques, mises en page de produits
PortéeAttributs de produit uniquementPages, blocs, produits

Meilleure pratique : Utilisez TemplatePreviews pour les images d'attributs, Templates pour le contenu général.

Mise en Cache​

Les modèles d'aperçu changent rarement - mettez-les en cache (localStorage/sessionStorage sur le frontend, Redis/mémoire sur le backend ; un TTL d'environ 1 heure est un bon point de départ).

📊 Tableau de Référence Rapide​

MéthodeDescriptionCas d'utilisation
getTemplatePreviews()Obtenir tous les modèles d'aperçuLister tous les modèles d'attribut disponibles
getTemplatePreviewByMarker()Obtenir un modèle d'aperçu par marqueurRécupérer une configuration de modèle spécifique

❓ Questions Fréquemment Posées (FAQ)​

Quelle est la différence entre TemplatePreviews et Templates ?​

Les TemplatePreviews sont spécifiquement pour les images d'attributs de produit (échantillons de couleur, prévisualisations de matériaux), tandis que les Templates gèrent l'affichage de contenu général (pages, blocs, produits). Utilisez TemplatePreviews uniquement pour les images spécifiques aux attributs.

Comment configurer différentes tailles pour les images horizontales, verticales et carrées ?​

Dans le panneau d'administration, configurez les trois orientations pour chaque modèle d'aperçu. Le système détecte l'orientation d'une image et applique l'ensemble de proportions correspondant (horizontal, vertical, ou square).

Puis-je attribuer différents modèles d'aperçu à différents types d'attributs ?​

Oui. Créez plusieurs modèles d'aperçu avec différents marqueurs (par exemple, color_swatch, material_preview, pattern_thumbnail) et attribuez chacun au type d'attribut approprié pour un rendu cohérent.

Comment appliquer un modèle d'aperçu aux images d'attributs ?​

Récupérez le modèle via getTemplatePreviewByMarker() et utilisez ses proportions pour rendre les images d'attributs avec des dimensions cohérentes. L'attribution d'un modèle à un type d'attribut se fait dans le panneau d'administration.

🎓 Meilleures Pratiques​

  • Utilisez des marqueurs, pas des IDs - les marqueurs sont stables à travers les environnements.
  • Utilisez des marqueurs sémantiques - color_swatch, pas preview_1.
  • Mappez les attributs aux modèles - gardez un modèle par type d'attribut pour la cohérence.
  • Mettez en cache les modèles d'aperçu - réduisez les appels API pour des données rarement changées.

🔗 Documentation Connexe​