Tạo giao diện tìm kiếm bằng tiện ích tìm kiếm

Tiện ích tìm kiếm cung cấp giao diện tìm kiếm có thể tùy chỉnh cho các ứng dụng web. Tiện ích này chỉ yêu cầu một lượng nhỏ HTML và JavaScript để triển khai và bật các tính năng tìm kiếm phổ biến như các khía cạnh và tính năng phân trang. Bạn cũng có thể tuỳ chỉnh các phần của giao diện với CSS và JavaScript.

Nếu bạn cần sự linh hoạt hơn mức mà tiện ích cung cấp, hãy cân nhắc sử dụng API truy vấn. Để biết thông tin về cách tạo giao diện tìm kiếm bằng API truy vấn, hãy tham khảo bài viết Tạo giao diện tìm kiếm bằng API truy vấn.

Xây dựng giao diện tìm kiếm

Việc xây dựng giao diện tìm kiếm yêu cầu nhiều bước:

  1. Định cấu hình ứng dụng tìm kiếm
  2. Tạo một ID ứng dụng khách cho ứng dụng
  3. Thêm đánh dấu HTML cho hộp tìm kiếm và kết quả
  4. Tải tiện ích con trên trang
  5. Khởi chạy tiện ích

Định cấu hình ứng dụng tìm kiếm

Mỗi giao diện tìm kiếm phải có một ứng dụng tìm kiếm được xác định trong bảng điều khiển dành cho quản trị viên. Ứng dụng tìm kiếm cung cấp thêm thông tin cho truy vấn, chẳng hạn như các nguồn dữ liệu, khía cạnh và cài đặt chất lượng tìm kiếm.

Để tạo một ứng dụng tìm kiếm, hãy tham khảo bài viết Tạo trải nghiệm tìm kiếm tuỳ chỉnh.

Tạo một ID ứng dụng khách cho ứng dụng

Ngoài các bước trong bài viết Định cấu hình quyền truy cập vào API Google Cloud Search, bạn cũng phải tạo mã ứng dụng khách cho ứng dụng web.

Định cấu hình dự án

Khi bạn định cấu hình dự án:

  • Chọn loại ứng dụng khách Trình duyệt web
  • Cung cấp URI gốc của ứng dụng.
  • Ghi chú về mã ứng dụng khách đã được tạo. Bạn sẽ cần mã ứng dụng khách để hoàn tất các bước tiếp theo. Tiện ích ứng dụng không cần thiết đối với tiện ích.

Để biết thêm thông tin, hãy xem OAuth 2.0 cho ứng dụng web phía máy khách.

Thêm đánh dấu HTML

Tiện ích con này yêu cầu một lượng nhỏ HTML để hoạt động. Bạn phải cung cấp:

  • Phần tử input cho hộp tìm kiếm.
  • Một phần tử để cố định cửa sổ bật lên đề xuất.
  • Phần tử chứa kết quả tìm kiếm.
  • (Không bắt buộc) Cung cấp một phần tử để chứa các tuỳ chọn điều khiển thuộc tính.

Đoạn mã HTML sau đây cho biết HTML của một tiện ích tìm kiếm, trong đó các phần tử cần liên kết được xác định bằng thuộc tính id của chúng:

cung cấp/tiện ích/công khai/with_css/index.html
<div id="search_bar">
  <div id="suggestions_anchor">
    <input type="text" id="search_input" placeholder="Search for...">
  </div>
</div>
<div id="facet_results"></div>
<div id="search_results"></div>

Tải tiện ích con

Tiện ích được tải động thông qua tập lệnh trình tải. Để thêm trình tải, hãy sử dụng thẻ <script> như sau:

cung cấp/tiện ích/công khai/with_css/index.html
<!-- Google API loader -->
<script src="https://apis.google.com/js/api.js?mods=enable_cloud_search_widget&onload=onLoad" async defer></script>

Bạn phải cung cấp một lệnh gọi lại onload trong thẻ tập lệnh. Hàm được gọi khi trình tải sẵn sàng. Khi trình tải đã sẵn sàng, hãy tiếp tục tải tiện ích bằng cách gọi gapi.load() để tải ứng dụng khách API, mô-đun đăng nhập bằng Google và Cloud Search.

cung cấp/tiện ích/công khai/with_css/app.js
/**
* Load the cloud search widget & auth libraries. Runs after
* the initial gapi bootstrap library is ready.
*/
function onLoad() {
  gapi.load('client:auth2:cloudsearch-widget', initializeApp)
}

Hàm initializeApp() được gọi sau khi tất cả mô-đun được tải.

Khởi chạy tiện ích

Trước tiên, hãy khởi chạy thư viện ứng dụng bằng cách gọi gapi.client.init() hoặc gapi.auth2.init() với mã ứng dụng khách đã tạo và phạm vi https://www.googleapis.com/auth/cloud_search.query. Tiếp theo, hãy sử dụng các lớp gapi.cloudsearch.widget.resultscontainer.Builder và gapi.cloudsearch.widget.searchbox.Builder để định cấu hình tiện ích và liên kết tiện ích đó với các phần tử HTML.

Ví dụ sau đây minh họa cách khởi chạy tiện ích:

cung cấp/tiện ích/công khai/with_css/app.js
/**
 * Initialize the app after loading the Google API client &
 * Cloud Search widget.
 */
function initializeApp() {
  // Load client ID & search app.
  loadConfiguration().then(function() {
    // Set API version to v1.
    gapi.config.update('cloudsearch.config/apiVersion', 'v1');

    // Build the result container and bind to DOM elements.
    var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setSearchResultsContainerElement(document.getElementById('search_results'))
      .setFacetResultsContainerElement(document.getElementById('facet_results'))
      .build();

    // Build the search box and bind to DOM elements.
    var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setInput(document.getElementById('search_input'))
      .setAnchor(document.getElementById('suggestions_anchor'))
      .setResultsContainer(resultsContainer)
      .build();
  }).then(function() {
    // Init API/oauth client w/client ID.
    return gapi.auth2.init({
        'clientId': clientId,
        'scope': 'https://www.googleapis.com/auth/cloud_search.query'
    });
  });
}

Ví dụ trên đề cập đến hai biến cho cấu hình được xác định là:

cung cấp/tiện ích/công khai/with_css/app.js
/**
* Client ID from OAuth credentials.
*/
var clientId = "...apps.googleusercontent.com";

/**
* Full resource name of the search application, such as
* "searchapplications/<your-id>".
*/
var searchApplicationName = "searchapplications/...";

Tùy chỉnh trải nghiệm đăng nhập

Theo mặc định, tiện ích này sẽ nhắc người dùng đăng nhập và ủy quyền cho ứng dụng tại thời điểm họ bắt đầu nhập truy vấn. Bạn có thể sử dụng tính năng Đăng nhập bằng Google cho Trang web để mang lại trải nghiệm đăng nhập phù hợp hơn với người dùng.

Ủy quyền trực tiếp cho người dùng

Sử dụng tính năng Đăng nhập bằng Google để giám sát trạng thái đăng nhập của người dùng và người dùng đăng nhập hoặc đăng xuất khi cần. Ví dụ: ví dụ sau đây quan sát trạng thái isSignedIn để theo dõi các thay đổi về việc đăng nhập và sử dụng phương thức GoogleAuth.signIn() để bắt đầu đăng nhập từ một lượt nhấp vào nút:

cung cấp/tiện ích/công khai/with_signin/app.js
// Handle sign-in/sign-out.
let auth = gapi.auth2.getAuthInstance();

// Watch for sign in status changes to update the UI appropriately.
let onSignInChanged = (isSignedIn) => {
  // Update UI to switch between signed in/out states
  // ...
}
auth.isSignedIn.listen(onSignInChanged);
onSignInChanged(auth.isSignedIn.get()); // Trigger with current status.

// Connect sign-in/sign-out buttons.
document.getElementById("sign-in").onclick = function(e) {
  auth.signIn();
};
document.getElementById("sign-out").onclick = function(e) {
  auth.signOut();
};

Để biết thêm chi tiết, hãy xem phần Đăng nhập bằng Google.

Tự động đăng nhập người dùng

Bạn có thể đơn giản hoá trải nghiệm đăng nhập bằng cách ủy quyền trước cho ứng dụng thay mặt cho người dùng trong tổ chức. Kỹ thuật này cũng hữu ích nếu sử dụng Proxy nhận dạng của Cloud để bảo vệ ứng dụng.

Để biết thêm thông tin, hãy xem Sử dụng Đăng nhập bằng Google với Ứng dụng CNTT.

Tuỳ chỉnh giao diện

Bạn có thể thay đổi giao diện tìm kiếm thông qua kết hợp các kỹ thuật:

  • Ghi đè kiểu bằng CSS
  • Trang trí các thành phần bằng bộ chuyển đổi
  • Tạo phần tử tùy chỉnh bằng bộ chuyển đổi

Ghi đè kiểu bằng CSS

Tiện ích tìm kiếm đi kèm với CSS riêng để tạo kiểu đề xuất, phần tử kết quả cũng như kiểm soát phân trang. Bạn có thể định kiểu lại các phần tử này nếu cần.

Trong khi tải, tiện ích tìm kiếm sẽ tải động biểu định kiểu mặc định. Điều này xảy ra sau khi biểu định kiểu ứng dụng được tải, làm tăng mức độ ưu tiên của các quy tắc. Để đảm bảo các kiểu của riêng bạn được ưu tiên hơn so với kiểu mặc định, hãy sử dụng bộ chọn tổ tiên để tăng tính cụ thể của các quy tắc mặc định.

Ví dụ: quy tắc sau sẽ không có hiệu lực nếu được tải trong một thẻ link hoặc style tĩnh trong tài liệu.

.cloudsearch_suggestion_container {
  font-size: 14px;
}

Thay vào đó, hãy đủ điều kiện cho quy tắc có ID hoặc lớp của vùng chứa đối tượng cấp trên được khai báo trong trang.

#suggestions_anchor .cloudsearch_suggestion_container {
  font-size: 14px;
}

Để biết danh sách các lớp hỗ trợ và HTML mẫu do tiện ích tạo ra, hãy xem tài liệu tham khảo Các lớp CSS được hỗ trợ.

Trang trí các thành phần bằng bộ chuyển đổi

Để trang trí một phần tử trước khi kết xuất, hãy tạo và điều chỉnh trình chuyển đổi triển khai một trong các phương thức trang trí như decorateSuggestionElement hoặc decorateSearchResultElement.

Ví dụ: các bộ chuyển đổi sau đây thêm một lớp tuỳ chỉnh vào phần tử đề xuất và kết quả.

cung cấp/tiện ích/công khai/with_decorated_element/app.js
/**
 * Search box adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.decorateSuggestionElement = function(element) {
  element.classList.add('my-suggestion');
}

/**
 * Results container adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.decorateSearchResultElement = function(element) {
  element.classList.add('my-result');
}

Để đăng ký trình chuyển đổi này khi khởi chạy tiện ích, hãy sử dụng phương thức setAdapter() của lớp Builder tương ứng:

cung cấp/tiện ích/công khai/with_decorated_element/app.js
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

Trang trí có thể sửa đổi các thuộc tính của phần tử vùng chứa cũng như bất kỳ phần tử con nào. Bạn có thể thêm hoặc xóa phần tử con trong quá trình trang trí. Tuy nhiên, nếu thay đổi cấu trúc các phần tử, hãy cân nhắc tạo trực tiếp các phần tử thay vì trang trí.

Tạo phần tử tùy chỉnh bằng bộ chuyển đổi

Để tạo một phần tử tùy chỉnh cho một đề xuất, vùng chứa thuộc tính hoặc kết quả tìm kiếm, hãy tạo và đăng ký một bộ chuyển đổi có triển khai createSuggestionElement, createFacetResultElement hoặc createSearchResultElement.

Các bộ chuyển đổi sau minh hoạ cách tạo phần tử đề xuất tuỳ chỉnh và kết quả tìm kiếm bằng thẻ HTML <template>.

cung cấp/tiện ích/công khai/with_custom_element/app.js
/**
 * Search box adapter that overrides creation of suggestion elements.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.createSuggestionElement = function(suggestion) {
  let template = document.querySelector('#suggestion_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.suggested_query').textContent = suggestion.suggestedQuery;
  return fragment.firstElementChild;
}

/**
 * Results container adapter that overrides creation of result elements.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.createSearchResultElement = function(result) {
  let template = document.querySelector('#result_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.title').textContent = result.title;
  fragment.querySelector('.title').href = result.url;
  let snippetText = result.snippet != null ?
    result.snippet.snippet : '';
  fragment.querySelector('.query_snippet').innerHTML = snippetText;
  return fragment.firstElementChild;
}

Để điều chỉnh bộ chuyển đổi khi khởi chạy tiện ích, hãy sử dụng phương thức setAdapter() của lớp Builder tương ứng:

cung cấp/tiện ích/công khai/with_custom_element/app.js
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

Việc tạo các phần tử thuộc tính tuỳ chỉnh bằng createFacetResultElement sẽ phải tuân theo một số hạn chế:

  • Bạn phải đính kèm lớp CSS cloudsearch_facet_bucket_clickable vào phần tử mà người dùng nhấp vào để bật/tắt một bộ chứa.
  • Bạn phải gói từng bộ chứa trong một phần tử chứa bằng lớp CSS cloudsearch_facet_bucket_container.
  • Bạn không thể kết xuất các nhóm theo thứ tự khác với nhóm xuất hiện trong phản hồi.

Ví dụ: đoạn mã sau đây sẽ hiển thị các thuộc tính bằng cách sử dụng liên kết thay vì hộp kiểm.

cung cấp/tiện ích/công khai/with_custom_facet/app.js
/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}

ResultsContainerAdapter.prototype.createFacetResultElement = function(result) {
  // container for the facet
  var container = document.createElement('div');

  // Add a label describing the facet (operator/property)
  var label = document.createElement('div')
  label.classList.add('facet_label');
  label.textContent = result.operatorName;
  container.appendChild(label);

  // Add each bucket
  for(var i in result.buckets) {
    var bucket = document.createElement('div');
    bucket.classList.add('cloudsearch_facet_bucket_container');

    // Extract & render value from structured value
    // Note: implementation of renderValue() not shown
    var bucketValue = this.renderValue(result.buckets[i].value)
    var link = document.createElement('a');
    link.classList.add('cloudsearch_facet_bucket_clickable');
    link.textContent = bucketValue;
    bucket.appendChild(link);
    container.appendChild(bucket);
  }
  return container;
}

// Renders a value for user display
ResultsContainerAdapter.prototype.renderValue = function(value) {
  // ...
}

Tùy chỉnh hành vi tìm kiếm

Cài đặt Ứng dụng tìm kiếm đại diện cho cấu hình mặc định cho giao diện tìm kiếm và là tĩnh. Để triển khai bộ lọc động hoặc các khía cạnh, chẳng hạn như cho phép người dùng bật/tắt các nguồn dữ liệu, bạn có thể ghi đè chế độ cài đặt ứng dụng tìm kiếm bằng cách chặn một yêu cầu tìm kiếm bằng bộ chuyển đổi.

Triển khai bộ chuyển đổi bằng phương thức interceptSearchRequest để sửa đổi các yêu cầu được gửi đến API tìm kiếm trước khi thực thi.

Ví dụ: bộ chuyển đổi sau đây chặn các yêu cầu hạn chế truy vấn đối với một nguồn do người dùng chọn:

cung cấp/tiện ích/công khai/with_request_counteror/app.js
/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}
ResultsContainerAdapter.prototype.interceptSearchRequest = function(request) {
  if (!this.selectedSource || this.selectedSource == 'ALL') {
    // Everything selected, fall back to sources defined in the search
    // application.
    request.dataSourceRestrictions = null;
  } else {
    // Restrict to a single selected source.
    request.dataSourceRestrictions = [
      {
        source: {
          predefinedSource: this.selectedSource
        }
      }
    ];
  }
  return request;
}

Để đăng ký trình chuyển đổi khi khởi chạy tiện ích, hãy sử dụng phương thức setAdapter() khi tạo ResultsContainer

cung cấp/tiện ích/công khai/with_request_counteror/app.js
var resultsContainerAdapter = new ResultsContainerAdapter();
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(resultsContainerAdapter)
  // ...
  .build();

HTML sau đây được dùng để hiển thị hộp chọn để lọc theo nguồn:

cung cấp/widget/public/with_request_counteror/index.html
<div>
  <span>Source</span>
  <select id="sources">
    <option value="ALL">All</option>
    <option value="GOOGLE_GMAIL">Gmail</option>
    <option value="GOOGLE_DRIVE">Drive</option>
    <option value="GOOGLE_SITES">Sites</option>
    <option value="GOOGLE_GROUPS">Groups</option>
    <option value="GOOGLE_CALENDAR">Calendar</option>
    <option value="GOOGLE_KEEP">Keep</option>
  </select>
</div>

Mã sau đây xử lý thay đổi, đặt lựa chọn và thực thi lại truy vấn nếu cần.

cung cấp/tiện ích/công khai/with_request_counteror/app.js
// Handle source selection
document.getElementById('sources').onchange = (e) => {
  resultsContainerAdapter.selectedSource = e.target.value;
  let request = resultsContainer.getCurrentRequest();
  if (request.query) {
    // Re-execute if there's a valid query. The source selection
    // will be applied in the interceptor.
    resultsContainer.resetState();
    resultsContainer.executeRequest(request);
  }
}

Bạn cũng có thể chặn phản hồi tìm kiếm bằng cách triển khai interceptSearchResponse trong trình chuyển đổi.

Ghim phiên bản API

Theo mặc định, tiện ích này sử dụng phiên bản API ổn định mới nhất. Để khoá một phiên bản cụ thể, hãy đặt tham số cấu hình cloudsearch.config/apiVersion thành phiên bản ưu tiên trước khi khởi chạy tiện ích.

cung cấp/tiện ích/công khai/cơ bản/app.js
gapi.config.update('cloudsearch.config/apiVersion', 'v1');

Phiên bản API sẽ mặc định là 1.0 nếu không được đặt hoặc được đặt thành giá trị không hợp lệ.

Ghim phiên bản tiện ích

Để tránh những thay đổi không mong muốn đối với giao diện tìm kiếm, hãy đặt thông số cấu hình cloudsearch.config/clientVersion như sau:

gapi.config.update('cloudsearch.config/clientVersion', 1.1);

Phiên bản tiện ích con sẽ mặc định là 1.0 nếu không được đặt hoặc được đặt thành giá trị không hợp lệ.

Bảo mật giao diện tìm kiếm

Kết quả tìm kiếm chứa thông tin có tính nhạy cảm cao. Làm theo các phương pháp hay nhất để bảo mật ứng dụng web, đặc biệt là đối với các cuộc tấn công jackjacking.

Để biết thêm thông tin, hãy xem Dự án hướng dẫn OWASP

Bật tính năng gỡ lỗi

Sử dụng interceptSearchRequest để bật tính năng gỡ lỗi cho tiện ích tìm kiếm. Ví dụ:

  if (!request.requestOptions) {
  // Make sure requestOptions is populated
  request.requestOptions = {};
  }
  // Enable debugging
  request.requestOptions.debugOptions = {enableDebugging: true}

  return request;