改变浏览器外观-修改地址栏图标（Omnibox）

Contents

1. Manifest

2. 示例

3. API reference: chrome.omnibox

   1. Methods

      1. setDefaultSuggestion

   2. Events

      1. onInputCancelled
      2. onInputChanged
      3. onInputEntered
      4. onInputStarted

   3. Types

      1. SuggestResult

omnibox 应用程序界面允许向Google Chrome的地址栏注册一个关键字，地址栏也叫omnibox。

当用户输入你的扩展关键字，用户开始与你的扩展交互。每个击键都会发送给你的扩展，扩展提供建议作为相应的响应。

建议可以被格式化多种方式。当用户接受建议，你的扩展被通知可以执行动作。

Manifest

使用omnibox 应用程序界面，必须在 manifest 中包含omnibox 关键字段。需要指定像素为16x16的图标，以便当用户输入关键字时，在地址栏中显示。

如：

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  **"omnibox": { "keyword" : "aaron" },** 
  **"icons": {** 
    **"16": "16-full-color.png"** 
  **},** 
  "background_page": "background.html"
}

提示:  Chrome 自动创建灰度模式16x16像素的图标。你应该提供全色版本图标以便可以在其他场景下使用。 如：Context menus API

使用全色的16x16像素图标。

示例

从sample page 页面可以找到使用该API的例子。.

应用程序界面参考: chrome.omnibox

Methods

method name

void chrome.module.methodName(, ``)

Undocumented.

A description from the json schema def of the function goes here.

Parameters

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

setDefaultSuggestion

void chrome.omnibox.setDefaultSuggestion(, object suggestion)

Undocumented.

设置缺省建议的描述和风格。缺省建议是显示在 URL地址栏下的第一个建议显示文字

Parameters

suggestion ( optional enumerated Type array of object )

Undocumented.

一个局部的SuggestResult 对象，没有'content' 参数。关于该参数的描述，请参见SuggestResult。

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

description ( optional enumerated Type array of string )

Undocumented.

显示在缺省建议中的文本，可以包含'%s'并可以被用户输入替换。

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Events

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(function() {...});

Undocumented.

用户结束键盘输入会话，但未接受该输入（取消了输入）。

Parameters

onInputChanged

chrome.omnibox.onInputChanged.addListener(function(string text, function suggest) {...});

Undocumented.

用户修改了在 omnibox中的输入。

Parameters

text ( optional enumerated Type array of string )

Undocumented.

Description of this parameter from the json schema.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

suggest ( optional enumerated Type array of function )

Undocumented.

一个传给onInputChanged 事件的回调，用来在事件发生的时候，发送回建议给浏览器。

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Parameters

paramName ( optional enumerated Type array of SuggestResult array of paramType paramType )

Undocumented.

建议结果，数组。

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

onInputEntered

chrome.omnibox.onInputEntered.addListener(function(string text) {...});

Undocumented.

用户接收了omnibox中的数据。

Parameters

text ( optional enumerated Type array of string )

Undocumented.

Description of this parameter from the json schema.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

onInputStarted

chrome.omnibox.onInputStarted.addListener(function() {...});

Undocumented.

用户输入扩展的关键字，开始了一个键盘输入会话。 这个事件在会话开始时发送，早于其它事件，而且一个会话只会发送一次。

Parameters

Types

SuggestResult

paramName ( optional enumerated Type array of object )

Undocumented.

建议结果。

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

content ( optional enumerated Type array of string )

Undocumented.

在URL区域中的文本，当用户选择该条目时发送给扩展。

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

description ( optional enumerated Type array of string )

Undocumented.

The URL下拉列表中显示的文本。可以包含一个XML风格标记。支持的标签是'url' (作为一个文法上的URL)， 'match' (作为匹配用户请求数据的高亮文本显示)，以及 'dim' (作为灰色辅助文本)。风格可以嵌套。

选项页

为了让用户设定你的扩展功能，你可能需要提供一个选项页。如果你提供了选项页，在扩展管理页面 chrome://extensions上会提供一个链接。点击选项链接就可以打开你的选项页。

在manifest中定义你的选项页

{
  "name": "My extension",
  ...
  **"options_page": "options.html"**,
  ...
}

编写你的选项页

下面是个选项页的范例:

<html>
<head><title>My Test Extension Options</title></head>
<script type="text/javascript">
// Saves options to localStorage.
function save_options() {
  var select = document.getElementById("color");
  var color = select.children[select.selectedIndex].value;
  localStorage["favorite_color"] = color;
  // Update status to let user know options were saved.
  var status = document.getElementById("status");
  status.innerHTML = "Options Saved.";
  setTimeout(function() {
    status.innerHTML = "";
  }, 750);
}
// Restores select box state to saved value from localStorage.
function restore_options() {
  var favorite = localStorage["favorite_color"];
  if (!favorite) {
    return;
  }
  var select = document.getElementById("color");
  for (var i = 0; i < select.children.length; i++) {
    var child = select.children[i];
    if (child.value == favorite) {
      child.selected = "true";
      break;
    }
  }
}
</script>
<body onload="restore_options()">
Favorite Color:
<select id="color">
 <option value="red">red</option>
 <option value="green">green</option>
 <option value="blue">blue</option>
 <option value="yellow">yellow</option>
</select>
<br>
<button onclick="save_options()">Save</button>
</body>
</html>

注意事项

• 本功能在Chromium4.0.222.x以上版本生效。
• 为了鼓励不同扩展之间的选项页的一致性，我们计划提供一些默认的css样式。你可以关注 crbug.com/25317的更新。