# Omnibox ## Contents 1. [Manifest](omnibox.html#manifest) 2. [示例](omnibox.html#examples) 3. [API reference: chrome.omnibox](omnibox.html#apiReference) 1. [Methods](omnibox.html#methods) 1. [setDefaultSuggestion](omnibox.html#method-setDefaultSuggestion) 2. [Events](omnibox.html#events) 1. [onInputCancelled](omnibox.html#event-onInputCancelled) 2. [onInputChanged](omnibox.html#event-onInputChanged) 3. [onInputEntered](omnibox.html#event-onInputEntered) 4. [onInputStarted](omnibox.html#event-onInputStarted) 3. [Types](omnibox.html#types) 1. [SuggestResult](omnibox.html#type-SuggestResult) omnibox 应用程序界面允许向Google Chrome的地址栏注册一个关键字，地址栏也叫omnibox。  当用户输入你的扩展关键字，用户开始与你的扩展交互。每个击键都会发送给你的扩展，扩展提供建议作为相应的响应。 建议可以被格式化多种方式。当用户接受建议，你的扩展被通知可以执行动作。 ## Manifest 使用omnibox 应用程序界面，必须在 [manifest](manifest.html) 中包含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](contextMenus.html) 使用全色的16x16像素图标。 ## 示例 从[sample page](samples.html#omnibox) 页面可以找到使用该API的例子。. ## 应用程序界面参考: chrome.omnibox ### Methods <a></a> #### 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](manifest.html#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](manifest.html#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](manifest.html#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](manifest.html#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](manifest.html#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](manifest.html#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](omnibox.html#type-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](manifest.html#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](manifest.html#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](manifest.html#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](manifest.html#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](http://crbug.com/25317)的更新。