Nhảy đến nội dung

Giới thiệu

🎯 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 mình. 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 đảm bảo kích thước và định dạng nhất quán phù hợp với yêu cầu thiết kế của bạn.

Các mẫu xem trước cấu hình các tham số hình ảnh được sử dụng trong các thuộc tính, cung cấp hình ảnh được chuẩn hóa theo các thông số đã được thiết lập trong mẫu xem trước. Điều này đảm bảo hiển thị hình ảnh nhất quán 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.

Hãy coi đây là bộ cấu hình hình ảnh thuộc tính của bạn - 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 trong toàn bộ danh mục của bạn.

📖 Giải thích đơn giản​

Mỗi ứng dụng thương mại điện tử cần hình ảnh sản phẩm nhất quán trên các thuộc tính:

  • 🎨 Mẫu Màu - Các biến thể màu sản phẩm (Đỏ, Xanh, Xanh lá) với hình ảnh xem trước
  • 📏 Bảng Kích Thước - Hình ảnh thuộc tính kích thước (Nhỏ, Vừa, Lớn) với hướng dẫn trực quan
  • 🖼️ Mẫu Vật Liệu - Hình ảnh thuộc tính vật liệu (Da, Cotton, Lụa) với kết cấu
  • 💎 Tùy Chọn Hoàn Thiện - Hình ảnh hoàn thiện bề mặt (Bóng, Mờ, Satin) với ví dụ trực quan
  • 👗 Mẫu Họa Tiết - Hình ảnh thuộc tính họa tiết (Kẻ sọc, Đơn sắc, Hoa) với mẫu
  • 🏷️ Thư Viện Thuộc Tính - Kích thước hình ảnh nhất quán cho tất cả các thuộc tính sản phẩm

Vấn đề với hình ảnh thuộc tính không nhất quán

Vấn đề:

  • 🎨 Hiển thị không nhất quán - Các hình ảnh thuộc tính khác nhau có kích thước khác nhau
  • 📊 Khó bảo trì - Thay đổi yêu cầu chỉnh sửa nhiều thành phần
  • 🔄 Không tái sử dụng - Logic kích thước giống nhau bị lặp lại ở khắp nơi
  • 🖼️ Trải nghiệm người dùng kém - Hình ảnh thuộc tính trông không đồng nhất và không chuyên nghiệp

Giải pháp TemplatePreviews

Lợi ích:

  • 🎨 Hiển thị nhất quán - Tất cả hình ảnh thuộc tính sử dụng cùng một mẫu
  • 📊 Bảo trì dễ dàng - Thay đổi mẫu trong bảng điều khiển quản trị
  • 🔄 Có thể tái sử dụng - Cùng một mẫu cho tất cả các thuộc tính
  • 🖼️ Trải nghiệm người dùng chuyên nghiệp - Hình ảnh thuộc tính được căn chỉnh, đồng nhất

✨ Khái niệm chính​

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

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

  • Hình ảnh Thuộc Tính - Hình ảnh liên quan đến các thuộc tính sản phẩm (màu sắc, kích thước, vật liệu)
  • Kích Thước Xem Trước - Kích thước cho hiển thị hình ảnh thuộc tính
  • Cài Đặt Cắt - Cách cắt hình ảnh thuộc tính
  • Đánh Dấu - Định danh duy nhất cho tham chiếu mẫu
  • Tính Nhất Quán - Mẫu giống nhau đảm bảo hiển thị hình ảnh thuộc tính đồng nhất

Cấu Trúc Mẫu Xem Trước​

Mỗi mẫu xem trước có cấu trúc như sau:

{
  id: 3,                                      // Định danh duy nhất
  title: 'Mẫu Xem Trước',                     // Tên mẫu (không duy nhất)
  identifier: 'preview-templates',            // Đánh dấu mẫu (duy nhất)
  proportions: {                              // Bộ tham số hình ảnh
    default: {                                // Cấu hình mẫu mặc định
      horizontal: {                           // Dành cho hình ảnh ngang
        width: 234,                           // Chiều rộng tính bằng pixel
        height: 324,                          // Chiều cao tính bằng pixel
        alignmentType: 'middleBottom'         // Loại căn chỉnh (trục nén)
      },
      vertical: {                             // Dành cho hình ảnh dọc
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // Dành cho hình ảnh vuông
        side: 3,                              // Chiều dài cạnh tính bằng pixel
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // Số phiên bản
  attributeValues: {},                        // Dữ liệu thuộc tính bổ sung
  position: 1,                                // Vị trí hiển thị
  isUsed: false,                              // Trạng thái sử dụng
  attributeSetIdentifier: null                // Bộ thuộc tính liên quan
}

Các trường chính:

  • identifier - Đánh dấu duy nhất cho tham chiếu mẫu (sử dụng cái này, không phải ID)
  • title - Tên mẫu hiển thị trong bảng điều khiển quản trị
  • proportions - Cấu hình hình ảnh cho các hướng khác nhau
  • alignmentType - Xác định cách hình ảnh được cắt/căn chỉnh

Quy Trình Mẫu Xem Trước​

1. Tạo mẫu xem trước trong bảng điều khiển quản trị
   (Xác định kích thước cho hình ảnh thuộc tính)
   ↓
2. Gán mẫu cho loại thuộc tính
   (ví dụ, thuộc tính "Màu" sử dụng "color_swatch")
   ↓
3. Lấy mẫu qua SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. Áp dụng mẫu cho hình ảnh thuộc tính
   (Sử dụng đánh dấu mẫu trong URL hình ảnh)
   ↓
5. Hiển thị hình ảnh thuộc tính nhất quán
   (Tất cả mẫu màu có cùng kích thước)

Tại sao sử dụng mô-đun TemplatePreviews?​

Lợi íchMô tả
Thuộc Tính Nhất QuánTất cả hình ảnh thuộc tính có cùng kích thước
Tối Ưu Hình ẢnhTự động thay đổi kích thước và nén
Bảo Trì Dễ DàngThay đổi mẫu, cập nhật tất cả thuộc tính
Trải Nghiệm Người Dùng Tốt HơnHiển thị thuộc tính đồng nhất, chuyên nghiệp
Tích Hợp CDNGiao hàng tối ưu cho hình ảnh thuộc tính
Cấu Hình Có Thể Tái Sử DụngCùng một mẫu cho tất cả mẫu màu

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

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 mẫu xem trước qua SDK - chúng được tạo trong bảng điều khiển quản trị OneEntry:

Bảng Điều Khiển Quản Trị OneEntry → Cài đặt → Mẫu Xem Trước → Tạo Mẫu → Đặt Tên/Đánh Dấu → Cấu Hình Tham Số → Lưu

Quy trình tạo:

  • Cung cấp một Tên (định danh không duy nhất)
  • Cung cấp một Đánh Dấu (định danh duy nhất)
  • Nhấn "Tạo" để hoàn tất

Cấu hình:

  • Chọn mẫu và nhấn biểu tượng bánh răng để cấu hình
  • Thêm bộ tham số xem trước cho ba hướng hình ảnh:
    • Dọc - Chiều rộng, Chiều cao, Loại Căn Chỉnh
    • Ngang - 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
  • Chỉ định một bộ tham số là mẫu mặc định

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

Mẫu Xem Trước vs Mẫu​

TemplatePreviews được sử dụng đặc biệt cho hình ảnh thuộc tính sản phẩm:

Tính năngTemplatePreviewsMẫu
Mục đíchXem trước hình ảnh thuộc tínhHình ảnh nội dung chung
Trường hợp sử dụngMẫu màu, mẫu vật liệuHình ảnh hero, hình ảnh sản phẩm
Phạm viChỉ thuộc tính sản phẩmTrang, khối, sản phẩm
Ví dụMẫu màu 50×50Biểu ngữ hero 1920×1080

Thực hành tốt nhất: Sử dụng TemplatePreviews cho hình ảnh thuộc tính, Mẫu cho nội dung chung.

Áp Dụng Mẫu cho Hình Ảnh Thuộc Tính​

OneEntry tự động tối ưu hóa hình ảnh thuộc tính dựa trên các mẫu xem trước.

Gán Mẫu Xem Trước​

Các mẫu xem trước thường được gán cho các loại thuộc tính cụ thể.

Hiển Thị Thuộc Tính Nhất Quán​

Sử dụng mẫu xem trước để đảm bảo hiển thị hình ảnh thuộc tính đồng nhất.

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

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

💡 Ghi chú quan trọng​

Mẫu Xem Trước được Tạo trong Bảng Điều Khiển Quản Trị​

Nhớ: SDK được sử dụng để lấy cấu hình mẫu xem trước, không phải để tạo chúng.

Để tạo/chỉnh sửa mẫu xem trước: Sử dụng Bảng Điều Khiển Quản Trị OneEntry.

Tối Ưu Hình Ảnh Thuộc Tính​

CDN OneEntry tự động tối ưu hóa hình ảnh thuộc tính dựa trên cài đặt mẫu xem trước:

  • Thay đổi kích thước tự động
  • Chuyển đổi định dạng (JPEG, PNG, WebP)
  • Nén
  • Cắt
  • Lưu trữ

Bạn chỉ cần tham chiếu đến đánh dấu mẫu

Bộ Nhớ Cache Mẫu Xem Trước​

Mẫu xem trước hiếm khi thay đổi - thực hiện bộ nhớ cache:

  • Frontend: localStorage, sessionStorage
  • Backend: Redis, bộ nhớ cache
  • TTL: 1 giờ được khuyến nghị

Hiển Thị Thuộc Tính Nhất Quán​

Sử dụng cùng một mẫu xem trước cho cùng một loại thuộc tính:

  • Tất cả thuộc tính màu → mẫu color_swatch
  • Tất cả thuộc tính vật liệu → mẫu material_preview
  • Tất cả thuộc tính họa tiết → mẫu pattern_thumbnail

Tính nhất quán cải thiện trải nghiệm người dùng và trông chuyên nghiệp.

Kích Thước Mẫu Được Khuyến Nghị​

Kích thước hình ảnh thuộc tính phổ biến:

  • Mẫu Màu: 50×50 đến 100×100
  • Mẫu Vật Liệu: 80×80 đến 150×150
  • Mẫu Họa Tiết: 60×60 đến 120×120
  • Bảng Kích Thước: 100×80 đến 200×150
  • Mẫu Hoàn Thiện: 75×75 đến 100×100

Công Nghệ LQIP​

Các mẫu xem trước sử dụng công nghệ Low-Quality Image Placeholder (LQIP) để tối ưu hóa hiệu suất tải:

Cách hoạt động:

  • Trả về một cấu trúc mảng hai phần tử:
    1. Hình thu nhỏ - định dạng WebP, tối ưu hóa cho tải nhanh (vài trăm byte)
    2. Mẫu Được Tạo - hình ảnh độ phân giải đầy đủ thay thế hình thu nhỏ sau khi tải

✅ Lợi ích:

  • Hiển thị ngay lập tức với hình thu nhỏ
  • Chuyển tiếp mượt mà đến chất lượng đầy đủ
  • Giảm tiêu thụ băng thông
  • Cải thiện trải nghiệm người dùng

Xóa Mẫu​

Để xóa một mẫu:

  1. Chọn mẫu trong bảng điều khiển quản trị
  2. Nhấn biểu tượng xóa
  3. Xác nhận xóa

Lưu ý: Chỉ có các mẫu chưa sử dụng mới có thể bị xóa.

📊 Bảng Tham Khảo Nhanh​

Phương phápMô tảTrường hợp sử dụng
getTemplatePreviews()Lấy tất cả các mẫu xem trướcLiệt kê tất cả các mẫu thuộc tính có sẵn
getTemplatesPreviewByMarker()Lấy mẫu xem trước theo đánh dấuLấ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 sử dụng đặc biệt 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ý hình ảnh nội dung chung (biểu ngữ hero, hình ảnh sản phẩm). Sử dụng TemplatePreviews chỉ cho hình ảnh thuộc tính.

Làm thế nào để 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 tự động phát hiện hướng hình ảnh và áp dụng các tỷ lệ thích hợp (ngang, dọc hoặc vuông).

LQTP là gì và tại sao nó quan trọng?​

LQIP (Low-Quality Image Placeholder) tải một hình thu nhỏ nhỏ trước (vài trăm byte), sau đó thay thế nó bằng hình ảnh chất lượng đầy đủ. Điều này cung cấp phản hồi hình ảnh ngay lập tức và cải thiện hiệu suất cảm nhận, đặc biệt trên các kết nối chậm.

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 chúng cho các loại thuộc tính phù hợp để hiển thị nhất quán.

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

Các mẫu xem trước được áp dụng tự động khi bạn cấu hình chúng trong bảng điều khiển quản trị. Lấy mẫu qua getTemplatesPreviewByMarker() và sử dụng các tỷ lệ để hiển thị hình ảnh thuộc tính với kích thước nhất quán.

Kích thước được khuyến nghị cho hình ảnh thuộc tính là gì?​

Giữ cho hình ảnh thuộc tính nhỏ: 50-150px để tối ưu hóa hiệu suất. Kích thước phổ biến: Mẫu màu (50×50 đến 100×100), Mẫu vật liệu (80×80 đến 150×150), Mẫu họa tiết (60×60 đến 120×120).

🎓 Thực Hành Tốt Nhất​

  • Sử dụng đánh dấu, không phải ID - Đánh dấu ổn định qua các môi trường
  • Lưu trữ mẫu xem trước - Giảm số lần gọi API cho dữ liệu hiếm khi thay đổi
  • Tạo kích thước nhất quán - Cùng loại thuộc tính = cùng kích thước mẫu
  • Sử dụng định dạng WebP - Nén tốt hơn cho hình ảnh thuộc tính
  • Xác định cài đặt chất lượng - Cân bằng chất lượng và kích thước tệp (80-90 được khuyến nghị)
  • Ánh xạ thuộc tính đến mẫu - Tạo ánh xạ loại thuộc tính → mẫu
  • Sử dụng đánh dấu ngữ nghĩa - color_swatch, không phải preview_1
  • Kiểm tra trên di động - Đảm bảo hình ảnh thuộc tính trông đẹp trên màn hình nhỏ

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

Định nghĩa của mô-đun TemplatePreviews​


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

🔗 Tài liệu liên quan​