Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

設計使用者介面

擴充功能的使用者介面應簡潔明瞭，與擴充功能本身一樣，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});
});

提供擴充功能圖示

擴充功能至少需要一個代表該功能的圖示。請提供 PNG 格式的圖示，以獲得最佳視覺效果，但系統也接受 WebKit 支援的任何格式，包括 BMP、GIF、ICO 和 JPEG。

指定工具列圖示

工具列專屬圖示會註冊在資訊清單的 browser_action 或 page_action 下方的 "default_icon" 欄位中。建議加入多個尺寸，以便在 16 dp 空間中縮放。建議至少使用 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。

「喝水事件」範例彈出式視窗會顯示可用的計時器選項。使用者點選其中一個按鈕即可設定鬧鐘。

彈出式視窗範例螢幕截圖

<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" 欄位，並指定關鍵字。網址列新分頁搜尋範例擴充功能使用「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'
};

「Global 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>