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 web và ứng dụng web khác bằng cách sử dụ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ủ Công cụ tìm kiếm có thể lập trình lưu trữ, cùng với mọi chế độ tuỳ chỉnh mà 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 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 hàm và thuộc tính dành riêng cho Programmable Search Engine Control API.
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ọ.
Các 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 một 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: một 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 thông tin đầu vào của người dùng theo một trong những cách sau:
- Cụm từ tìm kiếm được nhập vào trường nhập văn bản
- Một 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 những cách sau:
- Một chuỗi truy vấn được nhúng trong URL
- Thực thi có lập trình
Sau đây là các loại phần tử Tìm kiếm có thể lập trình:
| Loại phần tử | (Các) 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 xuất hiện trong cùng một <div>. |
| hai cột | <div class="gcse-searchbox"> và <div class="gcse-searchresults"> |
Bố cục hai cột với kết quả tìm kiếm ở một bên và hộp tìm kiếm ở bên còn lại. Nếu dự định chèn nhiều phần tử ở chế độ hai cột vào 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ỉ có 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 bao nhiêu Phần tử tìm kiếm hợp lệ tuỳ ý 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>
Tạo nhiều lựa chọn bố cục bằng cách sử dụng các 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ó 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 tạo các lựa chọn bố cục bằng cách sử dụng các Phần tử tìm kiếm có thể lập trình. Để xem bản minh hoạ về một trong các lựa chọn này, hãy nhấp vào đường liên kết.
| Phương thức | (Các) thành phần |
|---|---|
| Toàn chiều rộng | <div class="gcse-search"> |
| Nhỏ 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 lựa chọn bố cục.
Tuỳ chỉnh các phần tử của công cụ 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 chuyển đến 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 đã tạo trong bảng điều khiển Công cụ tìm kiếm có thể lập trình. Nhờ đó, bạn có thể tạo trải nghiệm tìm kiếm dành riêng cho trang.
Ví dụ: mã sau đây 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-.
Bạn bắt buộc phải có tiền tố này 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 đã sử dụng bảng điều khiển 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 những tính năng đó. Mọi chế độ tuỳ chỉnh mà bạn chỉ định bằng các thuộc tính này sẽ ghi đè các chế độ cài đặt trong bảng điều khiển. Ví dụ sau đây tạo một Phần tử tìm kiếm gồm 2 cột với các tính năng sau:
- Đã bật chế độ quản lý nhật ký
- Số lượng kết quả tự động hoàn thành tối đa được đặt thành 5
- Tiêu chí tinh chỉnh 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 được liên kết theo tên hoặc để ghép nối 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, 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 đầu tiên chưa được đặt tên có gname "searchbox-only0", searchbox-only 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 storesearch gname để liên kết một thành phần searchbox với một 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 có nhiều thành phần có cùng |
Bất kỳ |
autoSearchOnLoad |
Boolean | Chỉ định xem có thực hiện tìm kiếm theo 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 phải có một chuỗi truy vấn trong URL để thực hiện tính năng tìm kiếm tự động. Mặc định: true. |
Bất kỳ |
enableHistory |
Boolean | Nếu true, cho phép quản lý nhật ký cho các nút Quay lại và Chuyển tiếp của trình duyệt. Xem bản minh hoạ. |
hộp tìm kiếm chỉ có 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. Tham số này sẽ được nhúng trong URL (ví dụ: http://www.example.com?q=lady+gaga). Xin lưu ý rằng chỉ định tên tham số truy vấn không kích hoạt tính năng tự động tìm kiếm khi tải. Bạn phải có một chuỗi truy vấn trong URL để thực hiện tính năng tìm kiếm tự động. |
Bất kỳ |
resultsUrl |
URL | URL của trang kết quả. (Mặc định là trang do Google lưu trữ). | chỉ có 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ỉ có hộp tìm kiếm |
ivt |
Boolean |
Tham số này cho phép bạn cung cấp một giá trị boolean để thông báo cho Google 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ệ và phương pháp lưu trữ cục bộ trên cả lưu lượng truy cập có sự đồng ý và lưu lượng truy cập không có sự đồng ý.
Mặc định: Ví dụ về cách sử dụng: |
searchresults 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 trên thiết bị di động hay không.
Mặc định: Ví dụ về cách sử dụng: |
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 cho phép sử dụng tính năng tự động hoàn thành. |
Bất kỳ |
autoCompleteMaxCompletions |
Số nguyên | Số lượng kết quả tự động hoàn thành tối đa cần hiển thị. | hộp tìm kiếm chỉ có 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ỉ có 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 bật. Ngôn ngữ được hỗ trợ. | hộp tìm kiếm chỉ có hộp tìm kiếm |
| Tinh chỉnh | |||
defaultToRefinement |
Chuỗi | Chỉ có sẵn nếu bạn đã tạo các tiêu chí 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 chỉnh mặc định để hiển thị.Lưu ý: Bố cục do Google lưu trữ không hỗ trợ thuộc tính này. | Bất kỳ |
refinementStyle |
Chuỗi | Các giá trị có thể chấp nhận là tab (mặc định) và link.
link chỉ được hỗ trợ nếu bạn tắt tính năng tìm kiếm hình ảnh hoặc nếu bạn bật tính năng tìm kiếm hình ảnh nhưng tắt tính năng tìm kiếm trên web. |
searchresults searchresults-only |
| Tìm kiếm bằng hình ảnh | |||
enableImageSearch |
Boolean | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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 |
searchresults searchresults-only |
defaultToImageSearch |
Boolean | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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 |
Bất kỳ |
imageSearchLayout |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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. Các giá trị được chấp nhận là |
searchresults searchresults-only |
imageSearchResultSetSize |
Số nguyên, Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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 tập kết quả tìm kiếm cho tính năng tìm kiếm hình ảnh.
Ví dụ: |
Bất kỳ |
image_as_filetype |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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 tệp có đuôi được chỉ định. Các tiện ích được hỗ trợ là | Bất kỳ |
image_as_oq |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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" (hoặc). Ví dụ về cách sử dụng nếu bạn muốn kết quả tìm kiếm bao gồm "term1" hoặc "term2": | Bất kỳ |
image_as_rights |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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à | Bất kỳ |
image_as_sitesearch |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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ỉ hiển thị kết quả là các trang trên một trang web cụ thể. Ví dụ về cách sử dụng: | Bất kỳ |
image_colortype |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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ả tìm kiếm ở hình ảnh đen trắng (đơn sắc), thang màu xám hoặc hình ảnh có màu. Các giá trị được hỗ trợ là | Bất kỳ |
image_cr |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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 đối với tài liệu có nguồn gốc từ một quốc gia cụ thể. | Bất kỳ |
image_dominantcolor |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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ột màu chủ đạo cụ thể.
Các giá trị được hỗ trợ là | Bất kỳ |
image_filter |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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.
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: | Bất kỳ |
image_gl |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng tìm kiếm bằng 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. Tăng kết quả tìm kiếm có quốc gia xuất xứ khớp với giá trị tham số. | Bất kỳ |
image_size |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng hình ảnh trong bảng điều khiển của Công cụ tìm kiếm có thể lập trình.
Trả về hình ảnh có kích thước được chỉ định, trong đó kích thước có thể là một trong các kích thước sau: | Bất kỳ |
image_sort_by |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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ả 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: | Bất kỳ |
image_type |
Chuỗi | Chỉ có sẵn nếu bạn đã bật tính năng
tìm kiếm bằng 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 đối với hình ảnh thuộc một loại cụ thể.
Các giá trị được hỗ trợ là | Bất kỳ |
| Tìm kiếm trên web | |||
disableWebSearch |
Boolean | Nếu true, hãy tắt tính năng tìm kiếm trên web. Thường chỉ được dùng nếu bạn đã bật
tính năng tìm kiếm bằng 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. |
searchresults searchresults-only |
webSearchQueryAddition |
Chuỗi | Các từ khoá bổ sung được thêm vào cụm từ tìm kiếm bằng toán tử logic OR.
Ví dụ về cách sử dụng: |
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. Giá trị mặc định phụ thuộc vào bố cục và việc 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ỉ trên các trang web được chỉ định. Các giá trị được chấp nhận bao gồm:
|
Bất kỳ |
webSearchSafesearch |
Chuỗi |
Chỉ định xem có bật SafeSearch cho kết quả tìm kiếm trên web hay không. Giá trị được chấp nhận là off và active.
|
Bất kỳ |
as_filetype |
Chuỗi | Hạn chế kết quả đối với các tệp có đuôi được 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" (hoặc).
Ví dụ về cách sử dụng nếu bạn muốn kết quả tìm kiếm bao gồm "term1" hoặc "term2": |
Bất kỳ |
as_rights |
Chuỗi | Bộ lọc dựa trên việc cấp phép.
Các giá trị được hỗ trợ là Hãy xem https://wiki.creativecommons.org/wiki/CC_Search_integration để biết các tổ hợp thường gặp. | Bất kỳ |
as_sitesearch |
Chuỗi | Chỉ hiển thị kết quả là các trang trên một trang web cụ thể.
Ví dụ về cách sử dụng: |
Bất kỳ |
cr |
Chuỗi | Hạn chế kết quả tìm kiếm đối với tài liệu có nguồn gốc từ một quốc gia cụ thể.
Ví dụ về cách sử dụng: |
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: |
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ố.
Chế độ này chỉ hoạt động khi kết hợp với chế độ cài đặt giá trị ngôn ngữ. Ví dụ về cách sử dụng: |
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ể.
Ví dụ về cách sử dụng: |
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 lựa chọn được cung cấp trong chế độ 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.
Để 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: |
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. |
searchresults searchresults-only |
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ể được dùng để hiển thị một chuỗi đã bản địa hoá bằng tất cả các ngôn ngữ được hỗ trợ, trong khi chuỗi tuỳ chỉnh thì không. | searchresults 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. Giá trị mặc định phụ thuộc vào bố cục và việc công 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ụ thể. |
Bất kỳ |
safeSearch |
Chuỗi | Chỉ định xem
Tìm kiếm an toàn có được bật cho cả 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à off và active. |
Bất kỳ |
Lệnh gọi lại
Các lệnh gọi lại hỗ trợ việc kiểm soát chi tiết quá trình khởi tạo phần tử tìm kiếm và quy trình tìm kiếm.
Các đối tượng này được đăng ký bằng Search Element JavaScript thông qua đối tượng __gcse toàn cục. Register Callbacks minh hoạ việc đăng ký tất cả các lệnh gọi lại được hỗ trợ.
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 tạo được gọi trước khi JavaScript của Phần tử tìm kiếm hiển thị các phần tử tìm kiếm trong DOM. Nếu parsetags được đặt thành explicit trong __gcse, thì JavaScript của Phần tử tìm kiếm sẽ để lại việc kết xuất Phần tử tìm kiếm cho lệnh gọi lại khởi tạo (như minh hoạ trong phần Đăng ký lệnh gọi lại).
Bạn có thể dùng cách 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. Bạn cũng có thể ghi đè các thuộc tính của phần tử; ví dụ: bạ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 thuộc tính HTML để mặc định tìm kiếm trên web thành một hộp tìm kiếm hình ảnh, hoặc chỉ định rằng các cụm từ tìm kiếm được gửi thông qua biểu mẫu Công cụ tìm kiếm có thể lập trình sẽ được thực thi trong một phần tử chỉ có kết quả tìm kiếm.
Xem bản minh hoạ.
Vai trò của lệnh gọi lại khởi chạy được kiểm soát bằng giá trị của thuộc tính parsetags của __gcse.
- Nếu giá trị là
onload, thì JavaScript của Phần tử tìm kiếm sẽ tự động kết xuất tất cả Phần tử tìm kiếm trên trang. Lệnh gọi lại khởi tạo vẫn được gọi, nhưng không chịu trách nhiệm kết xuất các Phần tử tìm kiếm. - Nếu giá trị là
explicit, thì JavaScript của Phần tử tìm kiếm sẽ không kết xuất Phần tử tìm kiếm. Lệnh gọi lại có thể kết xuất các phần tử này một cách chọn lọc bằng hàmrender()hoặc kết xuất tất cả Phần tử tìm kiếm bằng hàmgo()
Đoạn mã sau đây minh hoạ cách kết xuất một hộp tìm kiếm, cùng với kết quả tìm kiếm, trong một div, bằng cách sử dụng parsetag explicit và lệnh gọi lại khởi chạy:
Chúng ta cần thêm một <div> có giá trị nhận dạng ở vị trí mà chúng ta muốn đặt mã Phần tử tìm kiếm:
<div id="test"></div><div>. Xin lưu ý rằng nó 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
};
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 luồng điều khiển tìm kiếm. Các lệnh gọi lại tìm kiếm xuất hiện theo cặp, một lệnh gọi lại tìm kiếm trên web và một lệnh gọi lại tìm kiếm hình ảnh phù hợp:
- Bắt đầu tìm kiếm
- Đối với tìm kiếm hình ảnh
- Đối với tìm kiếm trên web
- Đã có kết quả
- Đối với tìm kiếm hình ảnh
- Đối với tìm kiếm trên web
- Kết quả được hiển thị
- Đối với tìm kiếm hình ảnh
- Đối với 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 trong đối tượng __gcse. Điều này xảy ra khi JavaScript của Phần tử tìm kiếm bắt đầu. Hệ thống sẽ bỏ qua các nội dung sửa đổi đối với __gcse sau khi khởi động.
Mỗi lệnh gọi lại này được truyền gName cho Phần tử tìm kiếm dưới dạng một đối số.
gname rất hữu ích khi một trang chứa nhiều nội dung tìm kiếm. Đặt cho phần tử tìm kiếm giá trị gname bằ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 ra một giá trị 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 phần tử đó. Ví dụ về trường hợp sử dụng là sử dụng thời gian trong ngày theo giờ đị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ể được sửa đổi bằng JavaScript của phần tử tìm kiếm).
Lệnh gọi lại sẽ trả về giá trị cần 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 được sửa đổi.
Ngoài ra, bạn có thể đặt hàm gọi lại trong đối tượng __gcse hoặc thêm hàm gọi lại vào đối tượng một cách linh độ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ề lệnh gọi lại bắt đầu tìm kiếm trong Ví dụ về lệnh gọi lại bắt đầu tìm kiếm sẽ thêm morning hoặc afternoon vào truy vấn, tuỳ thuộc vào thời gian trong ngày.
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/trên 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 ví dụ là một lệnh gọi lại hiển thị chương trình khuyến mãi và kết quả theo một kiểu mà bạn 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- cụm từ tìm kiếm đã tạo ra những 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 gồm các đối tượng kết quả. Xem định nghĩa đối tượng kết quả.
div- một thẻ div HTML được đặt trong DOM, nơi Phần tử tìm kiếm thường đặt 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 vào div này, nhưng lệnh gọi lại này có thể chọn dừng quá trình kết xuất kết quả tự động và sử dụng
divnày để tự kết xuất 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 công việc ở chân trang.
Ví dụ về lệnh gọi lại Đã có kết quả
Lệnh gọi lại resultsReady trong ví dụ Example Results Ready Callback 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ả bằng một phương thức thay thế rất đơn giản.
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 trong đối tượng __gcse.
Kết quả tìm kiếm hình ảnh/web – Lệnh gọi lại được hiển thị
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. Các trường hợp sử dụng ví dụ bao gồm một lệnh gọi lại thêm nội dung kết quả mà phần tử tìm kiếm không hiển thị, chẳng hạn như hộp đánh dấu lưu nội dung này hoặc thông tin không được tự động hiển thị, hoặc một lệnh gọi lại thêm các nút để biết thêm thông tin.
Nếu lệnh gọi lại kết quả được hiển thị cần thông tin có trong các tham số promos và results của lệnh gọi lại kết quả đã sẵn sàng, thì lệnh gọi lại này có thể truyền thông tin đó 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 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 Kết quả được hiển thị
Lệnh gọi lại resultsRendered ví dụ trong Lệnh gọi lại kết quả được kết xuất ví dụ sẽ thêm một hộp đánh dấu Giữ giả vào mỗi chương trình khuyến mãi và 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 kết quả được hiển thị cần thông tin đã được truyền đến lệnh gọi lại kết quả đã sẵn sàng, thì lệnh gọi lại này có thể truyền dữ liệu đó giữa các lệnh gọi lại. Ví dụ sau đây minh hoạ một trong nhiều cách để truyề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ị.
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};
};__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ụ về lệnh gọi lại Kết quả được kết xuất: Mở các loại tệp cụ thể trong thẻ/cửa sổ mới
Ví dụ về lệnh gọi lại sau đây có thể sửa đổi các đường liên kết đến kết quả tìm kiếm sau khi các đường liên kết này được hiển thị để mở một tệp cụ thể trong thẻ/trang mới thay vì cửa sổ hiện tại (ví dụ: PDF, Excel hoặc Word). Điều này giúp cải thiện trải nghiệm duyệt web khi người dùng không muốn mở một tệp trên cùng một cửa sổ và rời khỏi trang kết quả.
Ví dụ về lệnh gọi lại này xác định các đường liên kết đến tệp PDF trong kết quả tìm kiếm và đặt thuộc tính target="_blank" trên các đường liên kết đến tệp PDF để các đường liên kết đó mở trong một thẻ mới. MutationObserver được dùng để xử lý linh động các kết quả mới nếu trang cập nhật. Lưu ý: Bạn có thể thay thế .pdf trong handleSearchResults bằng bất kỳ loại tệp nào khác theo yêu cầu của mình.
Ví dụ về lệnh gọi lại này không hoạt động trên bố cục Lớp phủ và bố cục do Google lưu trữ.
function handleSearchResults() {
const links = document.querySelectorAll('.gsc-results .gs-title');
links.forEach(link => {
const url = link.href;
if (url?.toLowerCase().endsWith('.pdf')) {
link.setAttribute('target', '_blank');
}
});
}
const myWebResultsRenderedCallback = () => {
// Call handleSearchResults when results are rendered
handleSearchResults();
// Set up a MutationObserver to handle subsequent updates to the results
const observer = new MutationObserver(handleSearchResults);
const searchResultsContainer = document.querySelector('.gsc-results');
if (searchResultsContainer) {
observer.observe(searchResultsContainer, {
childList: true,
subtree: true
});
} else {
console.log('No Results.');
}
};
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>Các ví dụ khác về lệnh gọi lại
Bạn có thể xem thêm các 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.
Thuộc tính khuyến mãi và kết quả
Khi sử dụng ký hiệu JSDoc, đây là các thuộc tính của đối tượng promotion và result. Tại đây, chúng tôi liệt kê tất cả các thuộc tính có thể xuất hiện. Sự xuất hiện của nhiều thuộc tính 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.
{
content: string,
image: {
height: number,
url: string,
width: number,
},
title: string,
url: string,
visibleUrl: string,
}{
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 results có kiểu lỏng lẻo của một mảng đối tượng. Các giá trị của mục trong mảng này do 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 kiểm soát. Ví dụ: một trang web đánh giá có thể bao gồm dữ liệu có cấu trúc giúp thêm mục nhập mảng này vào richSnippet:
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},Programmable Search Element Control API (V2)
Đối tượng google.search.cse.element sẽ xuất bản các hàm tĩnh sau:
| Chức năng | Mô tả | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
Kết xuất một Phần tử tìm kiếm.
Tham số
|
||||||
.go(opt_container) |
Hiển thị tất cả các thẻ/lớp Phần tử tìm kiếm trong vùng chứa được chỉ định.
Tham số
|
||||||
.getElement(gname) |
Lấy đối tượng phần tử theo gname. Nếu không tìm thấy, hãy trả về giá trị rỗng.
Đối tượng
Đoạn mã sau 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ề một bản đồ của tất cả các đối tượng phần tử được tạo thành công, được khoá bằng gname. |