Giới thiệu

Lấy các mẫu xem trước chuẩn hóa kích thước và định dạng hình ảnh cho hình ảnh thuộc tính sản phẩm.

Thông tin thêm về các mẫu xem trước trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloud/docs/templates/templates_preview/

---

🎯 Mô-đun này làm gì?

Mô-đun TemplatePreviews cho phép bạn chuẩn hóa các tham số hình ảnh trong toàn bộ dự án của bạn. Bằng cách áp dụng các mẫu xem trước cho các thuộc tính "Hình ảnh" hoặc "Nhóm Hình ảnh", bạn cung cấp hình ảnh có kích thước và cắt xén nhất quán theo cấu hình của mẫu - trên các hình ảnh sản phẩm, hình ảnh biến thể và hình ảnh dựa trên thuộc tính.

Bạn tạo các mẫu xem trước trong bảng điều khiển quản trị OneEntry (Cài đặt > Mẫu Xem trước), và mô-đun này lấy các cấu hình đó để các thuộc tính sản phẩm có hình ảnh được hiển thị nhất quán. SDK chỉ có thể đọc: bạn không thể tạo các mẫu xem trước thông qua nó.

🚀 Bắt đầu nhanh

Khởi tạo mô-đun từ defineOneEntry:

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

Lấy các mẫu xem trước và đọc tỷ lệ của chúng:

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

✨ Khái niệm chính

Mẫu Xem trước là gì?

Một Mẫu Xem trước (ITemplatesPreviewEntity) là một cấu hình hình ảnh cho các thuộc tính sản phẩm:

• Đánh dấu (identifier) - Định danh duy nhất cho tham chiếu mẫu (sử dụng cái này, không phải ID)
• Tiêu đề (title) - Tên mẫu hiển thị trong bảng điều khiển quản trị (không duy nhất)
• Tỷ lệ (proportions) - Tập hợp các tham số hình ảnh theo hướng (ngang, dọc, vuông)
• Căn chỉnh (alignmentType) - Cách hình ảnh được cắt xén/căn giữa

Cấu trúc Mẫu Xem trước

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

Một giá trị tỷ lệ mẫu:

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

Quy trình Mẫu Xem trước

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)

📋 Những điều bạn cần biết

Các mẫu xem trước được tạo trong bảng điều khiển quản trị

Bạn không thể tạo các mẫu xem trước qua SDK - chúng được tạo trong bảng điều khiển quản trị OneEntry (Cài đặt > Mẫu Xem trước). Mỗi mẫu cần một Tên (không duy nhất) và một Đánh dấu duy nhất, cộng với các tập hợp tỷ lệ cho ba hướng hình ảnh:

• Ngang - chiều rộng, chiều cao, loại căn chỉnh
• Dọc - chiều rộng, chiều cao, loại căn chỉnh
• Vuông - chiều dài cạnh, loại căn chỉnh

SDK chỉ dùng để lấy các cấu hình mẫu xem trước, không phải để tạo chúng.

Sử dụng đánh dấu, không phải ID

Tham chiếu các mẫu xem trước bằng đánh dấu (identifier) của chúng trong mã của bạn - các đánh dấu ổn định qua các môi trường. Sử dụng getTemplatePreviewByMarker(marker) cho một mẫu duy nhất và getTemplatePreviews() cho tất cả chúng.

TemplatePreviews so với Templates

TemplatePreviews đặc biệt dành cho hình ảnh thuộc tính sản phẩm:

Tính năng	TemplatePreviews	Templates
Mục đích	Xem trước hình ảnh thuộc tính	Hiển thị nội dung chung
Trường hợp sử dụng	Mẫu màu, mẫu vật liệu	Hình ảnh hero, bố cục sản phẩm
Phạm vi	Chỉ thuộc tính sản phẩm	Trang, khối, sản phẩm

Thực tiễn tốt nhất: Sử dụng TemplatePreviews cho hình ảnh thuộc tính, Templates cho nội dung chung.

Bộ nhớ đệm

Các mẫu xem trước hiếm khi thay đổi - hãy lưu vào bộ nhớ đệm (localStorage/sessionStorage ở phía trước, Redis/bộ nhớ ở phía sau; ~1 giờ TTL là một điểm khởi đầu hợp lý).

---

📊 Bảng tham khảo nhanh

Phương thức	Mô tả	Trường hợp sử dụng
getTemplatePreviews()	Lấy tất cả các mẫu xem trước	Liệt kê tất cả các mẫu thuộc tính có sẵn
getTemplatePreviewByMarker()	Lấy một mẫu xem trước theo đánh dấu	Lấy cấu hình mẫu cụ thể

❓ Câu hỏi thường gặp (FAQ)

Sự khác biệt giữa TemplatePreviews và Templates là gì?

TemplatePreviews đặc biệt dành cho hình ảnh thuộc tính sản phẩm (mẫu màu, mẫu vật liệu), trong khi Templates xử lý hiển thị nội dung chung (trang, khối, sản phẩm). Sử dụng TemplatePreviews chỉ cho hình ảnh thuộc tính.

---

Làm thế nào để tôi cấu hình các kích thước khác nhau cho hình ảnh ngang, dọc và vuông?

Trong bảng điều khiển quản trị, cấu hình tất cả ba hướng cho mỗi mẫu xem trước. Hệ thống phát hiện hướng của hình ảnh và áp dụng tập hợp tỷ lệ phù hợp (ngang, dọc, hoặc vuông).

---

Tôi có thể gán các mẫu xem trước khác nhau cho các loại thuộc tính khác nhau không?

Có. Tạo nhiều mẫu xem trước với các đánh dấu khác nhau (ví dụ: color_swatch, material_preview, pattern_thumbnail) và gán mỗi mẫu cho loại thuộc tính phù hợp để hiển thị nhất quán.

---

Làm thế nào để tôi áp dụng một mẫu xem trước cho hình ảnh thuộc tính?

Lấy mẫu qua getTemplatePreviewByMarker() và sử dụng tỷ lệ của nó để hiển thị hình ảnh thuộc tính với kích thước nhất quán. Việc gán một mẫu cho một loại thuộc tính được thực hiện trong bảng điều khiển quản trị.

---

🎓 Thực tiễn tốt nhất

• Sử dụng đánh dấu, không phải ID - các đánh dấu ổn định qua các môi trường.
• Sử dụng đánh dấu ngữ nghĩa - color_swatch, không phải preview_1.
• Ánh xạ thuộc tính đến mẫu - giữ một mẫu cho mỗi loại thuộc tính để đảm bảo tính nhất quán.
• Lưu trữ các mẫu xem trước - giảm số lần gọi API cho dữ liệu hiếm khi thay đổi.

---

🔗 Tài liệu liên quan

• Bảng điều khiển quản trị OneEntry - Mẫu Xem trước - Tài liệu chính thức của bảng điều khiển quản trị
• Mô-đun Templates - Mẫu nội dung chung
• Mô-đun Attributes - Cấu hình thuộc tính sản phẩm
• Mô-đun Products - Sản phẩm có thuộc tính
• Thực tiễn tối ưu hóa hình ảnh

---