Giới thiệu
Các khối nội dung có thể tái sử dụng được sử dụng trên nhiều trang khác nhau.
Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/category/blocks
🎯 Mô-đun này làm gì?
Mô-đun Blocks cho phép bạn lấy các thành phần nội dung tái sử dụng (khối) — các tập hợp thuộc tính mà bạn tạo một lần trong bảng điều khiển quản trị và tái sử dụng trên các trang và trang sản phẩm: tiêu đề, chân trang, banner, đánh giá, thanh trượt và widget sản phẩm/gợi ý. Cập nhật một khối một lần và nó sẽ thay đổi ở mọi nơi mà nó được sử dụng.
SDK là chỉ đọc: bạn lấy các khối ở đây và tạo hoặc chỉnh sửa chúng trong bảng điều khiển quản trị OneEntry.
🚀 Bắt đầu nhanh
Khởi tạo mô-đun từ defineOneEntry:
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
Lấy một khối duy nhất theo dấu hiệu của nó và đọc các thuộc tính của nó:
// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");
console.log(block.identifier, block.type, block.isVisible);
// "footer" "common_block" true
// Custom fields live in attributeValues.
console.log(block.attributeValues);
✨ Khái niệm chính
Khối là gì?
Một khối là một thành phần nội dung tái sử dụng chứa:
identifier— dấu hiệu duy nhất được sử dụng để tham chiếu trong mã (luôn sử dụng dấu hiệu; nó không bao giờ thay đổi)localizeInfos— dữ liệu địa phương hóa (ví dụ:title), nội dung khác nhau theo ngôn ngữtype—BlockTypexác định cách mà khối được hiển thịisVisible— cờ hiển thịattributeValues— các trường tùy chỉnh mà bạn định nghĩa qua AttributesSets
Cấu trúc khối
{
id: 3, // unique ID
localizeInfos: { // block localized data
title: 'Block', // block localized title
},
version: 0, // block version
position: 1, // block position in array of blocks
identifier: 'block', // block identifier (marker)
type: 'common_block', // block type
templateIdentifier: null, // template identifier
isVisible: true, // visibility
attributeValues: {}, // block attributes
}
📋 Những điều bạn cần biết
- Tham chiếu các khối theo dấu hiệu (
identifier) trong mã — các dấu hiệu không bao giờ thay đổi. - Các khối được tạo trong bảng điều khiển quản trị. SDK là chỉ đọc.
- Các trường tùy chỉnh đến từ AttributesSets. Ví dụ: một khối chân trang (bản quyền, liên kết xã hội, thông tin liên hệ), một banner hero (tiêu đề, CTA, hình nền), một đánh giá (tác giả, ảnh, trích dẫn, đánh giá).
- Khối và Trang. Một trang là một tài liệu tự chứa với một URL (ví dụ:
/about) được tạo trong mô-đun Pages; một khối là một thành phần tái sử dụng mà bạn chèn vào các trang.
📊 Bảng tham khảo nhanh - Các phương thức phổ biến
| Phương thức | Chức năng | Khi nào sử dụng |
|---|---|---|
| getBlocks() | Lấy tất cả các khối (phân trang, lọc) | Liệt kê tất cả các khối có sẵn |
| getBlockByMarker() | Lấy khối theo dấu hiệu | Lấy khối cụ thể trong mã |
| searchBlock() | Tìm kiếm các khối | Lấy các khối |
| getFrequentlyOrderedProducts() | Sản phẩm thường xuyên được đặt hàng | "Thường được đặt cùng nhau" |
| getCartComplement() | "Hoàn thành giỏ hàng của bạn" theo ngữ cảnh giỏ hàng | Bán chéo từ giỏ hàng |
| getCartComplementByProductIds() | "Hoàn thành giỏ hàng của bạn" theo productIds | Bán chéo cho các sản phẩm đã cho |
| getCartSimilar() | "Tương tự như giỏ hàng" theo ngữ cảnh giỏ hàng | Các lựa chọn thay thế cho các mục trong giỏ hàng |
| getCartSimilarByProductIds() | "Tương tự như giỏ hàng" theo productIds | Các lựa chọn thay thế cho các sản phẩm đã cho |
| getWishlistSimilar() | "Tương tự như danh sách mong muốn" theo danh sách mong muốn | Các lựa chọn thay thế cho các mục trong danh sách mong muốn |
| getWishlistSimilarByProductIds() | "Tương tự như danh sách mong muốn" theo productIds | Các lựa chọn thay thế cho các sản phẩm đã cho |
| getPersonalRecommendations() | Gợi ý cá nhân | Dòng sản phẩm cá nhân hóa |
| getRecentlyViewed() | Sản phẩm đã xem gần đây | Widget "Đã xem gần đây" |
| getRepeatPurchase() | Sản phẩm cho lần mua lại | Widget "Mua lại" |
| getTrending() | Sản phẩm đang thịnh hành | Widget "Đang thịnh hành" |
| getSlides() | Cây slide của khối thanh trượt | Hiển thị một slider/carousel |
🧩 Các loại khối
type của một khối (cái gọi là BlockType) xác định cách mà nó được hiển thị. Ngoài các loại cơ bản (common_block, product_block, similar_products_block, form, và các loại khác), các loại khối sản phẩm & cá nhân hóa sau đây có sẵn:
| Loại khối | Phương thức |
|---|---|
frequently_ordered_block | getFrequentlyOrderedProducts() |
trending_block | getTrending() |
recently_viewed_block | getRecentlyViewed() |
repeat_purchase_block | getRepeatPurchase() |
slider_block | getSlides() |
personal_recommendations_block | getPersonalRecommendations() |
cart_complement_block | getCartComplement() / getCartComplementByProductIds() |
cart_similar_block | getCartSimilar() / getCartSimilarByProductIds() |
wishlist_similar_block | getWishlistSimilar() / getWishlistSimilarByProductIds() |
Các khối cá nhân hóa (đã xem gần đây, mua lại, gợi ý cá nhân, giỏ hàng/danh sách mong muốn) được điều khiển bởi hoạt động của người dùng và hoạt động cho cả người dùng đã đăng nhập và khách (xem Chế độ khách).
Khóa giá (signPrice)
Các phương thức khối sản phẩm & gợi ý (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) chấp nhận một tham số tùy chọn signPrice. Nó nhận dấu hiệu của một kho lưu trữ đơn hàng và yêu cầu máy chủ khóa giá sản phẩm được trả về trong một khoảng thời gian giới hạn, vì vậy giá mà khách hàng thấy trong widget gợi ý là giá mà họ phải trả khi thanh toán.
signPrice— loạistringDấu hiệu kho lưu trữ đơn hàng để khóa giá. Nếu tham số được đặt, giá sẽ được khóa trong một khoảng thời gian nhất định.
- Trên các phương thức gợi ý,
signPricelà tham số vị trí cuối cùng (saulangCode). - Trên các biến thể
…ByProductIds(getCartSimilarByProductIds,getCartComplementByProductIds, …) nó là một trường của yêu cầubody(body.signPrice).
Mỗi sản phẩm được trả về sau đó mang một token signedPrice mã hóa giá đã khóa:
const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");
const signedPrice = products[0].signedPrice;
➡️ Tái sử dụng token đó khi tạo đơn hàng — xem phần Giá sản phẩm cố định (signedPrice) trong mô-đun Orders. Tham số khóa giá tương tự cũng tồn tại trong mô-đun Products (trong userQuery.signPrice).
❓ Câu hỏi thường gặp (FAQ)
Sự khác biệt giữa Blocks và Pages là gì?
- Pages/Product Pages — các trang tự chứa với URL (ví dụ:
/about) được tạo trong mô-đun Pages, mà bạn thêm các khối và các thành phần khác vào. - Blocks — các thành phần tái sử dụng được chèn vào các trang (ví dụ: một chân trang).
Hãy nghĩ về một trang như một tài liệu đầy đủ và một khối như một đoạn văn mà bạn tái sử dụng trên các tài liệu.
Làm thế nào để tôi cập nhật nội dung của một khối?
Chỉnh sửa nó trong bảng điều khiển quản trị OneEntry (phần Blocks). Tất cả các trang sử dụng khối đó sẽ tự động cập nhật.
Tôi nên tạo nhiều khối nhỏ hay ít khối lớn?
Ưu tiên nhiều khối nhỏ, tập trung (ví dụ: header_logo, footer_social_links) hơn là một khối lớn entire_page_layout — các khối nhỏ dễ tái sử dụng và bảo trì hơn.
Làm thế nào để tôi hiển thị/ẩn các khối một cách có điều kiện?
Kiểm tra trường isVisible trên khối đã lấy.
Làm thế nào để tôi xử lý các khối bị thiếu một cách nhẹ nhàng?
Bọc việc lấy trong try/catch và hiển thị một fallback khi không tìm thấy khối.
🎓 Thực hành tốt nhất
- Tạo các khối nhỏ, tập trung (trách nhiệm đơn).
- Sử dụng các dấu hiệu mô tả (
global_footer, không phảiblock1); viết thường với dấu gạch dưới. - Tham chiếu các khối theo dấu hiệu trong mã — các dấu hiệu không bao giờ thay đổi.
- Lưu cache các khối — chúng hiếm khi thay đổi.
- Xử lý các khối bị thiếu một cách nhẹ nhàng (try/catch).
🔗 Tài liệu liên quan
- Mô-đun Pages - Quản lý các trang sử dụng khối
- Mô-đun AttributesSets - Định nghĩa các thuộc tính khối
- Mô-đun Products - Sử dụng các khối trong các trang sản phẩm
- Mô-đun Hoạt động của người dùng - Điều khiển các khối cá nhân hóa