Bạn có thể nhúng các thành phần của Công cụ tìm kiếm có thể lập trình (hộp tìm kiếm và trang kết quả tìm kiếm) trong trang web của mình và các ứng dụng web khác bằng mã đánh dấu HTML. Các phần tử của Công cụ tìm kiếm có thể lập trình này bao gồm các thành phần được hiển thị dựa trên các chế độ cài đặt do máy chủ Tìm kiếm có thể lập trình lưu trữ, cùng với mọi thành phần tuỳ chỉnh mà bạn tạo.
Tất cả JavaScript đều được tải không đồng bộ, cho phép trang web của bạn tiếp tục tải trong khi trình duyệt tìm nạp JavaScript của Công cụ tìm kiếm có thể lập trình.
Giới thiệu
Tài liệu này cung cấp mô hình cơ bản để thêm các phần tử của Công cụ tìm kiếm có thể lập trình vào trang web của bạn, cùng với nội dung giải thích về các thành phần có thể định cấu hình của phần tử đó và API JavaScript linh hoạt.
Phạm vi
Tài liệu này mô tả cách sử dụng các chức năng và thuộc tính dành riêng cho API Điều khiển của Công cụ tìm kiếm có thể lập trình.
Khả năng tương thích với trình duyệt
Bạn có thể xem danh sách các trình duyệt mà Công cụ tìm kiếm có thể lập trình hỗ trợ tại đây.
Thẻ Đối tượng người xem
Tài liệu này dành cho những nhà phát triển muốn thêm chức năng Tìm kiếm có thể lập trình của Google vào các trang của họ.
Phần tử Tìm kiếm có thể lập trình
Bạn có thể sử dụng mã đánh dấu HTML để thêm Phần tử tìm kiếm có thể lập trình vào trang của mình. Mỗi phần tử bao gồm ít nhất một thành phần: hộp tìm kiếm, một khối kết quả tìm kiếm hoặc cả hai. Hộp tìm kiếm chấp nhận dữ liệu nhập của người dùng theo bất kỳ cách nào sau đây:
- Cụm từ tìm kiếm được nhập vào trường nhập văn bản
- Chuỗi truy vấn được nhúng trong URL
- Thực thi có lập trình
Ngoài ra, khối kết quả tìm kiếm sẽ chấp nhận dữ liệu đầu vào theo các cách sau:
- Chuỗi truy vấn được nhúng trong URL
- Thực thi có lập trình
Hiện có những loại Phần tử tìm kiếm có thể lập trình sau đây:
Loại phần tử | (Các) thành phần | Nội dung mô tả |
---|---|---|
tiêu chuẩn | <div class="gcse-search"> |
Hộp tìm kiếm và kết quả tìm kiếm, hiển thị trong cùng một <div> . |
hai cột | <div class="gcse-searchbox"> và <div class="gcse-searchresults"> |
Bố cục hai cột với kết quả tìm kiếm ở một bên và hộp tìm kiếm ở bên còn lại. Nếu định chèn nhiều phần tử ở chế độ hai cột vào trang web của mình, thì bạn có thể dùng thuộc tính gname để ghép nối hộp tìm kiếm với một khối kết quả tìm kiếm. |
chỉ hộp tìm kiếm | <div class="gcse-searchbox-only"> |
Hộp tìm kiếm độc lập. |
chỉ kết quả tìm kiếm | <div class="gcse-searchresults-only"> |
Một khối kết quả tìm kiếm độc lập. |
Bạn có thể thêm số Phần tử tìm kiếm hợp lệ vào trang web của mình với số lượng bất kỳ. Đối với chế độ hai cột, tất cả các thành phần bắt buộc (khối hộp tìm kiếm và khối kết quả tìm kiếm) phải có sẵn.
Dưới đây là ví dụ về một Phần tử tìm kiếm đơn giản:
<!-- Put the following javascript before the closing </head> tag and replace 123456 with your own Programmable Search Engine ID. --> <script async src="https://cse.google.com/cse.js?cx=123456"></script> <!-- Place this tag where you want both of the search box and the search results to render --> <div class="gcse-search"></div>
Soạn nhiều tuỳ chọn bố cục bằng Phần tử tìm kiếm có thể lập trình
Các tuỳ chọn bố cục sau có trên trang Giao diện của bảng điều khiển Công cụ tìm kiếm có thể lập trình. Sau đây là một số nguyên tắc chung về việc soạn lựa chọn bố cục bằng Phần tử tìm kiếm có thể lập trình. Để xem bản minh hoạ về bất kỳ tuỳ chọn nào trong số này, hãy nhấp vào đường liên kết.
Lựa chọn | (Các) thành phần |
---|---|
Toàn chiều rộng | <div class="gcse-search"> |
Cao | <div class="gcse-search"> |
Hai cột | <div class="gcse-searchbox"> , <div class="gcse-searchresults"> |
Hai trang | <div class="gcse-searchbox-only"> trên trang đầu tiên, <div class="gcse-searchresults-only"> (hoặc các thành phần khác) trên trang thứ hai. |
Chỉ kết quả | <div class="gcse-searchresults-only"> |
Do Google lưu trữ | <div class="gcse-searchbox-only"> |
Thông tin khác về các tuỳ chọn bố cục.
Tuỳ chỉnh các phần tử Tìm kiếm có thể lập trình
Để tuỳ chỉnh màu sắc, phông chữ hoặc kiểu đường liên kết, hãy truy cập trang Giao diện của công cụ tìm kiếm có thể lập trình.
Bạn có thể sử dụng các thuộc tính không bắt buộc để ghi đè các cấu hình đã tạo trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình. Nhờ vậy, bạn có thể tạo ra một trải nghiệm tìm kiếm theo trang cụ thể.
Ví dụ: Mã sau đây tạo một hộp tìm kiếm để mở ra một trang kết quả (http://www.example.com?search=lady+gaga) trong cửa sổ mới. Giá trị của thuộc tính queryParameterName
, cùng với chuỗi truy vấn của người dùng, được dùng để tạo URL kết quả.
Xin lưu ý rằng thuộc tính queryParameterName
có tiền tố là data-
.
Tiền tố này là bắt buộc đối với tất cả các thuộc tính.
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
Nếu đã dùng bảng điều khiển của Công cụ tìm kiếm có thể lập trình để bật các tính năng như tự động hoàn thành hoặc tinh chỉnh, thì bạn có thể sử dụng các thuộc tính để tuỳ chỉnh các tính năng đó. Mọi tuỳ chỉnh mà bạn chỉ định bằng cách sử dụng các thuộc tính này sẽ ghi đè các chế độ cài đặt đã thực hiện trong bảng điều khiển. Ví dụ sau đây sẽ tạo một Phần tử tìm kiếm gồm hai cột với các tính năng sau:
- Đã bật tính năng quản lý nhật ký
- Đã đặt số lượt tự động hoàn thành tối đa được hiển thị thành 5
- Nhãn tinh lọc sẽ hiển thị dưới dạng đường liên kết.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
Thuộc tính được hỗ trợ
Thuộc tính | Loại | Nội dung mô tả | Thành phần |
---|---|---|---|
Tổng quan | |||
gname |
Chuỗi | (Không bắt buộc) Tên cho đối tượng Phần tử tìm kiếm. Tên dùng để truy xuất một thành phần liên kết theo tên hoặc để ghép nối một thành phần searchbox với thành phần searchresults . Nếu không được cung cấp, Công cụ tìm kiếm có thể lập trình sẽ tự động tạo một gname dựa trên thứ tự của các thành phần trên trang web. Ví dụ: searchbox-only không được đặt tên đầu tiên có gname "searchbox-only0" và thành phần thứ hai có gname "seachbox-only1", v.v.
Xin lưu ý rằng gname được tạo tự động cho một thành phần trong bố cục 2 cột sẽ là two-column . Ví dụ sau đây sử dụng gname storesearch để liên kết thành phần searchbox với thành phần searchresults : <div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> Khi truy xuất một đối tượng, nếu nhiều thành phần có cùng |
Bất kỳ |
autoSearchOnLoad |
Boolean | Chỉ định xem có thực hiện tìm kiếm theo truy vấn được nhúng trong URL của trang đang tải hay không. Lưu ý rằng chuỗi truy vấn phải có trong URL để thực thi tính năng tìm kiếm tự động. Mặc định: true . |
Bất kỳ |
enableHistory |
Boolean | Nếu giá trị là true , hãy bật tính năng quản lý nhật ký cho nút Quay lại và Chuyển tiếp của trình duyệt. Xem bản minh hoạ. |
searchbox chỉ hộp tìm kiếm |
queryParameterName |
Chuỗi | Tên tham số truy vấn — ví dụ: q (mặc định) hoặc query . Thông tin này sẽ được nhúng vào URL đó (ví dụ:
http://www.example.com?q=lady+gaga). Xin lưu ý rằng việc chỉ định tên tham số truy vấn sẽ không kích hoạt tính năng tự động tìm kiếm khi tải. Chuỗi truy vấn phải có trong URL để thực thi tính năng tự động tìm kiếm. |
Bất kỳ |
resultsUrl |
URL | URL của trang kết quả. (Mặc định là trang được lưu trữ trên Google.) | chỉ hộp tìm kiếm |
newWindow |
Boolean | Chỉ định xem trang kết quả có mở trong một cửa sổ mới hay không.
Mặc định: false . |
chỉ hộp tìm kiếm |
ivt |
Boolean |
Thông số này cho phép bạn cung cấp một boolean thông báo cho Google rằng bạn muốn cho phép quảng cáo sử dụng lưu trữ cục bộ và cookie chỉ dành cho lưu lượng truy cập không hợp lệ và lưu lượng truy cập cục bộ trên cả lưu lượng truy cập có người dùng đồng ý và không đồng ý.
Mặc định: Cách sử dụng mẫu: |
kết quả tìm kiếm chỉ kết quả tìm kiếm |
mobileLayout |
Chuỗi |
Chỉ định xem có nên sử dụng kiểu bố cục dành cho thiết bị di động cho thiết bị di động hay không.
Mặc định: Cách sử dụng mẫu: |
Bất kỳ |
Tự động hoàn thành | |||
enableAutoComplete |
Boolean | Chỉ dùng được nếu bạn đã bật tính năng tự động hoàn thành trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
true giúp bật tính năng tự động hoàn thành. |
Bất kỳ |
autoCompleteMaxCompletions |
Số nguyên | Số lượng cụm từ tự động hoàn thành tối đa để hiển thị. | searchbox chỉ hộp tìm kiếm |
autoCompleteMaxPromotions |
Số nguyên | Số lượng kết quả được thăng hạng tối đa sẽ hiển thị trong tính năng tự động hoàn thành. | searchbox chỉ hộp tìm kiếm |
autoCompleteValidLanguages |
Chuỗi | Danh sách ngôn ngữ được phân tách bằng dấu phẩy mà bạn cần bật tính năng tự động hoàn thành. Ngôn ngữ được hỗ trợ. | searchbox chỉ hộp tìm kiếm |
Tinh chỉnh | |||
defaultToRefinement |
Chuỗi | Chỉ dùng được nếu bạn đã tạo các mục tinh chỉnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình. Chỉ định nhãn tinh lọc mặc định để hiển thị.Lưu ý: Thuộc tính này không được hỗ trợ cho bố cục do Google lưu trữ. | Bất kỳ |
refinementStyle |
Chuỗi | Giá trị được chấp nhận là tab (mặc định) và link .
link chỉ được hỗ trợ nếu tính năng tìm kiếm hình ảnh bị tắt hoặc nếu tính năng tìm kiếm hình ảnh được bật nhưng tính năng tìm kiếm trên web bị tắt. |
kết quả tìm kiếm chỉ kết quả tìm kiếm |
Tìm kiếm hình ảnh | |||
enableImageSearch |
Boolean | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Nếu |
kết quả tìm kiếm chỉ kết quả tìm kiếm |
defaultToImageSearch |
Boolean | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Nếu giá trị là |
Bất kỳ |
imageSearchLayout |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Chỉ định bố cục của trang kết quả tìm kiếm hình ảnh. Giá trị được chấp nhận là |
kết quả tìm kiếm chỉ kết quả tìm kiếm |
imageSearchResultSetSize |
Số nguyên, Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Chỉ định kích thước tối đa của nhóm kết quả tìm kiếm dành cho tìm kiếm hình ảnh.
Ví dụ: |
Bất kỳ |
image_as_filetype |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Giới hạn kết quả trong những tệp của một tiện ích đã chỉ định. Các tiện ích được hỗ trợ là | Bất kỳ |
image_as_oq |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Lọc kết quả tìm kiếm bằng toán tử logic OR. Cách sử dụng mẫu nếu bạn muốn kết quả tìm kiếm có chứa "term1" hoặc "term2": | Bất kỳ |
image_as_rights |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Bộ lọc dựa trên việc cấp phép. Các giá trị được hỗ trợ là Hãy xem các kiểu kết hợp thông thường. | Bất kỳ |
image_as_sitesearch |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Hạn chế kết quả đối với các trang thuộc một trang web cụ thể. Cách sử dụng mẫu: | Bất kỳ |
image_colortype |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Giới hạn tìm kiếm trong hình ảnh đen trắng (đơn âm), thang màu xám hoặc hình ảnh màu. Các giá trị được hỗ trợ: | Bất kỳ |
image_cr |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Hạn chế kết quả tìm kiếm trong các tài liệu bắt nguồn từ một quốc gia cụ thể. | Bất kỳ |
image_dominantcolor |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Hạn chế tìm kiếm hình ảnh có màu nổi bật cụ thể.
Giá trị được hỗ trợ: | Bất kỳ |
image_filter |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Lọc tự động kết quả tìm kiếm. Giá trị được hỗ trợ: 0/1 Cách sử dụng mẫu: | Bất kỳ |
image_gl |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình. Đẩy mạnh kết quả tìm kiếm có quốc gia xuất xứ khớp với giá trị tham số. | Bất kỳ |
image_size |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Trả về hình ảnh có kích thước được chỉ định, trong đó kích thước có thể là một trong các kích thước sau: | Bất kỳ |
image_sort_by |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Sắp xếp kết quả theo ngày hoặc nội dung có cấu trúc khác. Để sắp xếp theo mức độ liên quan, hãy sử dụng chuỗi trống (image_sort_by=""). Cách sử dụng mẫu: | Bất kỳ |
image_type |
Chuỗi | Chỉ dùng được nếu bạn đã bật tính năng
tìm kiếm hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Hạn chế tìm kiếm hình ảnh thuộc một loại cụ thể.
Các giá trị được hỗ trợ là | Bất kỳ |
Tìm kiếm trên web | |||
disableWebSearch |
Boolean | Nếu true , hãy tắt tính năng tìm kiếm trên web. Thường chỉ được sử dụng nếu tính năng
tìm kiếm hình ảnh đã được bật trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình. |
kết quả tìm kiếm chỉ kết quả tìm kiếm |
webSearchQueryAddition |
Chuỗi | Đã thêm từ khoá bổ sung vào cụm từ tìm kiếm bằng hàm logic OR.
Cách sử dụng mẫu: |
Bất kỳ |
webSearchResultSetSize |
Số nguyên, Chuỗi | Kích thước tối đa của tập hợp kết quả. Áp dụng cho cả kết quả tìm kiếm bằng hình ảnh và tìm kiếm trên web. Chế độ mặc định phụ thuộc vào bố cục và việc định cấu hình Công cụ tìm kiếm có thể lập trình để tìm kiếm trên toàn bộ web hay chỉ những trang web được chỉ định. Các giá trị được chấp nhận bao gồm:
|
Bất kỳ |
webSearchSafesearch |
Chuỗi |
Chỉ định việc có bật tính năng SafeSearch cho các kết quả tìm kiếm trên web hay không. Giá trị được chấp nhận là off và active .
|
Bất kỳ |
as_filetype |
Chuỗi | Giới hạn kết quả trong những tệp của một tiện ích đã chỉ định. Bạn có thể xem danh sách các loại tệp mà Google có thể lập chỉ mục trong Trung tâm trợ giúp của Search Console. | Bất kỳ |
as_oq |
Chuỗi | Lọc kết quả tìm kiếm bằng toán tử logic OR.
Cách sử dụng mẫu nếu bạn muốn kết quả tìm kiếm có chứa "term1" hoặc "term2": |
Bất kỳ |
as_rights |
Chuỗi | Bộ lọc dựa trên việc cấp phép.
Các giá trị được hỗ trợ là Xem https://wiki.creativecommons.org/wiki/CC_Search_integration để biết các kết hợp điển hình. | Bất kỳ |
as_sitesearch |
Chuỗi | Hạn chế kết quả đối với các trang thuộc một trang web cụ thể.
Cách sử dụng mẫu: |
Bất kỳ |
cr |
Chuỗi | Hạn chế kết quả tìm kiếm trong các tài liệu bắt nguồn từ một quốc gia cụ thể.
Cách sử dụng mẫu: |
Bất kỳ |
filter |
Chuỗi | Lọc tự động kết quả tìm kiếm.
Giá trị được hỗ trợ: 0/1 Cách sử dụng mẫu: |
Bất kỳ |
gl |
Chuỗi | Đẩy mạnh kết quả tìm kiếm có quốc gia xuất xứ khớp với giá trị tham số.
Tính năng này sẽ chỉ hoạt động cùng với chế độ cài đặt language value. Cách sử dụng mẫu: |
Bất kỳ |
lr |
Chuỗi | Giới hạn kết quả tìm kiếm trong các tài liệu viết bằng một ngôn ngữ cụ thể.
Cách sử dụng mẫu: |
Bất kỳ |
sort_by |
Chuỗi | Sắp xếp kết quả theo ngày hoặc nội dung có cấu trúc khác. Giá trị thuộc tính phải là một trong các lựa chọn được cung cấp trong phần cài đặt Sắp xếp kết quả của ví dụ về kết quả tìm kiếm có thể lập trình.
Để sắp xếp theo mức độ liên quan, hãy sử dụng chuỗi trống (sort_by=""). Cách sử dụng mẫu: |
Bất kỳ |
Kết quả tìm kiếm | |||
enableOrderBy |
Boolean | Cho phép sắp xếp kết quả theo mức độ liên quan, ngày hoặc nhãn. | Bất kỳ |
linkTarget |
Chuỗi | Đặt mục tiêu liên kết. Mặc định: _blank . |
kết quả tìm kiếm chỉ kết quả tìm kiếm |
noResultsString |
Chuỗi | Chỉ định văn bản mặc định để hiển thị khi không có kết quả nào khớp với truy vấn. Chuỗi kết quả mặc định có thể dùng để cho thấy chuỗi đã bản địa hoá bằng tất cả ngôn ngữ được hỗ trợ, còn chuỗi tuỳ chỉnh thì không. | kết quả tìm kiếm chỉ kết quả tìm kiếm |
resultSetSize |
Số nguyên, Chuỗi | Kích thước tối đa của tập hợp kết quả. Ví dụ: large , small , filtered_cse , 10 . Chế độ mặc định phụ thuộc vào bố cục và việc công cụ này được định cấu hình để tìm kiếm trên toàn bộ web hay chỉ những trang web được chỉ định. |
Bất kỳ |
safeSearch |
Chuỗi | Chỉ định liệu có bật
Tìm kiếm an toàn cho cả tìm kiếm trên web và hình ảnh hay không. Giá trị được chấp nhận là off và active . |
Bất kỳ |
Lệnh gọi lại
Các lệnh gọi lại hỗ trợ việc kiểm soát chi tiết việc khởi chạy phần tử tìm kiếm và các quá trình tìm kiếm.
Các mã này được đăng ký bằng JavaScript Phần tử tìm kiếm thông qua đối tượng __gcse
chung. Lệnh gọi lại đăng ký minh hoạ việc đăng ký tất cả các lệnh gọi lại được hỗ trợ.
Lệnh gọi lại khởi động
Lệnh gọi lại khởi chạy được gọi trước khi JavaScript Phần tử tìm kiếm hiển thị các phần tử tìm kiếm trong DOM. Nếu bạn đặt parsetags
thành explicit
trong __gcse
, thì JavaScript Phần tử tìm kiếm sẽ để quá trình kết xuất Phần tử tìm kiếm trở thành lệnh gọi lại khởi chạy (như minh hoạ trong phần Đăng ký lệnh gọi lại).
Bạn có thể dùng thuộc tính này để chọn các phần tử cần kết xuất hoặc trì hoãn việc kết xuất các phần tử cho đến khi cần thiết. Cũng có thể ghi đè thuộc tính của các phần tử; ví dụ: có thể biến hộp tìm kiếm được định cấu hình thông qua Bảng điều khiển hoặc thuộc tính HTML để mặc định chuyển chức năng tìm kiếm trên web thành hộp tìm kiếm hình ảnh, hoặc chỉ định rằng các truy vấn được gửi qua biểu mẫu của Công cụ tìm kiếm có thể lập trình sẽ được thực thi trong phần tử chỉ kết quả tìm kiếm.
Xem bản minh hoạ.
Vai trò của lệnh gọi lại khởi động được kiểm soát bởi giá trị của thuộc tính parsetags
của __gcse
.
- Nếu giá trị của phần tử này là
onload
, thì JavaScript Phần tử tìm kiếm sẽ tự động hiển thị tất cả Phần tử tìm kiếm trên trang. Lệnh gọi lại khởi động vẫn được gọi, nhưng không chịu trách nhiệm hiển thị Phần tử tìm kiếm. - Nếu giá trị của lớp này là
explicit
, thì JavaScript của Phần tử tìm kiếm sẽ không hiển thị Phần tử tìm kiếm. Lệnh gọi lại có thể hiển thị các phần tử đó một cách có chọn lọc bằng cách sử dụng hàmrender()
hoặc hiển thị tất cả Phần tử tìm kiếm có hàmgo()
Mã sau đây minh hoạ cách hiển thị hộp tìm kiếm (cùng với kết quả tìm kiếm) trong div
bằng cách sử dụng lệnh gọi lại khởi động và thẻ phân tích cú pháp explicit
:
Tìm kiếm lệnh gọi lại
JavaScript phần tử tìm kiếm hỗ trợ 6 lệnh gọi lại hoạt động trong luồng kiểm soát tìm kiếm. Lệnh gọi lại tìm kiếm đi theo cặp, lệnh gọi lại tìm kiếm trên web và lệnh gọi lại tìm kiếm hình ảnh phù hợp:
- Bắt đầu tìm kiếm
- Để tìm kiếm hình ảnh
- Để tìm kiếm trên web
- Đã có kết quả
- Để tìm kiếm hình ảnh
- Để tìm kiếm trên web
- Kết quả hiển thị
- Để tìm kiếm hình ảnh
- Để tìm kiếm trên web
Giống như lệnh gọi lại khởi tạo,các lệnh gọi lại tìm kiếm được định cấu hình bằng cách sử dụng các mục nhập trong đối tượng __gcse
. Điều này xảy ra khi JavaScript Phần tử tìm kiếm khởi động. Các nội dung sửa đổi đối với __gcse
sau khi khởi động sẽ bị bỏ qua.
Mỗi lệnh gọi lại này đều được truyền gName
cho Phần tử tìm kiếm dưới dạng một đối số.
gname
sẽ hữu ích khi một trang chứa nhiều cụm từ tìm kiếm. Cung cấp giá trị gname
cho phần tử tìm kiếm bằng cách sử dụng thuộc tính data-gname
:
<div class="gcse-searchbox" data-gname="storesearch"></div>
Nếu HTML không xác định gname, thì JavaScript phần tử tìm kiếm sẽ tạo một giá trị sẽ vẫn nhất quán cho đến khi HTML được sửa đổi.
Cuộc gọi lại bắt đầu tìm kiếm hình ảnh/web
Các lệnh gọi lại bắt đầu tìm kiếm được gọi ngay trước khi JavaScript của Phần tử tìm kiếm yêu cầu kết quả tìm kiếm từ máy chủ. Một trường hợp sử dụng mẫu là sử dụng thời gian trong ngày tại địa phương để kiểm soát các thay đổi đối với truy vấn.
searchStartingCallback(gname, query)
gname
- Chuỗi nhận dạng của Phần tử tìm kiếm
query
Giá trị - do người dùng nhập (có thể do JavaScript phần tử tìm kiếm sửa đổi.)
Lệnh gọi lại trả về giá trị cần được dùng làm truy vấn cho lượt tìm kiếm này. Nếu phương thức này trả về một chuỗi trống, thì giá trị trả về sẽ bị bỏ qua và phương thức gọi sẽ sử dụng truy vấn chưa sửa đổi.
Ngoài ra, bạn có thể đặt hàm callback vào đối tượng __gcse
hoặc tự động thêm lệnh gọi lại vào đối tượng bằng JavaScript:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Ví dụ về việc bắt đầu tìm kiếm lệnh gọi lại
Ví dụ về lệnh gọi lại bắt đầu tìm kiếm trong Cuộc gọi lại bắt đầu tìm kiếm mẫu sẽ thêm morning
hoặc afternoon
vào truy vấn tuỳ thuộc vào thời gian trong ngày.
Cài đặt lệnh gọi lại này trong window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
<script
async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Lệnh gọi lại sẵn sàng cho kết quả tìm kiếm hình ảnh/web
Các lệnh gọi lại này được gọi ngay trước khi JavaScript của Phần tử tìm kiếm hiển thị chương trình khuyến mãi và kết quả. Một trường hợp sử dụng mẫu là lệnh gọi lại hiển thị chương trình khuyến mãi và dẫn đến một kiểu không thể chỉ định bằng chế độ tuỳ chỉnh thông thường.
resultsReadyCallback(gname, query, promos, results, div)
gname
- Chuỗi nhận dạng của Phần tử tìm kiếm
query
- truy vấn đã tạo ra các kết quả này
promos
- một mảng các đối tượng khuyến mãi, tương ứng với chương trình khuyến mãi phù hợp cho cụm từ tìm kiếm của người dùng. Xem định nghĩa đối tượng khuyến mãi.
results
- một mảng các đối tượng kết quả. Xem định nghĩa đối tượng kết quả.
div
- Một div HTML được đặt trong DOM, nơi Phần tử tìm kiếm thường đặt quảng cáo và kết quả tìm kiếm. Thông thường, JavaScript Phần tử tìm kiếm sẽ xử lý việc điền div này, nhưng lệnh gọi lại này có thể chọn ngừng tự động hiển thị kết quả và sử dụng
div
này để tự hiển thị kết quả.
Nếu lệnh gọi lại này trả về một giá trị true
, thì JavaScript của Phần tử tìm kiếm sẽ bỏ qua hoạt động chân trang của nó.
Lệnh gọi lại sẵn sàng cho kết quả mẫu
Lệnh gọi lại resultsReady
mẫu trong Gọi lại sẵn sàng cho kết quả mẫu sẽ ghi đè cách trình bày mặc định của chương trình khuyến mãi và kết quả với việc thay thế rất đơn giản.
Lệnh gọi lại được hiển thị kết quả tìm kiếm trên web/hình ảnh
Các lệnh gọi lại này được gọi ngay trước khi JavaScript của Phần tử tìm kiếm hiển thị chân trang. Ví dụ về các trường hợp sử dụng: một lệnh gọi lại bổ sung nội dung kết quả mà phần tử tìm kiếm không cho thấy, chẳng hạn như hộp đánh dấu lưu loại này hoặc thông tin không được hiển thị tự động, hoặc lệnh gọi lại bổ sung các nút để biết thêm thông tin.
Nếu một lệnh gọi lại được hiển thị cần thông tin có trong các tham số promos
và results
của lệnh gọi lại sẵn sàng cho kết quả, thì bạn có thể truyền thông tin đó giữa các lệnh gọi lại, như sau:
callback(gname, query, promoElts, resultElts);
gname
- Chuỗi nhận dạng của Phần tử tìm kiếm
query
- chuỗi tìm kiếm.
promoElts
- một mảng các phần tử DOM có chứa chương trình khuyến mãi.
resultElts
- một mảng các phần tử DOM chứa kết quả.
Không có giá trị trả về.
Ví dụ về lệnh gọi lại được hiển thị kết quả
Ví dụ về lệnh gọi lại resultsRendered
trong Gọi lại kết quả được hiển thị mẫu sẽ thêm hộp đánh dấu Keep giả vào từng chương trình khuyến mãi và kết quả.
Nếu lệnh gọi lại được hiển thị kết quả cần thông tin đã được chuyển đến lệnh gọi lại sẵn sàng cho kết quả, thì bạn có thể truyền dữ liệu đó giữa các lệnh gọi lại. Ví dụ sau đây cho thấy một trong nhiều cách để chuyển giá trị xếp hạng từ richSnippet
từ lệnh gọi lại sẵn sàng cho kết quả đến lệnh gọi lại kết quả được hiển thị.
Các ví dụ khác về lệnh gọi lại
Bạn có thể xem thêm các ví dụ khác về lệnh gọi lại trong tài liệu Ví dụ khác về lệnh gọi lại.
Thuộc tính kết quả và chương trình khuyến mãi
Sử dụng ký hiệu JSDoc, đây là thuộc tính của các đối tượng promotion và kết quả. Tại đây, chúng tôi liệt kê tất cả các thuộc tính có thể có. Sự hiện diện của nhiều cơ sở lưu trú phụ thuộc vào thông tin chi tiết của chương trình khuyến mãi hoặc kết quả tìm kiếm.
richSnippet
trong kết quả có loại rời của một mảng đối tượng. Giá trị của các mục trong mảng này chịu sự kiểm soát của dữ liệu có cấu trúc có trên trang web cho từng kết quả tìm kiếm. Ví dụ: một trang web đánh giá có thể bao gồm dữ liệu có cấu trúc thêm mục mảng này vào richSnippet
:
'review': { 'ratingstars': '3.0', 'ratingcount': '1024', },
API Kiểm soát phần tử tìm kiếm có thể lập trình (Phiên bản 2)
Đối tượng google.search.cse.element
phát hành các hàm tĩnh sau đây:
Chức năng | Nội dung mô tả | ||||||
---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
Hiển thị Phần tử tìm kiếm.
Thông số
|
||||||
.go(opt_container) |
Hiển thị tất cả các thẻ/lớp Phần tử tìm kiếm trong vùng chứa được chỉ định.
Thông số
|
||||||
.getElement(gname) |
Lấy đối tượng phần tử theo gname . Nếu không tìm thấy, hãy trả về giá trị rỗng.
Đối tượng
Mã sau đây thực thi truy vấn "news" trong Phần tử tìm kiếm "element1": var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
Trả về bản đồ của tất cả đối tượng phần tử đã tạo thành công, được khoá bằng gname . |