Giới thiệu
Quản lý sản phẩm thương mại điện tử với các danh mục động, bộ lọc và tìm kiếm.
🎯 Mô-đun này làm gì?
Mô-đun Products (Danh mục) là một mô-đun độc lập cho phép bạn tạo, truy xuất, lọc và quản lý sản phẩm trong cửa hàng trực tuyến hoặc bộ sưu tập đa phương tiện của bạn. Nó cung cấp các công cụ rất linh hoạt để tạo danh mục sản phẩm hoặc bộ sưu tập đa phương tiện với các tính năng tìm kiếm, bộ lọc và tổ chức mạnh mẽ.
Danh mục cho phép tạo, tải lên, chỉnh sửa và lọc các danh mục thông qua một giao diện trực quan. Ngoài thương mại điện tử, nó hỗ trợ các ứng dụng thay thế như bộ sưu tập đa phương tiện, chứng minh tính linh hoạt của nó như một công cụ quản lý nội dung.
Hãy nghĩ về nó như một kho hàng kỹ thuật số của bạn - bạn quản lý hàng tồn kho sản phẩm của mình trong bảng điều khiển quản trị OneEntry (Danh mục > Sản phẩm), và ứng dụng của bạn lấy sản phẩm một cách động với các tính năng tìm kiếm, bộ lọc và sắp xếp mạnh mẽ.
📖 Giải thích đơn giản
Hãy tưởng tượng bạn đang xây dựng một cửa hàng trực tuyến bán:
- 👟 Giày thể thao - với kích thước, màu sắc, giá cả
- 📱 Điện tử - với thông số kỹ thuật, hình ảnh, đánh giá
- 👕 Thời trang - với kích thước, chất liệu, biến thể
- 📚 Sách - với tác giả, giá cả, mô tả
✅ Thay vì mã hóa cứng từng sản phẩm, bạn:
- Thêm sản phẩm trong bảng điều khiển quản trị OneEntry (với tất cả các chi tiết)
- Lấy sản phẩm một cách động bằng cách sử dụng mô-đun này
- Lọc theo danh mục, khoảng giá, tình trạng
- Tìm kiếm sản phẩm theo tên hoặc mô tả
- Sắp xếp theo giá, ngày, độ phổ biến
- Cập nhật giá cả/tồn kho mà không cần triển khai lại
Ví dụ thực tế:
❌ Without Products Module (hardcoded):
- Add new product → Change code → Deploy
- Change price → Code change → Deploy
- 1000 products = massive code file
✅ With Products Module (dynamic):
- Add new product → Update in admin → Live instantly
- Change price → Update in admin → Live instantly
- 10,000 products = simple API calls
✨ Khái niệm chính
Sản phẩm là gì?
Một sản phẩm là một mặt hàng bạn bán, bao gồm:
- Thông tin cơ bản - Tên, mô tả, SKU, giá cả
- Hình ảnh - Ảnh sản phẩm, bộ sưu tập
- Biến thể - Kích thước, màu sắc, tùy chọn (ví dụ: "Áo thun đỏ kích thước M")
- Hàng tồn kho - Số lượng tồn kho, tình trạng
- Thuộc tính tùy chỉnh - Bất kỳ trường nào bạn định nghĩa (thương hiệu, chất liệu, trọng lượng, v.v.)
- SEO - Tiêu đề meta, mô tả, từ khóa
- Tình trạng - Hoạt động, nháp, hết hàng
- Địa phương hóa - Hỗ trợ đa ngôn ngữ
Cấu trúc sản phẩm
Sản phẩm có thể có các cấu trúc khác nhau:
| Loại | Mô tả | Ví dụ |
|---|---|---|
| Sản phẩm đơn giản | Mặt hàng đơn lẻ, không có biến thể | Sách, Áp phích |
| Sản phẩm có biến thể | Nhiều tùy chọn (kích thước, màu sắc) | Áo thun (S/M/L, Đỏ/Xanh) |
| Sản phẩm kỹ thuật số | Mặt hàng có thể tải xuống | E-book, Phần mềm |
| Gói | Nhóm sản phẩm | Bộ khởi động, Bộ quà tặng |
Tổ chức sản phẩm
Sản phẩm được tổ chức thông qua một số tính năng chính:
- Danh mục - Tổ chức thành các phần (Danh mục là các trang của loại Danh mục được tạo trong mô-đun Trang)
- Tình trạng sản phẩm - Tạo các điều kiện lọc bổ sung ngoài các bộ lọc thuộc tính hiện có
- Liên kết sản phẩm - Thiết lập kết nối giữa các sản phẩm dựa trên tiêu chí thuộc tính
- Bộ lọc sản phẩm - Tìm kiếm nhanh bằng cách sử dụng các tiêu chí lọc đã chỉ định
- Thuộc tính tùy chỉnh - Thương hiệu, Kích thước, Màu sắc, Chất liệu, v.v.
Ví dụ về cấu trúc:
📁 Electronics
├─ 📱 Smartphones
│ ├─ iPhone 15 Pro
│ └─ Samsung Galaxy S24
└─ 💻 Laptops
├─ MacBook Pro
└─ Dell XPS
📁 Clothing
├─ 👕 T-Shirts
└─ 👖 Jeans
📋 Những điều bạn cần biết
Kiến trúc danh mục
Quan trọng: Các danh mục của danh mục là các trang của loại Danh mục được tạo thông qua mô-đun Trang. Bạn cần tạo các danh mục trước khi thêm sản phẩm.
Các tính năng của danh mục:
- Tab Sản phẩm - Nơi làm việc chính để tạo và quản lý các mục danh mục
- Bộ lọc sản phẩm - Tìm kiếm nhanh bằng cách sử dụng các tiêu chí đã chỉ định
- Liên kết sản phẩm - Kết nối các sản phẩm dựa trên tiêu chí thuộc tính (ví dụ: tất cả điện thoại màu đen)
- Tình trạng sản phẩm - Các điều kiện lọc bổ sung cho tổ chức
- Tải lên danh mục - Nhập dữ liệu danh mục hàng loạt
- Cài đặt - Tùy chọn cấu hình với các trường nhập số
Cách lấy sản phẩm
| Phương pháp | Khi nào sử dụng | Ví dụ |
|---|---|---|
| getProducts() | Liệt kê sản phẩm với bộ lọc/tìm kiếm | Trang danh mục cửa hàng |
| getProductsByPageId() | Sản phẩm từ danh mục cụ thể (theo ID) | Trang danh mục |
| getProductsByPageUrl() | Sản phẩm từ danh mục cụ thể (theo URL) | Trang danh mục theo URL |
| getProductById() | Lấy sản phẩm đơn lẻ theo ID | Trang chi tiết sản phẩm |
| getRelatedProductsById() | Lấy sản phẩm liên quan/tương tự | Phần "Bạn cũng có thể thích" |
| searchProduct() | Tìm kiếm sản phẩm theo truy vấn | Chức năng tìm kiếm |
Giải thích về phân trang đơn giản
Khi bạn có 1000 sản phẩm, bạn không tải tất cả cùng một lúc:
Công thức offset: offset = (pageNumber - 1) * limit
Tùy chọn sắp xếp
Sắp xếp sản phẩm theo các trường khác nhau:
| sortKey | Chức năng | Ví dụ sử dụng |
|---|---|---|
| price | Sắp xếp theo giá | Hiển thị sản phẩm rẻ nhất trước |
| date | Sắp xếp theo ngày tạo | Hiển thị sản phẩm mới nhất |
| title | Sắp xếp theo thứ tự chữ cái | Danh sách sản phẩm A-Z |
| position | Thứ tự tùy chỉnh (mặc định) | Thứ tự được chọn từ quản trị viên |
| id | Sắp xếp theo ID | Sắp xếp kỹ thuật |
Thứ tự sắp xếp:
- ASC (Tăng dần) - Từ thấp đến cao (A→Z, 0→9, rẻ→đắt)
- DESC (Giảm dần) - Từ cao đến thấp (Z→A, 9→0, đắt→rẻ)
Lọc sản phẩm
Sử dụng bộ lọc để thu hẹp kết quả:
Ký hiệu điều kiện:
| Ký hiệu | Ý nghĩa | Ví dụ |
|---|---|---|
| eq | Bằng (trùng khớp chính xác) | Giá = $50 |
| neq | Không bằng | Tình trạng ≠ "hết hàng" |
| in | Chứa (một trong số) | Màu sắc trong ["đỏ", "xanh"] |
| nin | Không chứa | Danh mục không trong ["lưu trữ"] |
| mth | Lớn hơn | Giá > $100 |
| lth | Nhỏ hơn | Giá < $50 |
| exs | Tồn tại (có giá trị) | Có giảm giá |
| nexs | Không tồn tại (trống) | Không có giảm giá |
Tình trạng sản phẩm và liên kết
Tình trạng sản phẩm tạo ra các điều kiện lọc bổ sung ngoài các bộ lọc thuộc tính hiện có để tổ chức sản phẩm một cách tinh vi hơn.
Liên kết sản phẩm cho phép thiết lập kết nối giữa các sản phẩm dựa trên tiêu chí thuộc tính. Ví dụ, bạn có thể liên kết tất cả các sản phẩm có thuộc tính màu sắc giống nhau (ví dụ: tất cả điện thoại màu đen cùng nhau).
📊 Bảng tham khảo nhanh - Các phương pháp phổ biến
| Phương pháp | Mô tả | Trường hợp sử dụng |
|---|---|---|
| getProducts() | Lấy tất cả sản phẩm với bộ lọc/sắp xếp | Trang danh mục chính |
| getProductById() | Lấy sản phẩm đơn lẻ theo ID | Trang chi tiết sản phẩm |
| getProductsByPageId() | Lấy sản phẩm từ danh mục theo ID trang | Trang danh mục |
| getProductsByPageUrl() | Lấy sản phẩm từ danh mục theo URL trang | Trang danh mục theo URL |
| getRelatedProductsById() | Lấy sản phẩm liên quan/tương tự | Phần "Bạn cũng có thể thích" |
| searchProduct() | Tìm kiếm sản phẩm theo truy vấn | Chức năng tìm kiếm |
| getProductsCount() | Lấy tổng số lượng sản phẩm | Thông tin phân trang |
| getProductsCountByPageId() | Lấy số lượng sản phẩm theo ID danh mục | Phân trang danh mục |
| getProductsCountByPageUrl() | Lấy số lượng sản phẩm theo URL danh mục | Phân trang danh mục |
| getProductBlockById() | Lấy khối sản phẩm theo ID | Các khối nội dung sản phẩm |
| getProductsEmptyPage() | Lấy cấu trúc trang sản phẩm trống | Xử lý trạng thái trống |
| getProductsPriceByPageUrl() | Lấy giá sản phẩm theo URL trang | Lọc theo giá |
❓ Câu hỏi thường gặp (FAQ)
Tôi có thể lọc theo nhiều tiêu chí cùng một lúc không?
Có! Kết hợp nhiều bộ lọc trong mảng.
Làm thế nào để tôi xử lý các biến thể sản phẩm (kích thước, màu sắc)?
Các biến thể sản phẩm được lưu trữ trong attributeValues.
Làm thế nào để tôi triển khai nút "Tải thêm"?
Sử dụng offset để tải thêm sản phẩm.
Tôi có thể hiển thị sản phẩm từ nhiều danh mục không?
Có, sử dụng ký hiệu điều kiện category in.
Làm thế nào để tôi triển khai phần "Sản phẩm mới"?
Sắp xếp theo ngày tạo hoặc sử dụng danh mục cha để sắp xếp thủ công.
💡 Lưu ý quan trọng
Thiết lập danh mục
Quan trọng: Trước khi thêm sản phẩm, bạn phải tạo các danh mục thông qua mô-đun Trang. Các danh mục của danh mục là các trang của loại Danh mục.
Quy trình làm việc:
- Đi đến mô-đun Trang trong bảng điều khiển quản trị
- Tạo các trang với loại "Danh mục"
- Những trang này trở thành các danh mục sản phẩm của bạn
- Thêm sản phẩm vào các danh mục này qua Danh mục > Sản phẩm
Các tính năng của danh mục
Mô-đun Danh mục cung cấp các công cụ toàn diện:
- Tab Sản phẩm - Nơi làm việc chính để tạo/quản lý các mục danh mục
- Bộ lọc sản phẩm - Cho phép tìm kiếm nhanh bằng cách sử dụng các tiêu chí đã chỉ định
- Liên kết sản phẩm - Kết nối các sản phẩm liên quan dựa trên thuộc tính
- Tình trạng sản phẩm - Tạo các điều kiện lọc tùy chỉnh
- Tải lên danh mục - Nhập hàng loạt sản phẩm
- Cài đặt - Cấu hình hành vi của danh mục
Ngoài thương mại điện tử
Danh mục không chỉ giới hạn ở sản phẩm - nó có thể được sử dụng cho:
- Bộ sưu tập đa phương tiện - Ảnh, video, bộ sưu tập nghệ thuật
- Mục danh mục - Công việc thiết kế, nghiên cứu trường hợp
- Thư viện tài liệu - Tài nguyên, tải xuống
- Danh mục sự kiện - Hội nghị, hội thảo trực tuyến
- Bộ sưu tập công thức - Thức ăn, đồ uống, nấu ăn
Tối ưu hóa hiệu suất
Lưu cache các sản phẩm thường xuyên được truy cập để giảm số lần gọi API và cải thiện thời gian tải.
Luôn lọc sản phẩm hoạt động
Trong sản xuất, luôn chỉ hiển thị các sản phẩm hoạt động bằng cách lọc với statusId: 1.
Xử lý hình ảnh bị thiếu
Cung cấp hình ảnh dự phòng cho các sản phẩm không có hình ảnh để duy trì giao diện người dùng nhất quán.
🎓 Thực hành tốt nhất
- Luôn sử dụng phân trang (giới hạn + offset)
- Lọc theo
statusId: 1trong sản xuất - Lưu cache danh sách sản phẩm để giảm số lần gọi API
- Xử lý "hết hàng" một cách khéo léo
- Cung cấp hình ảnh dự phòng
- Sử dụng ký hiệu cho các sản phẩm nổi bật (không phải ID)
- Triển khai tìm kiếm với debouncing
- Thêm trạng thái tải trong giao diện người dùng
Thêm thông tin về Danh mục trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/catalog
Định nghĩa của mô-đun Products
const { Products } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
Mô-đun này chấp nhận một tập hợp các tham số người dùng gọi là userQuery. Nếu các tham số không được truyền vào phương thức, giá trị mặc định sẽ được áp dụng. Một số phương thức chấp nhận body như một tham số để lọc. Nếu bạn không muốn thiết lập sắp xếp, hãy truyền một mảng rỗng hoặc không truyền gì cả.
Tham số:
const userQuery = { offset: 0, limit: 30, sortOrder: 'DESC', sortKey: 'id',}
Schema
offset: số
Tham số phân trang. Mặc định 0
ví dụ: 0
limit: số
tham số phân trang. Mặc định 30
ví dụ: 30
sortKey: chuỗi
Trường để sắp xếp (mặc định không đặt - sắp xếp theo vị trí, các giá trị có thể: id, title, date, price, position)
Các giá trị có sẵn: id, position, title, date, price
sortOrder: chuỗi
thứ tự sắp xếp DESC | ASC (mặc định DESC)
ví dụ: "DESC"
Mặc định, bạn có thể lấy 10 đối tượng. Điều này là do giới hạn bản ghi trong cài đặt quyền của mô-đun.
Để phân trang hoạt động chính xác, bạn cần cấu hình Quyền mô-đun theo nhu cầu của bạn trong phần tương ứng.
"conditionMarker" mà qua đó các giá trị được lọc (không được đặt theo mặc định), các giá trị có thể:
'in' - Chứa,
'nin' - Không chứa,
'eq' - Bằng,
'neq' - Không bằng,
'mth' - Lớn hơn,
'lth' - Nhỏ hơn,
'exs' - Tồn tại,
'nexs' - Không tồn tại
Sử dụng các điều kiện để tìm dữ liệu sản phẩm cụ thể:
attributeMarker: Định danh văn bản của thuộc tính đã được lập chỉ mục mà qua đó các giá trị được lọc. conditionMarker: Loại điều kiện để áp dụng cho giá trị thuộc tính.
| Ký hiệu | Ý nghĩa | Ví dụ |
|---|---|---|
| eq | Bằng | statusId = 1 (chỉ hoạt động) |
| neq | Không bằng | category ≠ "lưu trữ" |
| in | Chứa (một trong số) | category in ["điện tử", "sách"] |
| nin | Không chứa | brand not in ["fake_brand"] |
| exs | Tồn tại (có giá trị) | Có mô tả |
| nexs | Không tồn tại | Không có hình ảnh |
conditionValue: Giá trị để so sánh.
🔗 Tài liệu liên quan
- Bảng điều khiển quản trị OneEntry - Danh mục - Tài liệu chính thức về bảng điều khiển quản trị
- Mô-đun Trang - Tạo các danh mục danh mục (các trang loại Danh mục)
- Mô-đun AttributesSets - Các trường và thuộc tính sản phẩm tùy chỉnh
- Mô-đun Templates - Mẫu hiển thị sản phẩm
- Mô-đun Blocks - Các khối nội dung sản phẩm có thể tái sử dụng
- Mô-đun Orders - Xử lý đơn hàng sản phẩm