# Browser Actions ## Contents 1. [Manifest](browserAction.html#manifest) 2. [UI的組成部分](browserAction.html#ui) 1. [圖標](browserAction.html#icon) 2. [tooltip](browserAction.html#tooltip) 3. [Badge](browserAction.html#badge) 4. [Popup](browserAction.html#popups) 3. [Tips](browserAction.html#H2-6) 4. [范例](browserAction.html#examples) 5. [API reference: chrome.browserAction](browserAction.html#apiReference) 1. [Methods](browserAction.html#methods) 1. [setBadgeBackgroundColor](browserAction.html#method-setBadgeBackgroundColor) 2. [setBadgeText](browserAction.html#method-setBadgeText) 3. [setIcon](browserAction.html#method-setIcon) 4. [setPopup](browserAction.html#method-setPopup) 5. [setTitle](browserAction.html#method-setTitle) 2. [Events](browserAction.html#events) 1. [onClicked](browserAction.html#event-onClicked) 用 browser actions 可以在chrome主工具條的地址欄右側增加一個圖標。作為這個圖標的延展，一個browser action圖標還可以有[](browserAction.html#tooltip)[tooltip](browserAction.html#tooltip)、[badge](browserAction.html#badge)和[popup](browserAction.html#popups)。 如下圖, 地址欄右側的彩色正方形是一個browser action的圖標， 圖標下面的是popup。  如果你想創建一個不總是可見的圖標, 可以使用[page action](pageAction.html)來代替browser action. **注意:**Packaged apps 不能使用browser actions. ## Manifest 在[extension manifest](manifest.html)中用下面的方式注冊你的browser action: ``` { "name": "My extension", ... **"browser_action": { "default_icon": "images/icon19.png", _// optional_ "default_title": "Google Mail", _// optional; shown in tooltip_ "default_popup": "popup.html" _// optional_ }**, ... } ``` ## UI的組成部分 一個 browser action 可以擁有一個[圖標](browserAction.html#icon)，一個[tooltip](browserAction.html#tooltip)，一個[badge](browserAction.html#badge)和一個[popup](browserAction.html#popups)。 ### 圖標 Browser action 圖標推薦使用寬高都為19像素，更大的圖標會被縮小。 你可以用兩種方式來設置圖標: 使用一個靜態圖片或者使用HTML5[canvas element](http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html)。 使用靜態圖片適用于簡單的應用程序，你也可以創建諸如平滑的動畫之類更豐富的動態UI(如canvas element)。 靜態圖片可以是任意WebKit支持的格式，包括 BMP，GIF，ICO，JPEG或 PNG。 修改**browser_action**的[manifest](browserAction.html#manifest)中 **default_icon**字段，或者調用[setIcon()](browserAction.html#method-setIcon)方法。 ### ToolTip 修改**browser_action**的[manifest](browserAction.html#manifest)中**default_title**字段[](browserAction.html#manifest)，或者調用[setTitle()](browserAction.html#method-setTitle)方法。你可以為**default_title**字段指定本地化的字符串；點擊[Internationalization](i18n.html)查看詳情。 ### Badge Browser actions可以選擇性的顯示一個_badge_— 在圖標上顯示一些文本。Badges 可以很簡單的為browser action更新一些小的擴展狀態提示信息。 因為badge空間有限，所以只支持4個以下的字符。 設置badge文字和顏色可以分別使用[setBadgeText()](browserAction.html#method-setBadgeText)and[setBadgeBackgroundColor()](browserAction.html#method-setBadgeBackgroundColor)。 ### Popup 如果browser action擁有一個popup，popup 會在用戶點擊圖標后出現。popup 可以包含任意你想要的HTML內容，并且會自適應大小。 在你的browser action中添加一個popup，創建彈出的內容的HTML文件。 修改**browser_action**的[manifest](browserAction.html#manifest)中**default_popup**字段來指定HTML文件， 或者調用[setPopup()](browserAction.html#method-setPopup)方法。 ## Tips 為了獲得最佳的顯示效果, 請遵循以下原則： * **確認** Browser actions 只使用在大多數網站都有功能需求的場景下。 * **確認** Browser actions 沒有使用在少數網頁才有功能的場景， 此場景請使用[page actions](pageAction.html)。 * **確認**你的圖標尺寸盡量占滿19x19的像素空間。 Browser action 的圖標應該看起來比page action的圖標更大更重。 * **不要**嘗試模仿Google Chrome的扳手圖標，在不同的themes下它們的表現可能出現問題,，并且擴展應該醒目些。 * **盡量**使用alpha通道并且柔滑你的圖標邊緣，因為很多用戶使用themes，你的圖標應該在在各種背景下都表現不錯。 * **不要**不停的閃動你的圖標，這很惹人反感。 ## 范例 你可以在 [examples/api/browserAction](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/)目錄找到簡單的browser actions范例，更多的范例和幫助文檔可以參考[Samples](samples.html)。 ## API reference: chrome.browserAction ### Properties <a></a> #### getLastError chrome.extensionlastError ### Methods #### setBadgeBackgroundColor void chrome.browserAction.setBadgeBackgroundColor(, object `details`) Undocumented. 設置badge的背景顏色。 #### Parameters `details`_( optional enumerated Type array of object )_ 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. `color`_( optional enumerated Type array of Type array of integer paramType )_ Undocumented. 范圍為[0,255]整數構成的結構，用來描述badge的RGBA顏色。例如：不透明的紅色是[255, 0, 0, 255]。 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. `tabId`_( optional enumerated Type array of integer )_ 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. #### 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. #### setBadgeText void chrome.browserAction.setBadgeText(, object `details`) Undocumented. 設置browser action的badge文字，badge 顯示在圖標上面。 #### Parameters `details`_( optional enumerated Type array of object )_ 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. `text`_( optional enumerated Type array of string )_ Undocumented. 任意長度的字符串，但只有前4個字符會被顯示出來。 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. `tabId`_( optional enumerated Type array of integer )_ 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. #### 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. #### setIcon void chrome.browserAction.setIcon(, object `details`) Undocumented. 設置browser action的圖標。圖標可以是一個圖片的路徑或者是從一個canvas元素提取的像素信息.。無論是**圖標路徑**還是canvas的 **imageData**，這個屬性必須被指定。 #### Parameters `details`_( optional enumerated Type array of object )_ 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. `imageData`_( optional enumerated Type array of ImageData )_ Undocumented. 圖片的像素信息。必須是一個ImageData 對象(例如：一個canvas元素)。 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. `path`_( optional enumerated Type array of string )_ 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. `tabId`_( optional enumerated Type array of integer )_ 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. #### 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. #### setPopup void chrome.browserAction.setPopup(, object `details`) Undocumented. 設置一個點擊browser actions時顯示在popup中的HTML。 #### Parameters `details`_( optional enumerated Type array of object )_ 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. `tabId`_( optional enumerated Type array of integer )_ 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. `popup`_( optional enumerated Type array of string )_ Undocumented. popup中顯示的html文件。如果設置為空字符('')，將不顯示popup。 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) {...}; ``` 這個功能已經在**chromium 5.0.316.0版本**添加。如果你需要這個功能，可以通過manifest的[minimum_chrome_version](manifest.html#minimum_chrome_version)鍵值來確認你的擴展不會運行在早期的瀏覽器版本。 #### setTitle void chrome.browserAction.setTitle(, object `details`) Undocumented. 設置browser action的標題，這個將顯示在tooltip中。 #### Parameters `details`_( optional enumerated Type array of object )_ 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. `title`_( optional enumerated Type array of string )_ Undocumented. 鼠標移動到browser action上時顯示的文字。 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. `tabId`_( optional enumerated Type array of integer )_ 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. #### 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 #### onClicked chrome.browserAction.onClicked.addListener(function(Tab tab) {...}); Undocumented. 當browser action 圖標被點擊的時候觸發，當browser action是一個popup的時候，這個事件將不會被觸發。 #### Parameters `tab`_( optional enumerated [Tab](tabs.html#type-Tab) array of paramType )_ 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. ### Types <a></a> #### type name