Chuyển đến nội dung chính

Giới thiệu

Lấy các mẫu hiển thị điều khiển cách các trang, khối, sản phẩm và hình ảnh được hiển thị trong ứng dụng của bạn.

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

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

Mô-đun Templates cho phép bạn thay đổi cấu trúc và giao diện của dự án mà không cần thay đổi mã nguồn. Bạn tạo các mẫu trong bảng điều khiển quản trị OneEntry (Cài đặt > Mẫu), gán các thành phần của bạn với chúng, và mô-đun này sẽ lấy các cấu hình đó để ứng dụng của bạn có thể hiển thị nội dung với kiểu dáng nhất quán.

Việc tách biệt cấu trúc khỏi mã cho phép bạn chuyển đổi giữa các triển khai mẫu để ảnh hưởng đến cách các thực thể được hiển thị, tất cả mà không cần triển khai lại. SDK chỉ có thể đọc: bạn không thể tạo mẫu thông qua nó.

🚀 Bắt đầu nhanh​

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


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

Lấy các mẫu và đọc cấu hình của chúng:

// Fetch all templates of a given BlockType.
const productTemplates = await Templates.getTemplateByType("product", "en_US");

productTemplates.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.generalTypeName);
});

// Or fetch a single template by its marker.
const card = await Templates.getTemplateByMarker("product_thumbnail", "en_US");
console.log(card.attributeValues);

✨ Khái niệm chính​

Mẫu là gì?​

Một Mẫu (ITemplateEntity) là một cấu hình hiển thị xác định cách nội dung nên xuất hiện:

  • Loại chung (generalTypeName) - Danh mục thực thể mà mẫu áp dụng, một BlockType như product, common_page, common_block, form, hoặc order
  • 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)
  • Đánh dấu (identifier) - Định danh duy nhất cho tham chiếu mã (sử dụng cái này, không phải ID)
  • Giá trị thuộc tính (attributeValues) - Bản đồ các giá trị thuộc tính được khóa bởi đánh dấu
  • Bộ thuộc tính (attributeSetIdentifier) - Bộ thuộc tính liên kết tùy chọn

Cấu trúc mẫu (ITemplateEntity):

interface ITemplateEntity {
  id: number;                              // Unique identifier
  title: string;                           // Template name (non-unique)
  identifier: string;                      // Template marker (unique)
  generalTypeId: number;                   // Type ID reference
  version: number;                         // Version number
  generalTypeName: BlockType;              // General type name
  attributeSetIdentifier: string | null;   // Associated attribute set
  attributeValues: IAttributeValues;       // Map of attribute values keyed by marker
  position: number;                        // Sort position
}

Các loại mẫu (BlockType)​

Loại của một mẫu là generalTypeName, một giá trị BlockType. getTemplateByType(type) chấp nhận cùng một BlockType. Các giá trị phổ biến:

LoạiDanh mục thực thểVí dụ sử dụng
productSản phẩmChi tiết sản phẩm, hiển thị sản phẩm
catalog_pageTrang danh mụcDanh sách danh mục, kết quả tìm kiếm
common_pageTrang thông thườngBài viết blog, trang đích, trang giới thiệu
error_pageTrang lỗiTrang 404, trang 500, bố cục lỗi tùy chỉnh
common_blockKhối nội dungThẻ nội dung, banner, phần, widget
formBiểu mẫuBiểu mẫu liên hệ, biểu mẫu đăng ký, khảo sát
orderĐơn hàngXác nhận đơn hàng, lịch sử đơn hàng
serviceThực thể dịch vụNội dung liên quan đến dịch vụ

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

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

Bạn không thể tạo mẫu thông qua SDK - chúng được tạo trong bảng điều khiển quản trị OneEntry (Cài đặt > Mẫu). Mỗi mẫu cần một Tên (không duy nhất), một Đánh dấu duy nhất, và một Loại (danh mục thực thể mà nó áp dụng). SDK chỉ dùng để lấy cấu hình mẫu, không phải để tạo chúng.

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

Luôn tham chiếu các mẫu 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, còn ID thì không. Sử dụng getTemplateByMarker(marker) cho một mẫu đơn, getTemplateByType(type) cho tất cả các mẫu của một BlockType, và getAllTemplates() cho mọi mẫu được nhóm theo loại.

Mẫu bị thiếu​

Các phương thức trả về một đối tượng lỗi (IError) khi một mẫu không được tìm thấy. Luôn xác minh rằng các đánh dấu tồn tại và xử lý các mẫu bị thiếu một cách khéo léo.

Bộ nhớ đệm​

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

📊 Bảng tham khảo nhanh​

Phương thứcMô tảTrường hợp sử dụng
getAllTemplates()Lấy tất cả các mẫu được nhóm theo loạiLiệt kê tất cả các mẫu có sẵn
getTemplateByType()Lấy các mẫu theo loại thực thểLấy các mẫu cho một loại thực thể cụ thể
getTemplateByMarker()Lấy một mẫu 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 Templates và TemplatePreviews là gì?​

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

Làm thế nào để tôi lấy một mẫu cụ thể?​

Sử dụng getTemplateByMarker(marker) cho một mẫu đơn theo định danh của nó, hoặc getTemplateByType(type) để lấy tất cả các mẫu của một BlockType nhất định (ví dụ: product, common_page). Sử dụng getAllTemplates() để lấy mọi mẫu được nhóm theo loại.

Điều gì xảy ra nếu tôi tham chiếu một mẫu không tồn tại?​

Các phương thức trả về một đối tượng lỗi (IError). Luôn xác minh rằng các đánh dấu mẫu tồn tại và xử lý các mẫu bị thiếu một cách khéo léo.

Tôi nên sử dụng loại mẫu nào cho nội dung của mình?​

Chọn dựa trên loại thực thể: common_page cho các trang tiêu chuẩn, catalog_page cho danh sách sản phẩm, common_block cho các khối nội dung, product cho chi tiết sản phẩm. Khớp loại mẫu với danh mục nội dung của bạn.

🎓 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.
  • Tạo các đánh dấu có nghĩa - product_card, không phải tpl_1.
  • Lưu trữ các mẫu - giảm số lần gọi API cho dữ liệu hiếm khi thay đổi.
  • Xử lý các mẫu bị thiếu - kiểm tra hình dạng trả về IError.

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