# 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)的更新。