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 bạn và các ứng dụng web khác bằng mã đánh dấu HTML. Các 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ài đặt do máy chủ Tìm kiếm có thể lập trình, cùng với bất kỳ thao tác tuỳ chỉnh nào bạn thực hiện.

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ông cụ tìm kiếm có thể lập trình các phần tử vào trang web của bạn, cùng với phần giải thích về các phần tử thành phần có thể định cấu hình và API JavaScript linh hoạt.

Phạm vi

Tài liệu này mô tả cách sử dụng các hàm và thuộc tính dành riêng cho API Điều khiển công cụ tìm kiếm có thể lập trình.

Khả năng tương thích của 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 các nhà phát triển muốn thêm công cụ Google Programmable Chức năng tìm kiếm cho 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ột phần tử bao gồm ít nhất một thành phần: một hộp tìm kiếm, một khối tìm kiếm kết quả hoặc cả hai. Hộp tìm kiếm sẽ chấp nhận hoạt động đầu vào của người dùng trong bất kỳ trường nào sau đây cách:

  • Một 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 thông tin đầu vào trong các cách sau:

  • Chuỗi truy vấn được nhúng trong URL
  • Thực thi có lập trình

Có các loại Phần tử tìm kiếm có thể lập trình sau đây:

Loại phần tử Thành phần Mô tả
tiêu chuẩn <div class="gcse-search"> Hộp tìm kiếm và kết quả tìm kiếm, được 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 kia. Nếu bạn định chèn nhiều phần tử ở chế độ hai cột trên trang web của mình, bạn có thể sử dụng thuộc tính gname để ghép nối hộp tìm kiếm với khối kết quả tìm kiếm.
chỉ hộp tìm kiếm <div class="gcse-searchbox-only"> Một hộp tìm kiếm độc lập.
searchresults-only <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ố lượng Phần tử tìm kiếm hợp lệ bất kỳ vào trang web của mình. Cho hai cột chế độ xem, tất cả các thành phần bắt buộc (hộp tìm kiếm và công cụ tìm kiếm khối kết quả) phải hiển thị.

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 lựa chọn bố cục bằng Phần tử tìm kiếm có thể lập trình

Các lựa chọn bố cục sau đây có sẵn trên trang Giao diện của bảng điều khiển của Công cụ tìm kiếm có thể lập trình. Dưới đây là một số nguyên tắc chung về cách tạo 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ỳ lựa chọn nào trong số này, hãy nhấp vào đường liên kết.

Phương thức Thành phần
Toàn chiều rộng <div class="gcse-search">
Thu gọn <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">
Lưu trữ trên Google <div class="gcse-searchbox-only">

Thông tin khác về các chế độ bố cục.

Tuỳ chỉnh 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 vào 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ấu hình được tạo trong Công cụ tìm kiếm có thể lập trình bảng điều khiển. Điều này cho phép bạn tạo trải nghiệm tìm kiếm theo trang cụ thể. Ví dụ: mã sau đây tạo ra 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 Thuộc tính queryParameterName cùng với chuỗi truy vấn của người dùng là được dùng để tạo URL kết quả.

Xin lưu ý rằng thuộc tính queryParameterName có tiền tố data-. Tiền tố này là bắt buộc cho 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 bạn đã 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 tất hoặc tinh chỉnh, bạn có thể sử dụng các thuộc tính để tuỳ chỉnh các tính năng đó. Bất kỳ tuỳ chỉnh nào 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 được thực hiện trong bảng điều khiển. Ví dụ sau đây sẽ tạo Phần tử tìm kiếm hai cột có các tính năng sau:

  • Tính năng quản lý nhật ký đang bật
  • Số lượng nội dung tự động hoàn thành tối đa được hiển thị được đặt thành 5
  • Các nhãn tinh lọc sẽ xuất hiện 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 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 được 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 searchbox có 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ụ: tên chưa đặt tên đầu tiên searchbox-onlygname "searchbox-only0" và URL 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 hai cột sẽ là two-column. Ví dụ sau đây sử dụng gname storesearch để liên kết một searchbox thành phần có 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 một đối tượng gname, 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 .

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 hay không của trang đang tải. Xin lưu ý rằng chuỗi truy vấn phải có trong URL để thực hiện tìm kiếm tự động. Mặc định: true. Bất kỳ
enableHistory Boolean Nếu là true, hãy bật tính năng quản lý nhật ký cho trình duyệt Quay lại và nút Tiến. Xem bản minh hoạ.

hộp tìm kiếm

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 chỉ có tên tham số truy vấn sẽ không kích hoạt tự động tìm kiếm khi tải. Một truy vấn chuỗi phải có trong URL để thực thi tìm kiếm tự động. 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 cửa sổ mới hay không. Mặc định: false. chỉ hộp tìm kiếm
ivt Boolean

Tham số này cho phép bạn cung cấp boolean cho Google biết rằng bạn muốn cho phép quảng cáo sử dụng cookie chỉ dùng để phát hiện lưu lượng truy cập không hợp lệ & cục bộ trên cả miền đã đồng ý và lưu lượng truy cập không có sự đồng ý.

true Khi không có thông số này hoặc bạn đặt thông số này thành "true" chúng tôi sẽ thiết lập cookie chỉ dùng để phát hiện lưu lượng truy cập không hợp lệ và chỉ sử dụng phương pháp lưu trữ cục bộ cho lưu lượng truy cập có sự đồng ý.

false Khi bạn đặt tham số này thành "false" chúng tôi sẽ đặt một giá trị không hợp lệ cookie chỉ dành cho lưu lượng truy cập và sử dụng phương pháp lưu trữ cục bộ cho cả lưu lượng truy cập có sự đồng ý và không có sự đồng ý của người dùng.

Mặc định: false

Ví dụ về cách sử dụng: <div class="gcse-search" data-ivt="true"></div>

kết quả tìm kiếm

searchresults-only

mobileLayout Chuỗi

Chỉ định xem có nên sử dụng kiểu bố cục cho thiết bị di động cho thiết bị di động hay không.

enabled Chỉ dùng bố cục trên thiết bị di động cho các 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 dành cho thiết bị di động cho tất cả các thiết bị.

Mặc định: enabled

Ví dụ về cách sử dụng: <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 tính năng tự động hoàn thà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. true bật tính năng tự động hoàn thành. Bất kỳ
autoCompleteMaxCompletions Số nguyên Số lượng nội dung tự động hoàn thành tối đa cần hiển thị.

hộp tìm kiếm

chỉ hộp tìm kiếm

autoCompleteMaxPromotions Số nguyên Số lượng chương trình khuyến mãi tối đa có thể hiển thị trong tính năng tự động hoàn thành.

hộp tìm kiếm

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à tính năng tự động hoàn thành sẽ được sử dụng bật. Ngôn ngữ được hỗ trợ.

hộp tìm kiếm

chỉ hộp tìm kiếm

Sàng lọc
defaultToRefinement Chuỗi Chỉ có sẵn nếu các mục tinh chỉnh đã được tạo trong Bảng điều khiển có thể lập trình cho Công cụ tìm kiếm. Chỉ định nhãn tinh lọc mặc định cho display.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 Các 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 đã tắt hoặc nếu tìm kiếm hình ảnh đã được bật nhưng tìm kiếm trên web bị tắt.

kết quả tìm kiếm

searchresults-only

Tìm kiếm hình ảnh
enableImageSearch Boolean Chỉ có sẵn nếu 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.

Nếu giá trị là 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 .

kết quả tìm kiếm

searchresults-only

defaultToImageSearch Boolean Chỉ có sẵn nếu 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.

Nếu giá trị trả về 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. Kết quả trên web sẽ xuất hiện trong một thẻ riêng.

Bất kỳ
imageSearchLayout Chuỗi Chỉ có sẵn nếu 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.

Chỉ định bố cục của trang kết quả tìm kiếm hình ảnh. Giá trị có thể chấp nhận là classic, column hoặc popup.

kết quả tìm kiếm

searchresults-only

imageSearchResultSetSize Số nguyên, Chuỗi Chỉ có sẵn nếu 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.

Chỉ định kích thước tối đa của tập hợp kết quả tìm kiếm khi tìm kiếm hình ảnh. Ví dụ: large, small, filtered_cse, 10.

Bất kỳ
image_as_filetype Chuỗi Chỉ có sẵn nếu 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.

Giới hạn kết quả trong các tệp thuộc một tiện ích cụ thể.

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ỉ có sẵn nếu 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.

Lọc kết quả tìm kiếm bằng cách sử dụng hàm logic OR.

Ví dụ về cách sử dụng nếu bạn muốn kết quả tìm kiếm có "term1" hoặc "term2":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

Bất kỳ

image_as_rights Chuỗi Chỉ có sẵn nếu 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.

Bộ lọc dựa trên giấy phép.

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 các kiểu kết hợp thông thường.

Bất kỳ

image_as_sitesearch Chuỗi Chỉ có sẵn nếu 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.

Hạn chế kết quả ở các trang từ một trang web cụ thể.

Ví dụ về cách sử dụng: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

Bất kỳ

image_colortype Chuỗi Chỉ có sẵn nếu 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.

Hạn chế tìm kiếm ở hình ảnh đen và trắng (đơn sắc), 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ỉ có sẵn nếu 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.

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ỉ có sẵn nếu 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.

Hạn chế tìm kiếm trong những hình ảnh có màu chủ đạo cụ thể. Sau đây là các 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ỉ có sẵn nếu 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.

Lọc tự động kết quả tìm kiếm.

Các giá trị được hỗ trợ: 0/1

Ví dụ về cách sử dụng: <div class="gcse-search" data-image_filter="0"></div>

Bất kỳ

image_gl Chuỗi Chỉ có sẵn nếu 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. Cải thiện kết quả tìm kiếm có quốc gia xuất xứ khớp với giá trị thông số.

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

Bất kỳ

image_size Chuỗi Chỉ có sẵn nếu 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.

Trả về hình ảnh có kích thướ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ỉ có sẵn nếu 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.

Sắp xếp kết quả bằng cách sử dụng 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 một chuỗi trống (image_sort_by="").

Ví dụ về cách sử dụng: <div class="gcse-search" data-image_sort_by="date"></div>

Bất kỳ

image_type Chuỗi Chỉ có sẵn nếu 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.

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 (Bản 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 dùng nếu 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

searchresults-only

webSearchQueryAddition Chuỗi Đã thêm cụm từ bổ sung vào cụm từ tìm kiếm bằng cách sử dụng toán tử logic OR.

Ví dụ về cách sử dụng: <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ả tìm kiếm hình ảnh và tìm kiếm trên web. Tuỳ chọn mặc định phụ thuộc vào bố cục và liệu Công cụ tìm kiếm có thể lập trình được định cấu hình để tìm kiếm trên toàn bộ web hay chỉ được chỉ định của bạn. Các giá trị được chấp nhận bao gồm:
  • Số nguyên từ 1 đến 20
  • small: yêu cầu một tập hợp các kết quả nhỏ, thường là 4 kết quả trên mỗi trang.
  • large: yêu cầu 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 cho một tối đa 10 trang hoặc 100 kết quả.
Bất kỳ
webSearchSafesearch Chuỗi Chỉ định xem Tính năng SafeSearch đã cho phép các kết quả tìm kiếm trên web. Các giá trị được chấp nhận là offactive. Bất kỳ
as_filetype Chuỗi Giới hạn kết quả trong các tệp thuộc một tiện ích cụ thể. Bạn có thể tìm thấy 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 cách sử dụng hàm logic OR.

Ví dụ về cách sử dụng nếu bạn muốn kết quả tìm kiếm có "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 giấy phép.

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 kiểu kết hợp thông thường.

Bất kỳ

as_sitesearch Chuỗi Hạn chế kết quả ở các trang từ một trang web cụ thể.

Ví dụ về cách sử dụng: <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ợ

Ví dụ về cách sử dụng: <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.

Các giá trị được hỗ trợ: 0/1

Ví dụ về cách sử dụng: <div class="gcse-search" data-filter="0"></div>

Bất kỳ
gl Chuỗi Cải thiện kết quả tìm kiếm có quốc gia xuất xứ khớp với giá trị thông số.

Thuộc tính này sẽ chỉ hoạt động khi dùng chế độ cài đặt language value.

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

Ví dụ về cách sử dụng: <div class="gcse-search" data-gl="fr"></div>

Bất kỳ
lr Chuỗi Hạn chế kết quả tìm kiếm trong các tài liệu được viết bằng một ngôn ngữ cụ thể.

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

Ví dụ về cách sử dụng: <div class="gcse-search" data-lr="lang_fr"></div>

Bất kỳ
sort_by Chuỗi Sắp xếp kết quả bằng cách sử dụng 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 tuỳ chọn được cung cấp trong phần cài đặt Sắp xếp kết quả của công cụ tìm kiếm có thể lập trình egnine.

Để sắp xếp theo mức độ liên quan, hãy sử dụng một chuỗi trống (sort_by="").

Ví dụ về cách sử dụng: <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 cho đường liên kết. Mặc định: _blank.

kết quả tìm kiếm

searchresults-only

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 cụm từ tìm kiếm. Chuỗi kết quả mặc định có thể được dùng để hiển thị một chuỗi đã bản địa hoá trong tất cả ngôn ngữ được hỗ trợ, trong khi ngôn ngữ tuỳ chỉnh thì không.

kết quả tìm kiếm

searchresults-only

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. Chiến lược phát hành đĩa đơn tuỳ thuộc vào bố cục và việc công cụ có được định cấu hình để tìm kiếm hay không toàn bộ web hay chỉ những trang web được chỉ định. Bất kỳ
safeSearch Chuỗi Chỉ định nếu Tìm kiếm an toàn được bật cho cả tìm kiếm trên web và tìm kiếm hình ảnh. Các giá trị được chấp nhận là offactive. Bất kỳ

Lệnh gọi lại

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

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 cookie này được đăng ký với JavaScript Phần tử tìm kiếm thông qua __gcse toàn cầu . Đăng ký gọi lại 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 tạo

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ị tìm kiếm trong DOM. Nếu parsetags được đặt thành explicit trong __gcse, JavaScript Phần tử tìm kiếm kết xuất Phần tử tìm kiếm cho lệnh gọi lại khởi chạy (như thể hiện trong phần Đăng ký lệnh gọi lại). Tính năng này có thể dùng để chọn các phần tử cần kết xuất hoặc trì hoãn các phần tử kết xuất cho đến khi chúng được cần thiết. Tệp này cũng có thể ghi đè các thuộc tính của các phần tử; Ví dụ: tính năng này 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 để đặt mặc định là web tìm kiếm vào một hộp tìm kiếm hình ảnh hoặc nêu rõ rằng những cụm từ tìm kiếm đượ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ỉ dành cho 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 parsetags của __gcse.

  • Nếu giá trị của phần tử này là onload, thì Phần tử tìm kiếm JavaScript 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 chạy là vẫn được gọi nhưng không chịu trách nhiệm hiển thị các Phần tử tìm kiếm.
  • Nếu giá trị của mã này là explicit, thì JavaScript của Phần tử tìm kiếm không hiển thị Phần tử tìm kiếm. Lệnh gọi lại có thể hiển thị chúng một cách có chọn lọc bằng cách sử dụng render(), hoặc hiển thị tất cả Phần tử tìm kiếm bằng 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, sử dụng thẻ phân tích cú pháp explicit và lệnh gọi lại khởi chạy:

Ví dụ về lệnh gọi lại khởi tạo

Chúng ta cần thêm <div> có giá trị mã nhận dạng nơi chúng tôi muốn mã Phần tử tìm kiếm:

    <div id="test"></div>
Thêm JavaScript này sau <div>. Xin lưu ý rằng tham chiếu test, id chúng tôi đã sử dụng để xác định
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
};
<div>

Hãy đưa HTML này vào để bắt đầu tải Phần tử tìm kiếm. Thay thế giá trị cx trong Mệnh đề src với cx của riêng bạn.

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

Lệnh gọi lại tìm kiếm

JavaScript Phần tử tìm kiếm hỗ trợ 6 lệnh gọi lại hoạt động trong quy trình kiểm soát hoạt động tìm kiếm. Lệnh gọi lại tìm kiếm 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 trùng khớ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ả được 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,lệnh gọi lại tìm kiếm được định cấu hình bằng các mục nhập trong đối tượng __gcse. Điều này xảy ra dưới dạng Phần tử tìm kiếm JavaScript bắt đầu. 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 được truyền gName cho Phần tử tìm kiếm làm đối số. gname rất hữu ích khi một trang chứa nhiều cụm từ tìm kiếm. Tìm kiếm các giá trị gname của phần tử bằng thuộc tính data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

Nếu HTML không xác định tên, JavaScript của Phần tử tìm kiếm sẽ tạo một giá trị vẫn nhất quán cho đến khi HTML được sửa đổi.

Lệnh gọi lại bắt đầu tìm kiếm hình ảnh/trên web

Các lệnh gọi lại bắt đầu tìm kiếm được gọi ngay trước khi yêu cầu JavaScript Phần tử tìm kiếm kết quả tìm kiếm từ máy chủ của trang web đó. Ví dụ về trường hợp sử dụng: sử dụng giờ địa phương trong ngày để 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ể sửa đổi bằng thao tác tìm kiếm JavaScript phần tử).

Lệnh gọi lại trả về giá trị sẽ được dùng làm truy vấn cho lượt tìm kiếm này. Nếu nó 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ử dụng truy vấn chưa được sửa đổi.

Ngoài ra, bạn có thể đặt hàm callback trong đố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ề lệnh gọi lại bắt đầu tìm kiếm

Ví dụ về tìm kiếm bắt đầu gọi lại trong Ví dụ về lệnh gọi lại bắt đầu tìm kiếm sẽ thêm morning hoặc afternoon cho truy vấn tùy thuộc vào thời gian trong ngày.

Ví dụ về lệnh gọi lại bắt đầu tìm kiếm
    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 bằng hình ảnh/trên web

Những 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 kết xuất quảng cáo và kết quả. Một ví dụ về trường hợp sử dụng là lệnh gọi lại hiển thị chương trình khuyến mãi và kết quả theo kiểu không thể chỉ định bằng 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 các đối tượng trùng khớp chương trình khuyến mãi cho truy vấn của người dùng. Xem định nghĩa về đố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 mà Phần tử tìm kiếm thường sẽ quảng cáo địa điểm và kết quả tìm kiếm. Thông thường, JavaScript của Phần tử tìm kiếm sẽ xử lý điền div này, nhưng lệnh gọi lại này có thể chọn dừng hiển thị kết quả tự động và dùng div này để kết xuất chính các kết quả.

Nếu lệnh gọi lại này trả về giá trị true, thì JavaScript của Phần tử tìm kiếm sẽ bỏ qua chân trang.

Lệnh gọi lại kết quả mẫu đã sẵn sàng

Ví dụ về lệnh gọi lại resultsReady trong Lệnh gọi lại sẵn sàng cho kết quả mẫu sẽ ghi đè bản trình bày mặc định chương trình khuyến mãi và kết quả bằng phương thức thay thế rất đơn giản.

Ví dụ về lệnh gọi lại kết quả đã sẵn sàng
    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>

Cũng giống như lệnh gọi lại bắt đầu tìm kiếm, trên đây 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 hiển thị kết quả tìm kiếm hình ảnh/trên web

Những 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 kết xuất trang chân trang. Ví dụ về trường hợp sử dụng: lệnh gọi lại thêm nội dung kết quả mà cụm từ tìm kiếm không hiển thị, chẳng hạn như hộp kiểm lưu nội dung này hoặc thông tin không tự động hiển thị hoặc lệnh gọi lại thêm nút để biết thêm thông tin.

Nếu một lệnh gọi lại được hiển thị kết quả cần thông tin có trong promosresults của lệnh gọi lại đã sẵn sàng cho kết quả, phương thức này có thể truyền giá trị đó giữa các tham số đó 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 hiển thị kết quả

Ví dụ về lệnh gọi lại resultsRendered trong Ví dụ về lệnh gọi lại hiển thị kết quả sẽ thêm một Keep giả hộp kiểm vào mỗi quảng cáo 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ả, mã có thể chuyể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ị điểm xếp hạng từ richSnippet từ lệnh gọi lại đã sẵn sàng cho kết quả đến kết quả được hiển thị .

Ví dụ về lệnh gọi lại kết quả đã sẵn sàng hợp tác với lệnh gọi lại 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 cách sử dụng mã như thế này 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>

Ví dụ khác về lệnh gọi lại

Bạn có thể xem thêm ví dụ 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à khuyến mãi

Sử dụng ký hiệu JSDoc, đây là các thuộc tính của đối tượng khuyến mãikết quả. Ở đây, chúng tôi liệt kê tất cả các thuộc tính có thể xuất hiện. 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 là một mảng . Giá trị của các phần tử trong mảng này được kiểm soát bởi dữ liệu có cấu trúc tìm thấy trên trang web cho từng kết quả tìm kiếm. Ví dụ: trang web đánh giá có thể bao gồm dữ liệu có cấu trúc thêm mục nhập mảng này vào richSnippet:

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

Programmable Search Element Control API (Phiên bản 2)

Đối tượng google.search.cse.element xuất bản những nội dung sau hàm tĩnh:

Chức năng Mô tả
.render(componentConfig, opt_componentConfig) Hiển thị một phần tử tìm kiếm.

Tham số

Tên Mô tả
componentConfig Cấu hình cho một thành phần Phần tử tìm kiếm có thể lập trình. Chỉ định những yếu tố 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ẽ được hiển thị.
  • tag (chuỗi): Loại thành phần sẽ được kết xuất. (Khi bạn cung cấp opt_componentConfig, 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à các kết quả tìm kiếm, được hiển thị cùng nhau
    • searchbox: Một 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ẽ kết hợp với một khối kết quả tìm kiếm do opt_componentConfig chỉ định theo bố cục 2 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ạ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 trong TWO_COLUMN để cung cấp thành phần searchresults. Chỉ định những yếu tố sau:
  • div (chuỗi): id của <div> hoặc phần tử div mà trong đó phần tử sẽ được kết xuất.
  • tag (chuỗi): Loại thành phần sẽ được kết xuất. Thời gian opt_componentConfig đã được cung cấp, giá trị của 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 một gname cho thành phần. Nếu được cung cấp, mã 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ạng khoá:giá trị ghép nối. 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.

Tham số

Tên Mô tả
opt_container Vùng chứa chứa các thành phần Phần tử tìm kiếm sẽ hiển thị. Nêu rõ Mã của vùng chứa (chuỗi) hoặc chính phần tử đó. Nếu bị bỏ qua, tất cả thành phần Phần tử tìm kiếm có thể lập trình trong Thẻ body 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 – hàm(chuỗi): Thực thi truy vấn có lập trình.
  • prefillQuery – function(string): Điền sẵn một truy vấn vào hộp tìm kiếm mà không thực thi truy vấn.
  • getInputQuery – function(): Lấy giá trị hiện tại hiển thị trong đầu vào .
  • clearAllResults - function(): Xoá chế độ điều khiển bằng cách ẩn mọi nội dung 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ề một bản đồ chứa tất cả đối tượng phần tử được tạo thành công, được khoá bởi gname.