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:

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.

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ợ

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

Lệnh gọi lại

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

  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:

    <div id="test"></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
};

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

    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.

    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;
    };

  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>

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 promos và results 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ả.

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);
    }
  };

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

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};
};

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ãi và kế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.

{
  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 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:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');