搜索微件为 Web 应用提供可自定义的搜索界面。 该微件只需要少量 HTML 和 JavaScript 即可实现并启用常用的搜索功能,如构面和分页。您还可以使用 CSS 和 JavaScript 自定义界面的各个部分。
如果该微件的灵活性未能满足您的需要,请考虑使用 Query API。如需了解如何使用 Query API 创建搜索界面,请参阅使用 Query API 创建搜索界面。
构建搜索界面
构建搜索界面需要执行以下几个步骤:
- 配置搜索应用
- 为应用生成客户端 ID
- 为搜索框和结果添加 HTML 标记
- 在页面上加载微件
- 初始化微件
配置搜索应用
每个搜索界面都必须在管理控制台中定义搜索应用。搜索应用为查询提供其他信息,例如数据源、构面和搜索质量设置。
如需创建搜索应用,请参阅打造自定义搜索体验。
为应用生成客户端 ID
除了配置对 Google Cloud Search API 的访问权限中介绍的步骤以外,您还必须为 Web 应用生成客户端 ID。
配置项目时,请执行以下操作:
- 选择网络浏览器客户端类型。
- 提供应用的原始 URI。
- 记下所创建的客户端 ID。您需要使用客户端 ID 完成后续步骤。该微件不需要用到客户端密钥。
如需了解其他信息,请参阅适用于客户端 Web 应用的 OAuth 2.0。
添加 HTML 标记
该微件只需要少量 HTML 即可运行。您必须提供以下元素:
- 搜索框的
input
元素。 - 锚定弹出式建议的元素。
- 包含搜索结果的元素。
- (可选)包含构面控件的元素。
以下 HTML 代码段显示了搜索微件的 HTML,其中要绑定的元素由其 id
属性标识:
加载微件
系统会通过加载程序脚本动态加载该微件。如需添加加载程序,请使用 <script>
标记,如下所示:
您必须在 script 标记中提供 onload
回调函数。加载程序准备就绪后,系统会调用该函数。此时,请调用 gapi.load()
加载 API 客户端、Google 登录和 Cloud Search 模块,以继续加载微件。
加载所有模块后,系统会调用 initializeApp()
函数。
初始化微件
首先,使用生成的客户端 ID 和 https://www.googleapis.com/auth/cloud_search.query
范围调用 gapi.client.init()
或 gapi.auth2.init()
来初始化客户端库。接下来,使用 gapi.cloudsearch.widget.resultscontainer.Builder
和 gapi.cloudsearch.widget.searchbox.Builder
类配置该微件并将其绑定到 HTML 元素。
以下示例显示了如何初始化该微件:
上面的示例引用了配置的两个变量,其定义如下:
自定义登录体验
默认情况下,微件会在用户开始输入查询时提示用户登录应用并向应用授权。您可以使用适用于网站的 Google 登录为用户提供更加个性化的登录体验。
直接向用户授权
使用使用 Google 账号登录监控用户的登录状态,并根据需要登录或注销用户。例如,以下示例会观察 isSignedIn
状态以监控登录更改,并使用 GoogleAuth.signIn()
方法通过按钮点击启动登录:
如需了解更多详情,请参阅使用 Google 账号登录。
自动登录用户
您可以代表您的组织中的用户预先向应用授权,从而进一步简化登录体验。在使用 Cloud Identity-Aware Proxy 保护应用时,此项技术也很有用。
如需了解其他信息,请参阅将 Google 登录与 IT 应用配合使用。
自定义界面
您可以通过组合使用以下技术更改搜索界面的外观:
- 使用 CSS 替换样式
- 使用适配器修饰元素
- 使用适配器创建自定义元素
使用 CSS 替换样式
搜索微件附带了自己的 CSS,用于为建议和结果元素以及分页控件设置样式。您可以根据需要重新设置这些元素的样式。
在加载期间,搜索微件会动态加载其默认样式表。 此操作将在应用样式表加载后进行,从而提高规则的优先级。如需确保您自己的样式优先于默认样式,请使用祖先选择器提高默认规则的特异性。
例如,在文档的静态 link
或 style
标记中加载的以下规则无效。
.cloudsearch_suggestion_container {
font-size: 14px;
}
请改为使用在页面中声明的祖先容器的 ID 或类来限定规则。
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
如需查看支持类列表和微件生成的示例 HTML,请参阅支持的 CSS 类参考。
使用适配器修饰元素
如需在渲染之前装饰元素,请创建并注册一个实现装饰方法之一(例如 decorateSuggestionElement
或 decorateSearchResultElement.
)的适配器
例如,以下适配器可以将自定义类添加到建议和结果元素中。
如需在初始化微件时注册适配器,请使用相应 Builder
类的 setAdapter()
方法:
修饰器可以修改容器元素以及任何子元素的特性。在修饰期间,系统可能会添加或移除子元素。但是,如果要更改元素的结构,请考虑直接创建元素而不是修饰元素。
使用适配器创建自定义元素
如需为建议、细分容器或搜索结果创建自定义元素,请分别创建并注册实现 createSuggestionElement
、createFacetResultElement
或 createSearchResultElement
的适配器。
以下适配器展示了如何使用 HTML <template>
标记创建自定义建议和搜索结果元素。
如需在初始化微件时注册适配器,请使用相应 Builder
类的 setAdapter()
方法:
使用 createFacetResultElement
创建自定义构面元素会受到以下几个限制的约束:
- 您必须将 CSS 类
cloudsearch_facet_bucket_clickable
附加到用户在切换存储分区时需要点击的元素。 - 您必须将每个存储分区封装在一个具有 CSS 类
cloudsearch_facet_bucket_container
的包含元素中。 - 您只能按照存储分区在响应中的显示顺序来呈现存储分区。
例如,以下代码段使用链接(而不是复选框)呈现构面。
自定义搜索行为
搜索应用设置是静态的,这些设置代表搜索界面的默认配置。如需实现动态过滤条件或构面(例如允许用户切换数据源),您可以使用适配器拦截搜索请求并替换搜索应用设置。
使用 interceptSearchRequest
方法实现适配器,以便在执行之前修改对 Search API 发出的请求。
例如,以下适配器会拦截请求,将查询限制在用户所选的数据源:
如需在初始化微件时注册适配器,请在构建 ResultsContainer
时使用 setAdapter()
方法
以下 HTML 用于显示按数据源进行过滤的选择框:
以下代码可以侦听更改、设置选择并在必要时重新执行查询。
您还可以通过在适配器中实现 interceptSearchResponse
来拦截搜索响应。
锁定 API 版本
默认情况下,该微件使用最新的稳定版 API。如需锁定特定版本,请在初始化该微件之前将 cloudsearch.config/apiVersion
配置参数设置为首选版本。
如果未设置 API 版本或者将其设置为无效值,则默认使用 1.0 版。
锁定微件版本
为避免意外更改搜索界面,请设置 cloudsearch.config/clientVersion
配置参数,如下所示:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
如果未设置微件版本或者将其设置为无效值,则系统将默认使用 1.0 版。
保护搜索界面
搜索结果包含高度敏感的信息。请按照最佳做法来保护 Web 应用,尤其要保护 Web 应用免遭点击劫持攻击。
如需了解更多信息,请参阅 OWASP 指南项目。
启用调试功能
使用 interceptSearchRequest
打开搜索微件的调试功能。例如:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;