Giới thiệu
Lấy nhãn trạng thái sản phẩm ("Mới", "Giảm giá", "Hết hàng") để gán và lọc các mục trong danh mục.
Thông tin thêm về trạng thái sản phẩm trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloud/docs/category/catalog
🎯 Mô-đun này làm gì?
Mô-đun ProductStatuses cung cấp các điều kiện lọc bổ sung cho các mục trong danh mục bên cạnh các bộ lọc dựa trên thuộc tính. Trạng thái sản phẩm cho phép bạn tạo các nhãn tùy chỉnh - như "Sản phẩm mới", "Bán chạy nhất", "Giảm giá", "Hết hàng" - để gán, tổ chức và lọc sản phẩm trong danh mục thương mại điện tử của bạn.
Bạn định nghĩa các nhãn trạng thái trong bảng điều khiển quản trị OneEntry (Danh mục > Trạng thái sản phẩm), gán chúng cho các sản phẩm và sử dụng mô-đun này để lấy trạng thái và lọc sản phẩm theo chúng. SDK chỉ có thể đọc: bạn không thể tạo trạng thái thông qua nó.
🚀 Bắt đầu nhanh
Khởi tạo mô-đun từ defineOneEntry:
const { ProductStatuses } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
Lấy tất cả các trạng thái và đọc các trường của chúng:
// Fetch every product status, localized to English.
const statuses = await ProductStatuses.getProductStatuses("en_US");
statuses.forEach((status) => {
console.log(status.identifier, status.localizeInfos.title, status.isDefault);
});
// Or fetch a single status by its marker.
const sale = await ProductStatuses.getProductsByStatusMarker("sale", "en_US");
console.log(sale.localizeInfos.title); // "Sale"
✨ Khái niệm chính
Trạng thái sản phẩm là gì?
Trạng thái sản phẩm (IProductStatusEntity) là một nhãn/gắn thẻ tùy chỉnh cho các sản phẩm:
- Tên trạng thái (
localizeInfos) - Tên hiển thị được địa phương hóa (ví dụ: "Sản phẩm mới", "Giảm giá") - Dấu hiệu trạng thái (
identifier) - Định danh duy nhất được sử dụng để lọc - Cờ mặc định (
isDefault) - Liệu đây có phải là trạng thái mặc định hay không - Vị trí (
position) - Thứ tự hiển thị
Quy trình trạng thái sản phẩm
1. Create status in admin panel
(e.g., "New Arrival")
↓
2. Assign status to products
(Select products in admin)
↓
3. Fetch statuses via SDK
(ProductStatuses.getProductStatuses())
↓
4. Display status badges on products
(Render badges in product listings)
↓
5. Filter products by status marker
(Products.getProducts([{ statusMarker }], langCode))
📋 Những điều bạn cần biết
Trạng thái được tạo trong bảng điều khiển quản trị
Bạn không thể tạo trạng thái thông qua SDK - chúng được tạo trong bảng điều khiển quản trị OneEntry (Danh mục > Trạng thái sản phẩm). Mỗi trạng thái cần có một Tên (bắt buộc) và một Dấu hiệu duy nhất (bắt buộc).
Ràng buộc về dấu hiệu:
- Chỉ cho phép chữ cái Latin (a-z, A-Z) và số (0-9)
- Cho phép dấu gạch dưới (
_) và dấu gạch ngang (-) - Không có khoảng trắng hoặc ký tự đặc biệt
- Phải duy nhất trong tất cả các trạng thái
SDK chỉ để lấy trạng thái và lọc sản phẩm, không phải để tạo trạng thái.
Một trạng thái cho mỗi sản phẩm
Một sản phẩm tham chiếu tối đa một trạng thái. Đối tượng sản phẩm mang statusIdentifier (dấu hiệu trạng thái, hoặc null):
const product = await Products.getProductById(123);
console.log(product.statusIdentifier); // "in_stock" - status marker, or null
Lọc theo trạng thái
Để lọc sản phẩm theo trạng thái, sử dụng phương thức getProducts(body, langCode, userQuery) của mô-đun Products. Truyền một trường statusMarker bên trong mảng body của IFilterParams để lấy sản phẩm với trạng thái cụ thể.
Xác thực một dấu hiệu
validateMarker(marker) trả về true nếu dấu hiệu tồn tại và false nếu không. Vì SDK không thể tạo trạng thái, hãy sử dụng nó để xác minh một dấu hiệu trước khi tham chiếu nó trong mã của bạn.
Trạng thái so với thuộc tính
ProductStatuses khác với thuộc tính sản phẩm:
| Tính năng | ProductStatuses | Thuộc tính |
|---|---|---|
| Mục đích | Nhãn/gắn thẻ/lọc | Thuộc tính sản phẩm |
| Ví dụ | "Mới", "Giảm giá", "Nổi bật" | Màu sắc, Kích thước, Chất liệu |
| Theo sản phẩm | Một trạng thái | Nhiều thuộc tính |
| Lọc | Đơn giản (theo dấu hiệu trạng thái) | Phức tạp (phạm vi, giá trị) |
| Trường hợp sử dụng | Nhãn tiếp thị | Thông số sản phẩm |
Thực tiễn tốt nhất: Sử dụng trạng thái cho nhãn tiếp thị, thuộc tính cho thông số sản phẩm.
📊 Bảng tham khảo nhanh
| Phương thức | Mô tả | Trường hợp sử dụng |
|---|---|---|
| getProductStatuses() | Lấy tất cả trạng thái sản phẩm | Liệt kê tất cả trạng thái có sẵn |
| getProductsByStatusMarker() | Lấy trạng thái sản phẩm theo dấu hiệu | Lấy trạng thái theo định danh |
| validateMarker() | Kiểm tra xem một dấu hiệu có tồn tại không | Xác thực dấu hiệu trước khi sử dụng |
❓ Câu hỏi thường gặp (FAQ)
Sự khác biệt giữa trạng thái sản phẩm và thuộc tính sản phẩm là gì?
Trạng thái sản phẩm là nhãn tiếp thị (Mới, Giảm giá, Nổi bật) để lọc và gán nhãn, trong khi thuộc tính là thông số sản phẩm (Màu sắc, Kích thước, Chất liệu). Sử dụng trạng thái cho nhãn quảng cáo và thuộc tính cho thông số sản phẩm.
Một sản phẩm có thể có nhiều trạng thái cùng một lúc không?
Không. Một sản phẩm tham chiếu tối đa một trạng thái, được hiển thị dưới dạng statusIdentifier (dấu hiệu trạng thái) trên đối tượng sản phẩm.
Làm thế nào để tôi lọc sản phẩm theo trạng thái?
Sử dụng phương thức getProducts(body, langCode, userQuery) của mô-đun Products. Truyền một trường statusMarker bên trong mảng body của IFilterParams để lấy sản phẩm với trạng thái cụ thể.
Làm thế nào để tôi kiểm tra xem một dấu hiệu trạng thái có tồn tại không?
Sử dụng validateMarker() - nó trả về true nếu dấu hiệu tồn tại và false nếu không. SDK không thể tạo trạng thái; các dấu hiệu được định nghĩa trong bảng điều khiển quản trị theo các quy tắc đặt tên (chữ cái Latin, số, dấu gạch dưới, dấu gạch ngang).
Tôi có thể thay đổi thứ tự hiển thị của các trạng thái không?
Có. Trong bảng điều khiển quản trị, bạn có thể kéo và thả các trạng thái để thay đổi thứ tự của chúng. Điều này ảnh hưởng đến trường position, xác định thứ tự hiển thị trong ứng dụng của bạn.
Làm thế nào để tôi thêm kiểu dáng tùy chỉnh cho các nhãn trạng thái?
Lấy tất cả các trạng thái, sau đó ánh xạ các dấu hiệu trạng thái tới các lớp CSS hoặc kiểu nội tuyến trong mã frontend của bạn. Áp dụng các kiểu này khi hiển thị nhãn sản phẩm dựa trên statusIdentifier của sản phẩm.
🎓 Thực tiễn tốt nhất
- Sử dụng các dấu hiệu mô tả -
new_arrival, không phảistatus1. - Xác thực trước khi tham chiếu - gọi
validateMarker()trước khi mã hóa một dấu hiệu. - Hiển thị nhãn trạng thái - hiển thị nhãn
statusIdentifiercủa sản phẩm trong danh sách. - Lưu trữ trạng thái - chúng hiếm khi thay đổi, vì vậy hãy lưu trữ để cải thiện hiệu suất.
🔗 Tài liệu liên quan
- Bảng điều khiển quản trị OneEntry - Trạng thái sản phẩm - Tài liệu chính thức của bảng điều khiển quản trị
- Mô-đun Products - Quản lý sản phẩm với trạng thái
- Mô-đun Attributes - Thuộc tính sản phẩm so với trạng thái
- Mô-đun GeneralTypes - Các loại và danh mục sản phẩm
- Mô-đun Locales - Tên trạng thái đa ngôn ngữ