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

Giới thiệu

Một truy vấn trên toàn bộ dự án của bạn - sản phẩm, trang, khối, biểu mẫu, đơn hàng và nhiều hơn nữa, được nhóm theo loại thực thể.

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

Mô-đun Tìm kiếm bao bọc điểm cuối tìm kiếm chéo thực thể công khai. Bạn truyền vào một truy vấn văn bản và nhận lại mọi bản ghi có tên hoặc giá trị thuộc tính khớp với nó, từ 18 loại thực thể cùng một lúc, được nhóm theo loại và chú thích với cách mỗi bản ghi khớp.

Sử dụng nó để cung cấp một hộp "tìm kiếm mọi thứ" toàn cầu - kiểu mà hiển thị một vài sản phẩm, một vài trang và một biểu mẫu khớp trong một danh sách thả xuống - và sau đó đi sâu vào một loại duy nhất khi người dùng yêu cầu thêm.

Đây là tìm kiếm theo từ khóa: nó khớp với văn bản nguyên văn của tiêu đề, định danh, url và giá trị thuộc tính. Đối với tìm kiếm dựa trên ý nghĩa (một truy vấn như "áo khoác ấm cho mùa đông" khớp với một sản phẩm có tên "áo khoác cách nhiệt"), hãy sử dụng tìm kiếm ngữ nghĩa của các mô-đun riêng lẻ - xem Tìm kiếm vector so với tìm kiếm toàn cầu bên dưới.

🚀 Bắt đầu nhanh​

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


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

Tìm kiếm mọi thứ, sau đó đi qua các nhóm:

// Search every entity type for "winter".
const result = await Search.globalSearch('winter');

console.log(result.query); // "winter"

result.groups.forEach((group) => {
  console.log(group.type, group.items.length, group.hasMore);

  group.items.forEach((item) => {
    console.log(item.id, item.title, item.matchKind, item.fragment);
  });
});

✨ Khái niệm chính​

Nhóm​

Phản hồi không phải là một danh sách phẳng. Nó là { query, groups }, nơi mỗi nhóm chứa các bản ghi của một loại thực thể:

{
  query: "winter",
  groups: [
    { type: "products", items: [ /* … */ ], hasMore: false },
    { type: "pages",    items: [ /* … */ ], hasMore: false }
  ]
}

hasMore cho bạn biết liệu có nhiều bản ghi của loại đó tồn tại ngoài trang đã trả về hay không - tín hiệu để cung cấp một liên kết "hiển thị tất cả sản phẩm" mà chạy lại truy vấn ở chế độ đi sâu.

Ngữ cảnh khớp​

Mỗi mục mang theo ngữ cảnh về cách nó khớp, vì vậy bạn có thể hiển thị một hàng kết quả có ý nghĩa thay vì chỉ là tiêu đề trống:

TrườngĐiều này cho bạn biết
matchKindLoại xếp hạng của sự khớp: exact, title, attributeName hoặc attributeValue
matchedFieldTrường cụ thể đã khớp: id, title, identifier, url, attributeName, attributeValue, importId, nodeName
matchedAttributeThuộc tính mà sự khớp xảy ra (khi sự khớp đến từ một thuộc tính)
fragmentNgữ cảnh văn bản thuần xung quanh sự khớp, không có định dạng - hãy làm nổi bật nó theo cách của bạn
langCodeNgôn ngữ của giá trị đã khớp, để bạn có thể gán nhãn cho các kết quả chéo ngôn ngữ
parentBản ghi sở hữu cho các thực thể không có trang riêng (một slide → khối của nó, một đơn hàng → kho của nó)

Các loại thực thể​

types thu hẹp tìm kiếm. Truyền bất kỳ loại nào trong số này, và SDK sẽ gửi chúng dưới dạng phân cách bằng dấu phẩy:

sản phẩm, trang, khối, slide, mẫu, giảm giá, nhóm_người_dùng, người_dùng, admins, menus, biểu_mẫu, attributes_sets, attributes, đơn_hàng, workflow, sự kiện, đăng_ký, bộ_sưu_tập.

Bỏ qua types để tìm kiếm tất cả chúng.

Chế độ đi sâu​

offset và limit chuyển điểm cuối vào chế độ đi sâu - phân trang qua một loại thực thể thay vì xem trước tất cả chúng.

⚠️ Chúng chỉ được chấp nhận cùng nhau với chính xác một loại có thể truy cập trong types. Bất kỳ sự kết hợp nào khác sẽ trả về 400 - Chế độ đi sâu (limit/offset) yêu cầu chính xác một loại có thể truy cập trong types.

SDK không mặc định chúng: bỏ qua cả hai và mọi nhóm sẽ trở lại đầy đủ.

// Overview: every type, every group complete.
const overview = await Search.globalSearch('winter');

// Drilldown: page 1 of the products only.
const products = await Search.globalSearch('winter', ['products'], 'visible', 0, 20);

Tính khả dụng​

visibility lọc các bản ghi đã tìm kiếm: 'all' (mặc định), 'visible' hoặc 'hidden'.

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

  • id là một số cho hầu hết các loại, một chuỗi cho workflow và thuộc tính - number | string, vì vậy đừng giả định rằng các id là số khi xây dựng các khóa hoặc url.
  • title là tùy chọn: các bản ghi không có tên riêng (đơn hàng, người dùng không có đăng nhập) sẽ trở lại mà không có nó. Quay lại identifier hoặc subtitle.
  • subtitle mang theo dòng thứ hai mà loại đó có - một url trang, một kho đơn hàng, một tên nút.
  • attributeSetId chỉ có mặt cho type: "attributes", chỉ vào bộ mà thuộc tính thuộc về.
  • Chỉ các bản ghi mà người gọi hiện tại có thể thấy mới được trả về; tìm kiếm tôn trọng cùng một quy tắc truy cập như phần còn lại của API.

📊 Bảng tham khảo nhanh​

Phương thứcMô tả
globalSearch()Tìm kiếm tên và giá trị thuộc tính trên tất cả các loại thực thể

Tìm kiếm vector so với tìm kiếm toàn cầu​

Cả hai đều tìm các bản ghi từ một truy vấn văn bản, nhưng chúng trả lời các câu hỏi khác nhau:

globalSearchget…ByVectorSearch
Khớp vớiVăn bản nguyên văn của tiêu đề, định danh, url và giá trị thuộc tínhÝ nghĩa - sự tương đồng ngữ nghĩa (vector)
Phạm vi18 loại thực thể trong một cuộc gọiMột mô-đun mỗi cuộc gọi
Trả về{ query, groups[] } - được nhóm theo loại{ items, total } - một container phẳng
Sử dụng điển hìnhMột hộp tìm kiếm toàn cầu / bảng lệnh"Tìm cho tôi một cái gì đó giống như này" trên một thực thể

Các đối tác ngữ nghĩa sống trong chính các mô-đun: sản phẩm, trang, người dùng, đơn hàng, giảm giá, admins và dữ liệu biểu mẫu.

❓ Câu hỏi thường gặp (FAQ)​

Tại sao offset / limit của tôi lại trả về 400?​

Bởi vì chúng chỉ hoạt động trong chế độ đi sâu. Truyền chính xác một loại thực thể có thể truy cập trong types cùng với chúng, hoặc bỏ qua hoàn toàn.

Làm thế nào để tôi làm nổi bật sự khớp trong UI?​

Sử dụng fragment - nó là ngữ cảnh văn bản thuần xung quanh sự khớp, cố ý không có định dạng, vì vậy bạn có thể làm nổi bật truy vấn trong đó mà không cần làm sạch bất cứ điều gì.

Một mục không có title. Đó có phải là một lỗi không?​

Không. Các đơn hàng và người dùng không có đăng nhập không có tên riêng, vì vậy title đơn giản là không có. Hiển thị identifier, subtitle hoặc một nhãn cụ thể cho loại thay vào đó.

Tôi có thể tìm kiếm các bản ghi ẩn không?​

Truyền visibility: 'hidden' (hoặc 'all') - tùy thuộc vào các quy tắc truy cập áp dụng cho người gọi.

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

  • Giảm độ trễ của truy vấn trong một hộp tìm kiếm khi bạn gõ: mỗi lần gõ phím là một yêu cầu.
  • Hiển thị cuộc gọi tổng quan trước (không có offset/limit), sau đó chuyển sang chế độ đi sâu khi người dùng chọn một loại - đó chính xác là điều mà hasMore dành cho.
  • Thu hẹp types đến những gì UI của bạn thực sự có thể hiển thị; tìm kiếm 18 loại để hiển thị 2 là công việc lãng phí.
  • Đối xử với id như number | string khi xây dựng liên kết và khóa React.

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