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) vào các trang trên trang web của bạn và các ứng dụng web khác bằng mã đánh dấu HTML. Các phần tử 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 chế độ tuỳ chỉnh 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ột mô hình cơ bản để thêm các phần tử 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 phần 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 hàm và thuộc tính dành riêng cho API Có thể lập trình dành cho công cụ tìm kiếm.

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 được 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 trang của họ.

Phần tử tìm kiếm có thể lập trình

Bạn có thể 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, 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 người dùng nhập vào theo bất kỳ cách nào sau đây:

  • Truy vấn tìm kiếm đã 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 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ó các 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 Mô tả
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 <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 kia. Nếu có ý định chèn nhiều phần tử ở chế độ hai cột trong trang web của mình, bạn có thể sử dụng thuộc tính gname để ghép một 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ỉ cuộn xuống dưới <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. Đối với chế độ hai cột, bạn phải có tất cả các thành phần bắt buộc (hộp tìm kiếm và khối kết quả tìm kiếm).

Sau đâ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 các tuỳ chọn bố cục khác nhau bằng cách sử dụng Thành phần tìm kiếm có thể lập trình

Các tuỳ chọn bố cục sau có sẵn 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. Dưới đây là một số nguyên tắc chung về cách soạn các tuỳ chọn bố cục bằng cách sử dụng Thành phần 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.

Lựa chọn (Các) thành phần
Chiều rộng đầy đủ <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">
Lưu trữ trên Google <div class="gcse-searchbox-only">

Thông tin thêm về các 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 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ác cấu hình được tạo trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình. Đ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 sẽ tạo một hộp tìm kiếm để mở trang kết quả (http://www.example.com?search=lady+gaga) trong một 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 đã sử 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, 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ỳ tùy 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ài đặt được 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 hai cột với các tính năng sau:

  • Đã bật tính năng quản lý nhật ký
  • Số lượng nội dung tự động hoàn thành hiển thị tối đa được đặt là 5
  • 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
Chung
gname Chuỗi (Không bắt buộc) Tên đối tượng của 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 một thành phần searchbox với một thành phần searchresults. Nếu bạn không cung cấp thuộc tính này, Công cụ tìm kiếm có thể lập trình sẽ tự động tạo gname, dựa trên thứ tự các thành phần trên trang web. Ví dụ: searchbox-only người chưa đặt tên đầu tiên có gname "searchbox-only0" và người thứ hai có gname "seachbox-only1", v.v. 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 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, 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 việc tìm kiếm theo cụm từ tìm kiếm được nhúng trong URL của trang đang tải hay không. Xin lưu ý rằng chuỗi truy vấn phải có trong URL để thực thi quá trình tìm kiếm tự động. Mặc định: true. Bất kỳ
enableHistory Boolean Nếu true, hãy bật tính năng quản lý nhật ký của các nút Quay lại và Tiến lên trên trình duyệt. 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. URL này sẽ được nhúng trong URL (ví dụ: http://www.example.com?q=lady+gaga). Xin lưu ý rằng việc chỉ định riêng 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 của cụm từ tìm kiếm phải có trong URL để thực thi quá trình 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 một cửa sổ mới hay không. Mặc định: false. chỉ hộp tìm kiếm
personalizedAds Boolean

Chỉ định việc người dùng có đồng ý cho phép nhà xuất bản chia sẻ thông tin cá nhân với Google cho mục đích cá nhân hoá quảng cáo hay không.

true Trả về những quảng cáo được nhắm mục tiêu theo cụm từ tìm kiếm và một số quảng cáo có thể được nhắm mục tiêu bằng cookie Google của người dùng. Nếu người dùng ở Liên minh Châu Âu, trước tiên người dùng phải đồng ý cho phép trang web của bạn chia sẻ thông tin cá nhân với Google cho mục đích quảng cáo được cá nhân hóa.

false Chỉ trả về những quảng cáo được nhắm mục tiêu cụm từ tìm kiếm. Giá trị này sẽ không trả lại bất kỳ quảng cáo nào được nhắm mục tiêu bằng cookie Google của người dùng. Nếu người dùng không cho phép trang web của bạn chia sẻ thông tin cá nhân với Google cho mục đích cá nhân hoá quảng cáo, thì bạn phải đặt giá trị này thành false.

Mặc định: true

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

THẺ

chỉ cuộn xuống dưới
mobileLayout Chuỗi

Chỉ định xem có nên 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 dành cho thiết bị di động cho các thiết bị di động.

disabled không sử dụng bố cục trên 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ỉ có sẵn 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 cụm từ tự động hoàn thành tối đa được 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 để 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 các ngôn ngữ được phân tách bằng dấu phẩy để bật tính năng tự động hoàn thành. Các ngôn ngữ được hỗ trợ.

hộp tìm kiếm

chỉ hộp tìm kiếm
Tinh chỉnh
defaultToRefinement Chuỗi Chỉ có sẵn nếu các nhãn tinh lọc đã được tạo 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 Được lưu trữ trên Google. 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 đang bật nhưng tính năng tìm kiếm trên web đang tắt.

THẺ

chỉ cuộn xuống dưới
Tìm kiếm hình ảnh
enableImageSearch Boolean Chỉ có sẵn 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.

Nếu true, hãy bật tính năng tìm kiếm hình ảnh. Kết quả hình ảnh sẽ hiển thị trên một thẻ riêng.

THẺ

chỉ cuộn xuống dưới
defaultToImageSearch Boolean Chỉ có sẵn 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.

Nếu 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 trên một thẻ riêng.

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

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.

THẺ

chỉ cuộn xuống dưới
imageSearchResultSetSize Số nguyên, Chuỗi Chỉ có sẵn 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.

Chỉ định kích thước tối đa của tập hợp kết quả tìm kiếm cho 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í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.

Hạn chế kết quả trong các tệp của 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í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.

Lọc kết quả tìm kiếm bằng toán tử logic "OR" (hoặc).

Ví dụ về cách sử dụng nếu bạn muốn các kết quả tìm kiếm bao gồm "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í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.

Các bộ lọc dựa trên quá trình cấp 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 điển hình.

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

Hạn chế kết quả trên các trang thuộc 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í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.

Hạn chế tìm kiếm đối với hình ảnh đen trắng (đơn sắc), thang màu xám hoặc màu. Giá trị được hỗ trợ là mono, gray, color.

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

Hạn chế kết quả tìm kiếm đối với 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í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.

Hạn chế tìm kiếm hình ảnh về màu chủ đạo cụ thể. Các giá trị được hỗ trợ là 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í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.

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

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í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. Tăng 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ỉ có sẵn 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.

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

Sắp xếp kết quả bằ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 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í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.

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 người), lineart (Bản vẽ đường kẻ), stock (Ảnh thương mại), photo (Ảnh chụp) 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 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.

THẺ

chỉ cuộn xuống dưới
webSearchQueryAddition Chuỗi Các cụm từ bổ sung đã được thêm vào cụm từ tìm kiếm bằng hàm 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ính năng tìm kiếm hình ảnh và tìm kiếm trên web. Chế độ mặc định tuỳ thuộc vào bố cục và liệu Công cụ tìm kiếm có thể lập trình có được định cấu hình để tìm kiếm trên toàn bộ web hay chỉ để xác định các trang web. Sau đây là các giá trị được chấp nhận:
  • Số nguyên từ 1-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 xem có bật tính năng Tìm kiếm an toàn cho kết quả tìm kiếm trên web hay không. Giá trị được chấp nhận là moderate, off và active. Bất kỳ
as_filetype Chuỗi Hạn chế kết quả trong các tệp của một tiện ích cụ thể. 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" (hoặc).

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

 Bất kỳ
as_rights Chuỗi Các bộ lọc dựa trên quá trình cấp 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.

Hãy truy cập vào https://wiki.creativeAdSense.org/wiki/CC_Search_ integration để tìm 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ả trên các trang thuộc 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 đối với 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 Tự động lọc kết quả tìm kiếm.

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 Tăng kết quả tìm kiếm có quốc gia xuất xứ khớp với giá trị tham số.

Lựa chọn này sẽ chỉ hoạt động cùng với chế độ cài đặt giá trị ngôn ngữ.

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 đối với tài liệu 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 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 chế độ cài đặt Sắp xếp kết quả của nội dung 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="").

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 liên kết. Mặc định: _blank.

THẺ

chỉ cuộn xuống dưới
noResultsString Chuỗi Chỉ định văn bản mặc định mà người dùng thấy 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ể dùng để hiển thị một chuỗi đã được bản địa hoá ở tất cả ngôn ngữ được hỗ trợ, còn chuỗi đã tuỳ chỉnh thì không.

THẺ

chỉ cuộn xuống dưới
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 tuỳ thuộc vào bố cục và liệu công cụ có được định cấu hình để tìm kiếm trên toàn bộ web hay chỉ trên những trang web được chỉ định. Bất kỳ
safeSearch Chuỗi Chỉ định xem chế độ Tìm kiếm an toàn có được bật cho cả chức năng tìm kiếm trên web và tìm kiếm hình ảnh hay không. Giá trị được chấp nhận là moderate, off và active. Bất kỳ

Callbacks

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

Lệnh gọi lại hỗ trợ kiểm soát chi tiết việc khởi chạy thành phần tìm kiếm và quy trình tìm kiếm. Chúng được đăng ký với JavaScript của phần tử tìm kiếm thông qua đối tượng __gcse toàn cục. Đăng ký lệnh 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 chạy

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 của Phần tử tìm kiếm sẽ để phần tử tìm kiếm kết xuất thành lệnh gọi lại khởi chạy (như hiển thị trong Đă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 việc kết xuất các phần tử cho đến khi cần đến. Nó cũng có thể ghi đè các thuộc tính của các phần tử; ví dụ: nó có thể chuyển một hộp tìm kiếm được định cấu hình thông qua Bảng điều khiển hoặc các thuộc tính HTML để mặc định là tìm kiếm web vào 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ông cụ tìm kiếm có thể lập trình sẽ được thực thi trong phần tử chỉ ClaimReview. Xem bản minh họa.

Vai trò của lệnh gọi lại khởi chạy chịu sự kiểm soát của 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 JavaScript của phần tử tìm kiếm sẽ tự động hiển thị tất cả các phần tử tìm kiếm trên trang. Lệnh gọi lại khởi chạy 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 phần tử này là explicit, thì JavaScript JavaScript của phần tử tìm kiếm sẽ không hiển thị các phần tử tìm kiếm. Lệnh gọi lại có thể kết xuất chúng 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ả các Phần tử tìm kiếm bằng hàm go()

Mã sau đây minh hoạ cách hiển thị một hộp tìm kiếm, cùng với kết quả tìm kiếm, trong một div, sử dụng thẻ phân tích cú pháp và lệnh gọi lại khởi chạy explicit:

Ví dụ về lệnh gọi lại khởi chạy

Chúng ta cần cung cấp một <div> kèm theo giá trị mã nhận dạng mà chúng ta muốn đưa vào mã phần tử Tìm kiếm: 

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

Thê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 của 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 đ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
    • Dành cho tìm kiếm trên web
  • Kết quả đã sẵn sàng
    • Để tìm kiếm hình ảnh
    • Dành cho tìm kiếm trên web
  • Kết quả hiển thị
    • Để tìm kiếm hình ảnh
    • Dành cho tìm kiếm trên web

Giống như lệnh gọi lại quá trình khởi chạy,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. Quá trình này xảy ra khi JavaScript của phần tử tìm kiếm bắt đầu. Nội dung sửa đổi thành __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 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. Gán giá trị gname cho phần tử tìm kiếm bằng thuộc tính data-gname:

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

Nếu HTML không xác định được tên, thì JavaScript của phần tử tìm kiếm JavaScript sẽ tạo ra một giá trị sẽ 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/web

Các lệnh gọi lại bắt đầu tìm kiếm sẽ đượ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ủ của mình. Ví dụ về trường hợp sử dụng: 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 cụm từ tìm kiếm. 

searchStartingCallback(gname, query)
gname
Chuỗi xác định của phần tử tìm kiếm
query
giá trị do người dùng nhập (có thể được sửa đổi bằng phần tử tìm kiếm JavaScript.)

Lệnh gọi lại sẽ trả về giá trị nên được dùng làm truy vấn cho cụm 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ề lệnh gọi lại bắt đầu tìm kiếm

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

Ví dụ về lệnh gọi lại 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 hỗ trợ 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ị kết quả được thăng hạng 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ị các chương trình khuyến mãi và kết quả theo kiểu không thể chỉ định với tùy chỉnh thông thường. 

resultsReadyCallback(gname, query, promos, results, div)
gname
Chuỗi xác định 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 loạt 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 loạt 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 các chương trình khuyến mãi 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ý việc điền sẵn div này, nhưng lệnh gọi lại này có thể chọn dừng tính nă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ẽ chuyển đến phần chân trang.

Ví dụ về lệnh gọi lại sẵn sàng cho kết quả

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

Ví dụ về lệnh gọi lại 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>

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

Lệnh gọi lại được hiển thị 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â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à phần tử tìm kiếm không xuất hiện, chẳng hạn như hộp đánh dấu lưu nội dung này hoặc thông tin không tự động kết xuất, hoặc lệnh gọi lại bổ sung nút để biết thêm thông tin.

Nếu một lệnh gọi lại được hiển thị cho kết quả cần thông tin nằm 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ì lệnh gọi lại có thể truyền giữa các thông số đó, như sau: 

callback(gname, query, promoElts, resultElts);
gname
Chuỗi xác định của phần tử tìm kiếm
query
chuỗi tìm kiếm.
promoElts
một mảng thành phần DOM chứa các 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ả

Lệnh gọi lại resultsRendered mẫu trong phần Gọi lại kết quả mẫu đã thêm hộp đánh dấu Keep giả mạo cho mỗi chương trình khuyến mãi và kết quả.

Ví dụ về lệnh gọi lại hiển thị kết quả 
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 truyền đến lệnh gọi lại sẵn sàng cho kết quả, thì lệnh gọi đó 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 được kết xuất.

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 Các ví dụ khác về lệnh gọi lại.

Kết quả được thăng hạng và Thuộc tính kết quả

Sử dụng ký hiệu JSDoc, đây là các thuộc tính của đối tượng khuyến mãi và kết quả. Ở đây, chúng tôi liệt kê tất cả các thuộc tính có thể có. Việc có nhiều cơ sở lưu trú sẽ 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 các đố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 trên trang web của mỗi 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 nhập 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 (V2)

Đối tượng google.search.cse.element phát hành các hàm tĩnh sau:

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

Thông số

Tên Mô tả
componentConfig Cấu hình của thành phần Phần tử tìm kiếm có thể lập trình. Xác định những thông tin sau:
  • div (chuỗi|Phần tử): id của <div> hoặc phần tử div mà phần tử Tìm kiếm có thể lập trình sẽ hiển thị.
  • tag (chuỗi): Loại thành phần sẽ được hiển thị. (Khi bạn cung cấp opt_componentConfig, giá trị của thuộc tính tag phải là searchbox.) Giá trị được phép là:
    • search: Hộp tìm kiếm và 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 một 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 một URL hoặc bằng quá trình thực thi có lập trình.
  • gname (chuỗi): (Không bắt buộc) Tên duy nhất cho thành phần này. Nếu bạn không cung cấp thuộc tính này, Công cụ tìm kiếm có thể lập trình sẽ tự động tạo 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ị. Các 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. Xác định những thông tin sau:
  • div (chuỗi): id của <div> hoặc phần tử div mà phần tử sẽ được hiển thị.
  • tag (chuỗi): Loại thành phần sẽ được 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 duy nhất cho thành phần này. Nếu bạn không cung cấp thuộc tính này, 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, thông số 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 khóa: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 Mô tả
opt_container Vùng chứa chứa các thành phần Phần tử tìm kiếm để kết xuất. 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ả thành phần Phần tử tìm kiếm có thể lập trình trong thẻ body của trang sẽ hiển thị.
.getElement(gname) Lấy đối tượng phần tử bằng 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 bạn không cung cấp thuộc tính này, 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 để hiển thị phần tử.
  • execute – function(string): Thực thi truy vấn có lập trình.
  • prefillQuery – function(string): Điền sẵn hộp tìm kiếm bằng một chuỗi truy vấn mà không cần thực thi truy vấn.
  • getInputQuery – function(): Lấy giá trị hiện tại trong hộp đầu vào.
  • clearAllResults – function(): Xoá tuỳ chọn điều khiển 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 "tin tức" 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ả các đối tượng phần tử đã tạo thành công, do gname tạo khoá.