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 coi 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ả 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á/ hàng tồn kho mà không cần triển khai lại

Ví dụ thực tế:

❌ Không có Mô-đun Sản phẩm (mã hóa cứng):
- Thêm sản phẩm mới → Thay đổi mã → Triển khai
- Thay đổi giá → Thay đổi mã → Triển khai
- 1000 sản phẩm = tệp mã khổng lồ

✅ Với Mô-đun Sản phẩm (động):
- Thêm sản phẩm mới → Cập nhật trong quản trị → Hiện ngay lập tức
- Thay đổi giá → Cập nhật trong quản trị → Hiện ngay lập tức
- 10,000 sản phẩm = các cuộc gọi API đơn giản

✨ 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á
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 phông đỏ kích thước M")
Hàng tồn kho - Số lượng hàng tồn, 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 phông (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:

📁 Điện tử
  ├─ 📱 Điện thoại thông minh
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptop
      ├─ MacBook Pro
      └─ Dell XPS

📁 Thời trang
  ├─ 👕 Áo phông
  └─ 👖 Quần 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 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 sản phẩm rẻ nhất trước
date	Sắp xếp theo ngày tạo	Hiện 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ị
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 (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 và liên kết sản phẩm

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 các cuộc 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: 1 trong sản xuất
Lưu cache danh sách sản phẩm để giảm các cuộc 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 UI

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"

"conditionMarker" mà theo đó các giá trị được lọc (mặc định không đặt), 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

🔗 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

Giới thiệu

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

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

✨ Khái niệm chính​

Sản phẩm là gì?​

Cấu trúc sản phẩm​

Tổ chức sản phẩm​

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

Kiến trúc Danh mục​

Cách lấy sản phẩm​

Giải thích về phân trang đơn giản​

Tùy chọn sắp xếp​

Lọc sản phẩm​

Tình trạng và liên kết sản phẩm​

📊 Bảng tham khảo nhanh - Các phương pháp phổ biến​

❓ 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?​

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)?​

Làm thế nào để tôi triển khai nút "Tải thêm"?​

Tôi có thể hiển thị sản phẩm từ nhiều danh mục không?​

Làm thế nào để tôi triển khai phần "Sản phẩm mới"?​

💡 Lưu ý quan trọng​

Thiết lập danh mục​

Các tính năng của danh mục​

Ngoài thương mại điện tử​

Tối ưu hóa hiệu suất​

Luôn lọc sản phẩm hoạt động​

Xử lý hình ảnh bị thiếu​

🎓 Thực hành tốt nhất​

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

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