chrome.omnibox

描述 多功能框 API 允许您在 Google Chrome 浏览器的地址栏(又叫多功能框)中注册一个关键字。
可用版本 从 Chrome 9 开始支持。
清单文件 "omnibox": {...}

A screenshot showing suggestions related to the keyword 'Chromium Search'

当用户输入您的扩展程序的关键字时,用户开始完全与您的扩展程序交互。每一次按键消息都将发送至您的扩展程序,您可以作出回应,提供建议。

建议可以具有各种不同格式。当用户接受某个建议时,将通知您的扩展程序作出反应。

清单文件

您必须在清单文件中包含 omnibox keyword 属性来使用多功能框 API,您还应该指定一个 16×16 像素的图标,当用户进入关键字模式时,显示在地址栏中。

例如:

      {
        "name": "Aaron 的多功能框扩展程序",
        "version": "1.0",
        "omnibox": { "keyword" : "aaron" },
        "icons": {
          "16": "16-full-color.png"
        },
        "background": {
          "persistent": false,
          "scripts": ["background.js"]
        }
      }
      

注意:Chrome 浏览器会自动创建您的 16×16 像素图标的灰度版本。您应该提供彩色的图标,以便用于其他需要颜色的情况,例如,右键菜单 API 也使用 16×16 像素的图标,但是显示为彩色。

例子

您可以在示例页面找到这一 API 的例子。

摘要

类型
SuggestResult
方法
setDefaultSuggestion chrome.omnibox.setDefaultSuggestion(object suggestion)
事件
onInputStarted
onInputChanged
onInputEntered
onInputCancelled

类型

SuggestResult

建议结果。
属性
string content

输入在地址栏中的文字,当用户选择这一项时发送给扩展程序。

string description

显示在地址栏下拉框中的文字,可以包含 XML 样式标记。支持的标记为 (用于字面的 URL)、(用于匹配用户查询的高亮文本)和 (用于帮助文本的浅色效果)。样式也可以嵌套,例如:浅色的匹配文本

方法

setDefaultSuggestion

chrome.omnibox.setDefaultSuggestion(object suggestion)

设置默认建议的描述和样式,默认建议即显示在 URL 栏下的第一行建议。

参数
object suggestion

具有部分内容的 SuggestResult 对象,没有"content"参数。

string description

显示在地址栏下拉框中的文字,可以包含 XML 样式标记。支持的标记为 (用于字面的 URL)、(用于匹配用户查询的高亮文本)和 (用于帮助文本的浅色效果)。样式也可以嵌套,例如:浅色的匹配文本

事件

onInputStarted

用户输入了扩展程序的关键字,开始关键字输入会话。这一事件确保每次进入输入会话时发送一次,并且在任何 onInputChanged 事件之前发生。

addListener

chrome.omnibox.onInputStarted.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function() {...};

onInputChanged

用户更改了输入在多功能框中的内容。

addListener

chrome.omnibox.onInputChanged.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(string text, function suggest) {...};
string text
function suggest

传递给 onInputChanged 事件的回调函数,用于将建议发回浏览器。

suggest 参数应该是一个如下形式的函数:

function(array of SuggestResult suggestResults) {...};
array of SuggestResult suggestResults

包含建议结果的数组。

onInputEntered

用户接受了输入在多功能框中的内容。

addListener

chrome.omnibox.onInputEntered.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(string text, enum of "currentTab", "newForegroundTab", or "newBackgroundTab" disposition) {...};
string text
enum of "currentTab", "newForegroundTab", or "newBackgroundTab" disposition

从 Chrome 28 开始支持。

多功能框查询的窗口性质,即推荐的显示结果的上下文。例如,如果多功能框命令导航至某个 URL,'newForegroundTab'(新的前台标签页)意味着导航应该在新建的已选中标签页中发生。

onInputCancelled

用户结束了关键字输入,没有接受输入。

addListener

chrome.omnibox.onInputCancelled.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function() {...};

示例扩展程序

  • Omnibox Example – To use, type 'omnix' plus a search term into the Omnibox.
  • Chromium Search – Add support to the omnibox to search the Chromium source code.