扩展程序界面应具有针对性且尽量简洁。与扩展程序本身一样,界面应自定义或增强浏览体验,而不会分散注意力。
本指南介绍了必需的和可选的界面功能。您可以用它来了解如何以及何时在扩展程序中实现不同的界面元素。
在所有网页上启用此扩展程序
如果扩展程序的功能在大多数情况下都能正常运行,请使用 browser_action。
注册浏览器操作
"browser_action"
字段已在清单中注册。
{
"name": "My Awesome browser_action Extension",
...
"browser_action": {
...
}
...
}
声明 "browser_action"
会使图标保持彩色,表明该扩展程序可供用户使用。
添加徽章
标记会显示一个彩色横幅,浏览器图标顶部最多包含四个字符。只有在其清单中声明 "browser_action"
的扩展程序才能使用它们。
使用标记来指示扩展程序的状态。Drink Water Event 示例会显示一个带有“开启”的标志,提示用户成功设置了闹钟,当扩展程序处于空闲状态时,系统不会显示任何内容。
通过调用 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 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"
}
...
}
其他界面功能
弹出式窗口
弹出式窗口是指当用户点击工具栏图标时,系统会在特殊窗口中显示的 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"
字段并指定关键字。多功能框新标签页搜索示例扩展程序使用“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>