Freebase 建议微件

  1. Freebase Suggestion 简介
  2. 将 Freebase Suggestion 添加到您的网站
  3. 配置选项
  4. 修改 CSS
  5. 事件的工作原理
  6. 更多信息和常见问题解答
  7. 示例和食谱

Freebase Suggestion 简介

Freebase Suggestion 是一个 jQuery 插件,可将 Freebase 主题自动补全功能添加到您网站上的搜索框中。用户开始输入文本时,该微件会根据 Freebase.com 上的数百万个主题或各类类型(例如人物、地点或动物)提供相关匹配内容。主题跳出有助于用户选择通过 Freebase ID 进行唯一标识的正确内容。

Freebase Suggested.png

特性

  • 跨浏览器 - 基于 jQuery,在 IE7+、FF2+、Safari 3+ 和 Chrome 上进行测试(jquery 最低版本为 1.4.4)
  • 跨网域。得益于 JSONP,无需使用代理服务器。
  • 由 Google 在 gstatic.com 上托管
  • 免费!(适用 Freebase 条款Google Developer API 条款。)

试试看!

野外免费数据库建议

已知使用 Freebase Suggestion 的网站:

为何使用 Freebase Suggestion?

  • 借助自动补全功能,您的用户无需输入太多数据即可输入更多数据。
  • 数据输入过程既有趣又准确!
  • 通过主题跳出中的图片和说明,减少用户的认知负担。
  • 使用醒目的标识码而非文字关键字。名称“Sting”有歧义,但 Freebase ID /en/sting/en/sting_1959 不是。
  • 避免为同一实体使用重复的名称。Puff Daddy, P. 迪迪、肖恩·考姆斯指的都是/en/sean_combs

向您的网站添加 Freebase Suggestion

要将 Freebase Suggestion 添加到您的网页中,请在您网站的源代码中添加以下代码。您还可以获取并使用 API 密钥来扩展 Freebase Suggestion 的功能。

要添加到您网站的代码

在 HTML 文档的 <head> 中添加以下代码:

<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/freebase/suggest/4_1/suggest.min.css" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.js"></script>
<script type="text/javascript" src="https://www.gstatic.com/freebase/suggest/4_1/suggest.min.js"></script>
<script type="text/javascript">
$(function() {
  $("#myinput").suggest({filter:'(all type:/film/director)'});
});
</script>

然后,在文档中使用如下所示的输入字段 <body>

<input type="text" id="myinput"/>

获取 API 密钥

获取 API 密钥后,您的应用可以发出 Suggestion 请求。如果没有 API 密钥,该微件只能用于有限的测试目的。要获取密钥,请按照我们的使用入门页面上的说明进行操作。

获取密钥后,使用如下代码将其传递给 Freebase Suggestion:

$(function() {
  $("#myinput").suggest({ "key" : "<your api key>"});
});

配置选项

下表介绍了 Freebase Suggestion 的配置选项。

名称 类型 默认 说明
高级 布尔值 true 如果为 true,Freebase Suggestion 会解析并处理输入中的内嵌 name:value 对,作为额外的过滤条件限制。例如,对于 'bob type:artist contributed_to:"Love and Theft"'(附加过滤条件约束),系统会将 '(all type:artist contributed_to:"Love and Theft")' 传递给搜索。此外,高级选项为 true 时,Freebase Suggestion 会识别 Freebase ID 和 MID,以便通过 ID 或 MID 直接搜索实体。
完全匹配 布尔值 false 如果为 true,则表示 Search API 仅返回完全匹配的内容(即输入内容中的内容)。系统会将此值透明地传递给 Search API。
filter 字符串 null 指定将作为过滤条件参数透明地传递到 Search API 的默认搜索过滤条件限制。例如,要将 Freebase Suggestion 限制为只在学院和/或大学搜索,请使用“(all type:/education/university)”作为过滤条件。如需查看可用搜索过滤条件的完整列表,请参阅 Search API文本限制
密钥 字符串 null service_url + service_path 指定的默认 Search API 提供 API 密钥。您可以从 API 控制台获取一个。
lang 字符串 null lang 参数接受以英文逗号分隔的语言代码列表,该列表会使搜索以指定的所有语言完成,并且结果会排名第一的语言,并以结果实体列表中首个实体的名称列出。目前,系统支持 18 种语言,即 1 个英语(英文)(12 个),目前为止,英语的覆盖率最高,并且是默认语言。系统会将此值透明地传递给 Search API。
评分 字符串 null 借助 scoring 参数,您可以控制使用哪些相关性得分组件来计算最终得分。此值会以透明方式传递给 Search API。
  • entity:同时使用 FREEBASE 和 Google 相关性得分,默认缺失 Google 得分为 1.0。这是默认值。
  • freebase:仅使用 Freebase 相关性得分。
  • schema:在查找类型、属性或网域等架构实体时使用。架构实体的链接计数计算方式不同。
拼写 字符串 always 有效值包括 alwaysno_resultsno_spelling。如果已请求拼写,但搜索返回了拼写更正,Freebase Suggestion 将在“建议”列表中显示更正内容。此值会以透明方式传递给搜索服务。
飞出 布尔值,bottom true 确定是否在鼠标悬停时显示飞出说明。如果状态为 bottom,则显示在建议列表底部。如果输入框上方显示建议列表,则会在列表顶部显示弹出菜单。如果为 true,则 Google 建议会尽可能在列表的左侧或右侧显示弹出框。
建议新 字符串 null 建议列表下方显示的文字。选择后,系统会触发 fb-select-new
css 对象 覆盖用于各种 Freebase Suggestion 元素的默认 CSS 类名称。如需了解详情,请参阅修改 CSS
css_prefix 字符串 null 您可以指定前置到 Suggestion 元素的类名称的前缀。例如,如果 css_prefix 为“foo-”,则容器名称将为“foo-fbs-pane”和“foo-fbs-flyoutpane”。
show_id 布尔值 true 显示搜索所返回的 &'notable 值。不过,如果不存在此 ID,则为 true,则会显示商品的 ID。
service_url 字符串 值为 https://www.googleapis.com/freebase/v1 这是 Google 建议服务的基本网址。
服务路径 字符串 /search service_url + service_path = 建议服务的网址。
flyout_service_url 字符串 null 飞出服务的基本网址。如果为 null,则默认为 service_url
flyout_service_path 字符串 值为 /topic${id}?filter=suggest&limit=3&key=${key} flyout_service_url + flyout_service_path = 跳出服务的网址。'${id}'{key}' 已分别替换为悬停项 ID 和 API 密钥。
flyout_image_service_url 字符串 null 飞出图片中的基准网址。如果为 null,则默认为 service_url
flyout_image_service_path 字符串 /image${id}?maxwidth=75&key=${key} flyout_image_service_url + flyout_image_service_path = 指向图片服务的网址。'${id}'{key}' 将分别替换为悬停项 ID 和 API 密钥。
flyout_parent 字符串(jQuery 选择器) null 默认情况下,飞出容器会附加到文档正文,并绝对定位。flyout_parent 会指定其他父项,并且不会弹出定位。
对齐 字符串 null 如果未设置 align,建议列表会与输入框的“左”或“右”对齐,具体取决于其在文档中的位置。如需替换此行为并明确设置其对齐方式,请将 align 设置为“left”或“right”。
status 数组 [4](字符串) ["开始输入内容以获取建议...",&teot;搜索...”;从列表中选择一项内容:很抱歉,出了点问题。请稍后重试” “建议”的 4 个不同阶段显示的状态消息;[0] 当输入框为空且获得焦点时。[1] 检索结果时,[2] 显示结果时,[3] 表示建议服务出现错误时。您可以通过传入与 4 个不同阶段对应的不同字符串数组来替换这些默认状态消息。
父级 字符串(jQuery 选择器) null 默认情况下,建议列表会附加到文档正文中,并且绝对位于相应位置。使用 parent 指定其他父项,列表并非绝对位置。
animate 布尔值 false 如果为 true,系统将显示 jQuery 下滑效果的“建议”列表动画。
xhr_delay 整数 (ms) 200 指定返回结果前的延迟时间。当 mql_filters 比较复杂且 Suggestion API 响应时间可能会长于硬编码延迟时间时,这会非常有用,这会导致用户体验出现一些下降以及不必要的负载。
Z-index 整数 null 设置最外层容器(fbs-panefbs-flyoutpane)的 Z-index。这在对话框中使用 Freebase 建议时非常有用,可让建议元素显示在顶部。

修改 CSS

通过使用 css 配置选项传入 CSS 类名称的备用值的映射,可以覆盖 Freebase Suggestion 使用的默认 CSS 类。下表介绍了默认 CSS 中的类。

窗格 建议列表的外部容器。

默认值:'fbs-pane'

list 建议列表。

默认值:'fbs-list'

商品 建议列表项。

默认值:'fbs-item'。

item_name 包含商品名称的元素。

默认值:'fbs-item-name'

已选择 当前突出显示/选中的项。默认值:'fbs-selected'。
状态 包含状态消息的元素。默认值:'fbs-status'。
item_type [商品类型] 包含商品的重要类型的元素。默认值:'fbs-item-type'。
飞出窗格 飞出外部容器。

默认值:'fbs-flyoutpane'

例如:

$("#myinput").suggest({
  "css": {
    "pane": "custom-pane-class",
    "list": "custom-list-class"
  }
});

事件的工作原理

Freebase Suggestion 会在其初始化时使用的输入上下文中触发以下事件。

fb-select - 从“建议”列表中选择项目时。该事件会附带一个数据对象,其中 data.namedata.id 表示所选内容的名称和 ID。

$("#myinput").suggest().bind("fb-select", function(e, data) { ... });

fb-select-new - 启用 suggest_new 选项后,系统会在选择 suggest_new 项时触发此事件。该事件会附带输入值。

$("#myinput").suggest({'suggest_new': 'This is the suggest new text'}).bind("fb-select-new", function(e, val) { ... });

常见问题解答和更多信息

欢迎在 Freebase Developers Google 网上论坛问题列表(选择“搜索/建议”组件)中提问、提交错误报告和提供反馈。

我刚刚创建了一个新主题,但它并没有显示在“建议”中 - 这是怎么回事?

Freebase Suggestion 会使用 Search API 提供结果,而且这些结果会近乎实时地更新。新主题通常在 1 分钟左右出现,但如果系统负载过高,这种情况可能会更长。

示例和食谱

基本用法

$("#example1")
 .suggest()
 .bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
});

试试看!

提出新建议

$("#example2")
 .suggest({
   "suggest_new": "Click on me if you don't see anything in the list"
 })
 .bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
 })
 .bind("fb-select-new", function(e, val) {
   alert("Suggest new: " + val);
 });

试试看!

使用过滤条件限制建议

推荐史蒂文·斯皮尔伯格执导的电影。

$("#example5")
.suggest({
   "filter": "(all type:/film/film contributor:\"Steven Spielberg #directed_by\")"
})
.bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
});

试试看!

从文本框中过滤

您可以在“建议”框中直接输入任一过滤条件限制来过滤结果。例如,要搜索有关园艺的图书,请尝试:

gardening type:/book/book
gardening type:book

实际上,您可以使用任何 Search Metaschema 限制条件来过滤搜索结果。例如,要搜索“contributed_to”电影《保存私人瑞恩》的所有人物,请尝试以下操作:

contributed_to:"Saving Private Ryan" type:/people/person

配置选项中所述,langscoringspellexact 会透明地传递给 Search API。您也可以以内嵌方式覆盖它们。例如,如果 Freebase Suggestion 使用 lang:"en" 进行了初始化,并且您还想搜索法语名称,请尝试执行以下操作:

babar lang:fr,en

如需了解其他过滤和搜索限制条件,请参阅搜索实战宝典