Programmable Search Element Control API

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"><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 gname, thì Công cụ tìm kiếm có thể lập trình sẽ sử dụng thành phần cuối cùng trên trang.

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 ý.

true Khi thông số này không có hoặc bạn đặt thành "true", chúng tôi sẽ đặt một cookie chỉ dành cho lưu lượng truy cập không hợp lệ và chỉ sử dụng tính năng lưu trữ cục bộ trên lưu lượng truy cập có sự đồng ý.

false Khi bạn đặt thông số này thành "false", chúng tôi sẽ đặt một cookie chỉ dành cho lưu lượng truy cập không hợp lệ và sử dụng bộ nhớ cục bộ cho cả lưu lượng truy cập có người dùng đồng ý và không được đồng ý.

Mặc định: false

Cách sử dụng mẫu: <div class="gcse-search" data-ivt="true"></div>

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.

enabled Chỉ sử dụng bố cục thiết bị di động cho thiết bị di động.

disabled Không sử dụng bố cục dành cho thiết bị di động cho bất kỳ thiết bị nào.

forced Sử dụng bố cục thiết bị di động cho tất cả các thiết bị.

Mặc định: enabled

Cách sử dụng mẫu: <div class="gcse-search" data-mobileLayout="disabled"></div>

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 true, hãy bật tính năng tìm kiếm hình ảnh. Kết quả tìm kiếm hình ảnh sẽ hiển thị trên một thẻ riêng.

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à true, trang kết quả tìm kiếm sẽ hiển thị kết quả tìm kiếm hình ảnh theo mặc định. Các kết quả trên web sẽ xuất hiện trên một thẻ riêng.

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à classic, column hoặc popup.

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ụ: large, small, filtered_cse, 10.

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à jpg, gif, png, bmp, svg, webp, ico, raw.

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":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

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à cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived và tổ hợp các giá trị này.

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: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

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ợ: mono, gray, color.

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ể.

Giá trị được hỗ trợ

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ợ: red, orange, yellow, green, teal, blue, purple, pink, white, gray, black, brown.

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: <div class="gcse-search" data-image_filter="0"></div>

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ố.

Giá trị được hỗ trợ

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: icon, small, medium, large, xlarge, xxlarge hoặc huge.

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: <div class="gcse-search" data-image_sort_by="date"></div>

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à clipart (Hình mẫu), face (Khuôn mặt của người), lineart (Hình vẽ đường kẻ), stock (Ảnh trên kho ảnh), photo (Ảnh) và animated (Ảnh GIF động).

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: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

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:
  • Một số nguyên từ 1 đến 20
  • small: yêu cầu một tập hợp kết quả nhỏ, thường là 4 kết quả trên mỗi trang.
  • large: yêu cầu một tập hợp kết quả lớn, thường là 8 kết quả trên mỗi trang.
  • filtered_cse: yêu cầu tối đa 10 kết quả trên mỗi trang, tối đa 10 trang hoặc 100 kết quả.
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à offactive. 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":<div class="gcse-search" data-as_oq="term1 term2"></div>

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à cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived và tổ hợp các giá trị này.

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: <div class="gcse-search" data-as_sitesearch="example.com"></div>

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ể.

Giá trị được hỗ trợ

Cách sử dụng mẫu: <div class="gcse-search" data-cr="countryFR"></div>

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: <div class="gcse-search" data-filter="0"></div>

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.

Giá trị được hỗ trợ

Cách sử dụng mẫu: <div class="gcse-search" data-gl="fr"></div>

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ể.

Giá trị được hỗ trợ

Cách sử dụng mẫu: <div class="gcse-search" data-lr="lang_fr"></div>

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: <div class="gcse-search" data-sort_by="date"></div>

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à offactive. Bất kỳ

Lệnh gọi lại

Sơ đồ trình tự gọi lại
sơ đồ trình tự của các lệnh gọi lại từ JavaScript Phần tử tìm kiếm

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ợ.

Đăng ký lệnh gọi lại

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };
  

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àm render() hoặc hiển thị tất cả Phần tử tìm kiếm có hàm go()

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:

Ví dụ về lệnh gọi lại khởi động

Chúng ta cần bao gồm <div> với giá trị mã nhận dạng mà chúng ta muốn thêm mã Phần tử tìm kiếm:

    <div id="test"></div>
Thêm JavaScript này sau <div>. Xin lưu ý rằng thuộc tính này tham chiếu đến test, id mà chúng ta đã dùng để xác định <div>
const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};

Bao gồm HTML này để bắt đầu tải Phần tử tìm kiếm. Thay thế giá trị cx trong mệnh đề src bằng cx của riêng bạn.

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

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.

Ví dụ về cách bắt đầu tìm kiếm lệnh gọi lại
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

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.

Ví dụ về lệnh gọi lại sẵn sàng cho kết quả
    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

Cài đặt lệnh gọi lại này trong window.__gcse:

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Tương tự như với lệnh gọi lại bắt đầu tìm kiếm, cách nêu trên là một trong nhiều cách để đặt lệnh gọi lại trong đối tượng __gcse.

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ố promosresults 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ả.

Ví dụ về lệnh gọi lại kết quả được hiển thị
myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

Cài đặt lệnh gọi lại này trong window.__gcse:

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

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ị.

Ví dụ về lệnh gọi lại sẵn sàng cho kết quả hợp tác với lệnh gọi lại được hiển thị kết quả
const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};
Cài đặt lệnh gọi lại này bằng mã như sau trong khi thiết lập __gcse:
const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

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 promotionkế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.

Thuộc tính khuyến mãi
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
Thuộc tính đối tượng kết quả
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

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ố

Tên Nội dung mô tả
componentConfig Cấu hình cho thành phần Phần tử tìm kiếm có thể lập trình. Chỉ định những điều sau:
  • div (chuỗi|Phần tử): id của <div> hoặc phần tử div mà trong đó Phần tử tìm kiếm có thể lập trình sẽ xuất hiện.
  • tag (chuỗi): Loại thành phần sẽ hiển thị. (Khi opt_componentConfig được cung cấp, giá trị của thuộc tính tag phải là searchbox.) Các giá trị được phép là:
    • search: Hộp tìm kiếm và kết quả tìm kiếm, hiển thị cùng nhau
    • searchbox: Thành phần hộp tìm kiếm của Phần tử tìm kiếm có thể lập trình.
    • searchbox-only: Một hộp tìm kiếm độc lập sẽ được ghép nối với một khối kết quả tìm kiếm do opt_componentConfig chỉ định trong bố cục hai cột.
    • searchresults-only: Một khối kết quả tìm kiếm độc lập. Các lượt tìm kiếm được kích hoạt bởi một tham số truy vấn được nhúng trong URL hoặc bằng cách thực thi có lập trình.
  • gname (chuỗi): (Không bắt buộc) Tên riêng biệt cho thành phần này. 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.
  • attributes (Đối tượng): Các thuộc tính không bắt buộc dưới dạng một cặp khoá:giá trị. Thuộc tính được hỗ trợ.
opt_componentConfig Không bắt buộc. Đối số cấu hình thành phần thứ hai. Được dùng ở chế độ TWO_COLUMN để cung cấp thành phần searchresults. Chỉ định những điều sau:
  • div (chuỗi): id của <div> hoặc phần tử div mà phần tử này cần kết xuất.
  • tag (chuỗi): Loại thành phần sẽ hiển thị. Khi cung cấp opt_componentConfig, giá trị của thuộc tính tag phải là searchresults. Ngoài ra, giá trị của thuộc tính tag của componentConfig phải là searchbox.
  • gname (chuỗi): (Không bắt buộc) Tên riêng biệt cho thành phần này. 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 gname cho thành phần này. Nếu được cung cấp, thuộc tính này phải khớp với gname trong componentConfig.
  • attributes (Đối tượng): Các thuộc tính không bắt buộc dưới dạng một cặp khoá:giá trị. Các thuộc tính được hỗ trợ.
.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ố

Tên Nội dung mô tả
opt_container Vùng chứa chứa các thành phần Phần tử tìm kiếm để hiển thị. Chỉ định mã nhận dạng của vùng chứa (chuỗi) hoặc chính phần tử đó. Nếu bạn bỏ qua, tất cả các thành phần của Phần tử tìm kiếm có thể lập trình bên trong thẻ body của trang sẽ được hiển thị.
.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 element được trả về có các thuộc tính sau:

  • gname: Tên của đối tượng phần tử. 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 gname cho đối tượng. Thông tin khác.
  • type: Loại phần tử.
  • uiOptions: Các thuộc tính cuối cùng dùng để kết xuất phần tử.
  • execute – function(string): Thực thi một truy vấn có lập trình.
  • prefillQuery – function(string): Điền sẵn một chuỗi truy vấn vào hộp tìm kiếm mà không thực thi truy vấn.
  • getInputQuery – function(): Nhận giá trị hiện tại hiển thị trong hộp dữ liệu đầu vào.
  • clearAllResults – function(): Xoá chế độ kiểm soát bằng cách ẩn mọi thứ trừ hộp tìm kiếm, nếu có.

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.