擴充功能的使用者介面應保持明確有意義且保持精簡。和擴充功能一樣,UI 也應自訂或強化瀏覽體驗,而不會分散使用者的注意力。
本指南將探索必要和選用的使用者介面功能。您可以運用這個模組,瞭解在擴充功能中實作不同 UI 元素的方式和時機。
在所有網頁上啟用擴充功能
當擴充功能的功能在大多數情況下可正常運作,請使用 browser_action。
註冊瀏覽器動作
系統會在資訊清單中註冊 "browser_action"
欄位。
{
"name": "My Awesome browser_action Extension",
...
"browser_action": {
...
}
...
}
宣告 "browser_action"
時,圖示會保持彩色,表示使用者可以使用擴充功能。
新增徽章
徽章會在瀏覽器圖示上方顯示彩色橫幅,最多顯示四個字元。只有在資訊清單中宣告 "browser_action"
的擴充功能才能使用這些元素。
使用標記指出擴充功能的狀態。「Drink Water Event」範例會顯示附有「ON」的標記,向使用者顯示成功設定鬧鐘,且擴充功能處於閒置狀態時,就不會顯示任何內容。
呼叫 chrome.browserAction.setBadgeText
和橫幅顏色,設定徽章文字 chrome.browserAction.setBadgeBackgroundColor
。
chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});
在所選網頁上啟用擴充功能
如果擴充功能的功能只能在特定情況下使用,請使用 page_action。
宣告網頁動作
系統會在資訊清單中註冊 "page_action"
欄位。
{
"name": "My Awesome page_action Extension",
...
"page_action": {
...
}
...
}
只有在使用者可使用擴充功能時,宣告 "page_action"
才能為圖示上色,否則圖示會以灰階顯示。
定義啟用擴充功能的規則
在背景指令碼中的 runtime.onInstalled
事件監聽器下呼叫 chrome.declarativeContent
,定義擴充功能可用時機的規則。「依網址查看的頁面動作」範例擴充功能會設定網址必須包含「g」的條件。如果符合條件,擴充功能會呼叫 declarativeContent.ShowPageAction()
。
chrome.runtime.onInstalled.addListener(function() {
// Replace all rules ...
chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
// With a new rule ...
chrome.declarativeContent.onPageChanged.addRules([
{
// That fires when a page's URL contains a 'g' ...
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: { urlContains: 'g' },
})
],
// And shows the extension's page action.
actions: [ new chrome.declarativeContent.ShowPageAction() ]
}
]);
});
});
啟用或停用擴充功能
使用 "page_action"
的擴充功能可透過呼叫 pageAction.show
和 pageAction.hide
動態啟用及停用。
Mappy 範例擴充功能會掃描網頁是否有地址,並在彈出式視窗的靜態地圖上顯示它的位置。這項擴充功能須依賴網頁內容,因此無法宣告規則來預測哪些頁面具有關聯性。相反地,如果在網頁上找到地址,會呼叫 pageAction.show
來調色圖示,並表示該擴充功能可在該分頁上使用。
chrome.runtime.onMessage.addListener(function(req, sender) {
chrome.storage.local.set({'address': req.address})
chrome.pageAction.show(sender.tab.id);
chrome.pageAction.setTitle({tabId: sender.tab.id, title: req.address});
});
提供擴充功能圖示
擴充功能至少需要一個圖示來代表擴充功能。儘管 WebKit 支援任何格式 (包括 BMP、GIF、ICO 和 JPEG),也可以 PNG 格式提供圖示來呈現最佳視覺效果。
指定工具列圖示
工具列專用的圖示會在資訊清單的 browser_action
或 page_action
下方的 "default_icon"
欄位中註冊。建議您加入多種大小,以便配合 16 dip 的空間調整大小。建議大小至少為 16x16 和 32x32。
{
"name": "My Awesome page_action Extension",
...
"page_action": {
"default_icon": {
"16": "extension_toolbar_icon16.png",
"32": "extension_toolbar_icon32.png"
}
}
...
}
所有圖示都必須為正方形,否則可能會變形。如果未提供圖示,Chrome 會在工具列中新增一般圖示。
建立及註冊其他圖示
在工具列以外的地方使用時,請加入下列大小的圖示。
圖示大小 | 圖示使用 |
---|---|
16x16 | 擴充功能網頁上的網站小圖示 |
32x32 | Windows 電腦通常需要這個大小。提供此選項可避免尺寸變形 48x48 選項縮小。 |
48x48 | 會顯示在擴充功能管理頁面上 |
128x128 | 安裝時和 Chrome 線上應用程式商店中 |
在資訊清單的 "icons"
欄位下方註冊圖示。
{
"name": "My Awesome Extension",
...
"icons": {
"16": "extension_icon16.png",
"32": "extension_icon32.png",
"48": "extension_icon48.png",
"128": "extension_icon128.png"
}
...
}
其他 UI 功能
彈出式廣告
彈出式視窗是一種 HTML 檔案,會在使用者點選工具列圖示時,顯示在特殊視窗中。 彈出式視窗的運作方式與網頁非常類似,可包含樣式表和指令碼標記的連結,但不允許內嵌 JavaScript。
「Drink Water Event」彈出式視窗會顯示可用的計時器選項。使用者按一下其中一個提供的按鈕來設定鬧鐘。
<html>
<head>
<title>Water Popup</title>
</head>
<body>
<img src='./stay_hydrated.png' id='hydrateImage'>
<button id='sampleSecond' value='0.1'>Sample Second</button>
<button id='15min' value='15'>15 Minutes</button>
<button id='30min' value='30'>30 Minutes</button>
<button id='cancelAlarm'>Cancel Alarm</button>
<script src="popup.js"></script>
</body>
</html>
您可在資訊清單中註冊瀏覽器動作或網頁動作的彈出式視窗。
{
"name": "Drink Water Event",
...
"browser_action": {
"default_popup": "popup.html"
}
...
}
您也可以呼叫 browserAction.setPopup
或 pageAction.setPopup
,以動態方式設定彈出式視窗。
chrome.storage.local.get('signed_in', function(data) {
if (data.signed_in) {
chrome.browserAction.setPopup({popup: 'popup.html'});
} else {
chrome.browserAction.setPopup({popup: 'popup_sign_in.html'});
}
});
工具提示
在使用者將遊標懸停在瀏覽器圖示上時,使用工具提示提供簡短說明或操作說明。
請在資訊清單中的 "default_title"
欄位 browser_action
或 page_action
中註冊工具提示。
{
"name": "Tab Flipper",
...
"browser_action": {
"default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
}
...
}
您也可以呼叫 browserAction.setTitle
和 pageAction.setTitle
來設定或更新工具提示。
chrome.browserAction.onClicked.addListener(function(tab) {
chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});
特殊的語言代碼字串是透過國際化實作。在名為 _locales
的資料夾中建立目錄,儲存語言特定訊息,如下所示:
_locales/en/messages.json
_locales/es/messages.json
在各語言的 messages.json
中設定訊息格式。
{
"__MSG_tooltip__": {
"message": "Hello!",
"description": "Tooltip Greeting."
}
}
{
"__MSG_tooltip__": {
"message": "Hola!",
"description": "Tooltip Greeting."
}
}
請在工具提示欄位中填入訊息名稱,而非設定訊息,以啟用本地化功能。
{
"name": "Tab Flipper",
...
"browser_action": {
"default_title": "__MSG_tooltip__"
}
...
}
網址列
使用者可以透過網址列叫用擴充功能功能。在資訊清單中加入 "omnibox"
欄位並指定關鍵字。「Omnibox New Tab Search」範例擴充功能使用「nt」做為關鍵字。
{
"name": "Omnibox New Tab Search",\
...
"omnibox": { "keyword" : "nt" },
"default_icon": {
"16": "newtab_search16.png",
"32": "newtab_search32.png"
}
...
}
使用者在網址列中輸入「nt」時,系統會啟用擴充功能。如要向使用者告知這項資訊,系統會將提供的 16x16 圖示轉為灰階,然後加入擴充功能名稱旁邊的網址列中。
擴充功能會監聽 omnibox.onInputEntered
事件。觸發之後,擴充功能會開啟新分頁,其中含有搜尋使用者項目的 Google 搜尋。
chrome.omnibox.onInputEntered.addListener(function(text) {
// Encode user input for special characters , / ? : @ & = + $ #
var newURL = 'https://www.google.com/search?q=' + encodeURIComponent(text);
chrome.tabs.create({ url: newURL });
});
內容選單
透過在資訊清單中授予 "contextMenus"
權限,新增內容選單選項。
{
"name": "Global Google Search",
...
"permissions": [
"contextMenus",
"storage"
],
"icons": {
"16": "globalGoogle16.png",
"48": "globalGoogle48.png",
"128": "globalGoogle128.png"
}
...
}
16x16 圖示會顯示在新的選單項目旁邊。
在背景指令碼中呼叫 contextMenus.create
以建立內容選單。這項操作必須在 runtime.onInstalled
事件監聽器事件下完成。
chrome.runtime.onInstalled.addListener(function() {
for (let key of Object.keys(kLocales)) {
chrome.contextMenus.create({
id: key,
title: kLocales[key],
type: 'normal',
contexts: ['selection'],
});
}
});
const kLocales = {
'com.au': 'Australia',
'com.br': 'Brazil',
'ca': 'Canada',
'cn': 'China',
'fr': 'France',
'it': 'Italy',
'co.in': 'India',
'co.jp': 'Japan',
'com.ms': 'Mexico',
'ru': 'Russia',
'co.za': 'South Africa',
'co.uk': 'United Kingdom'
};
全域 Google 搜尋內容選單範例會從 locales.js 的清單建立多個選項。如果擴充功能包含多個內容選單,Google Chrome 會自動將其收合為單一父項選單。
指令
擴充功能可以定義特定指令,並將其繫結至按鍵組合。在 "commands"
欄位下方的資訊清單中註冊一或多個指令。
{
"name": "Tab Flipper",
...
"commands": {
"flip-tabs-forward": {
"suggested_key": {
"default": "Ctrl+Shift+Right",
"mac": "Command+Shift+Right"
},
"description": "Flip tabs forward"
},
"flip-tabs-backwards": {
"suggested_key": {
"default": "Ctrl+Shift+Left",
"mac": "Command+Shift+Left"
},
"description": "Flip tabs backwards"
}
}
...
}
指令可用來提供新的瀏覽器或替代瀏覽器快速鍵。Tab Flipper 範例擴充功能會監聽背景指令碼中的 commands.onCommand
事件,並定義每個註冊組合的功能。
chrome.commands.onCommand.addListener(function(command) {
chrome.tabs.query({currentWindow: true}, function(tabs) {
// Sort tabs according to their index in the window.
tabs.sort((a, b) => { return a.index < b.index; });
let activeIndex = tabs.findIndex((tab) => { return tab.active; });
let lastTab = tabs.length - 1;
let newIndex = -1;
if (command === 'flip-tabs-forward')
newIndex = activeIndex === 0 ? lastTab : activeIndex - 1;
else // 'flip-tabs-backwards'
newIndex = activeIndex === lastTab ? 0 : activeIndex + 1;
chrome.tabs.update(tabs[newIndex].id, {active: true, highlighted: true});
});
});
指令也可建立與其擴充功能搭配使用的按鍵繫結。Hello Extensions 範例提供開啟彈出式視窗的指令。
{
"name": "Hello Extensions",
"description" : "Base Level Extension",
"version": "1.0",
"browser_action": {
"default_popup": "hello.html",
"default_icon": "hello_extensions.png"
},
"manifest_version": 2,
"commands": {
"_execute_browser_action": {
"suggested_key": {
"default": "Ctrl+Shift+F",
"mac": "MacCtrl+Shift+F"
},
"description": "Opens hello.html"
}
}
}
由於擴充功能定義了 browser_action
,因此可以在指令中指定 "execute_browser_action"
,藉此開啟彈出式檔案,而不加入背景指令碼。如果您使用 page_action
,則可將其替換為 "execute_page_action"
。瀏覽器和擴充功能指令都可以在相同的擴充功能中使用。
覆寫頁面
擴充功能可以覆寫,並以自訂 HTML 檔案取代「歷史記錄」、「新分頁」或「書籤」網頁。與彈出式視窗一樣,它可包含特殊的邏輯和樣式,但不允許內嵌 JavaScript。單一擴充功能僅限覆寫三個網頁中的其中一個。
在資訊清單的 "chrome_url_overrides"
欄位下方註冊覆寫頁面。
{
"name": "Awesome Override Extension",
...
"chrome_url_overrides" : {
"newtab": "override_page.html"
},
...
}
覆寫這些頁面時,應將 "newtab"
欄位替換為 "bookmarks"
或 "history"
。
<html>
<head>
<title>New Tab</title>
</head>
<body>
<h1>Hello World</h1>
<script src="logic.js"></script>
</body>
</html>