Interfejs rozszerzenia powinien być celowy i minimalny. Podobnie jak same rozszerzenia, interfejs użytkownika powinien dostosować lub ulepszyć przeglądanie, nie rozpraszając użytkownika.
W tym przewodniku omawiamy wymagane i opcjonalne funkcje interfejsu użytkownika. Dzięki niemu dowiesz się, jak i kiedy wdrażać różne elementy interfejsu w obrębie rozszerzenia.
Aktywuj rozszerzenie na wszystkich stronach
Użyj parametru browser_action, jeśli funkcje rozszerzenia działają w większości sytuacji.
Zarejestruj działanie przeglądarki
Pole "browser_action"
jest zarejestrowane w pliku manifestu.
{
"name": "My Awesome browser_action Extension",
...
"browser_action": {
...
}
...
}
Zadeklarowanie "browser_action"
zachowuje kolor ikony, co wskazuje, że rozszerzenie jest dostępne dla użytkowników.
Dodaj plakietkę
Plakietki mają kolorowy baner z maksymalnie 4 znakami nad ikoną przeglądarki. Można ich używać tylko przez rozszerzenia, które w pliku manifestu zadeklarują "browser_action"
.
Użyj plakietek, aby określić stan rozszerzenia. W próbce Drink Water Event jest wyświetlana plakietka z wartością „WŁ.”, która informuje użytkownika, że ustawił alarm. Gdy rozszerzenie jest nieaktywne, nic nie wyświetla.
Ustaw tekst plakietki, wywołując chrome.browserAction.setBadgeText
, i kolor banera, wywołując chrome.browserAction.setBadgeBackgroundColor
.
chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});
Aktywuj rozszerzenie na wybranych stronach
Użyj parametru page_action, jeśli funkcje rozszerzenia są dostępne tylko w określonych okolicznościach.
Zadeklaruj działanie na stronie
Pole "page_action"
jest zarejestrowane w pliku manifestu.
{
"name": "My Awesome page_action Extension",
...
"page_action": {
...
}
...
}
Zadeklarowanie atrybutu "page_action"
spowoduje kolorowanie ikony tylko wtedy, gdy rozszerzenie będzie dostępne dla użytkowników. W przeciwnym razie ikona będzie wyświetlana w skali szarości.
Definiowanie reguł aktywowania rozszerzenia
Zdefiniuj reguły użycia rozszerzenia, wywołując chrome.declarativeContent
w odbiorniku runtime.onInstalled
w skrypcie w tle. Przykładowe rozszerzenie Działanie strony według adresu URL ustawia warunek, że adres URL musi zawierać literę „g”. Jeśli warunek zostanie spełniony, rozszerzenie wywołuje metodę 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() ]
}
]);
});
});
Włączanie i wyłączanie rozszerzenia
Rozszerzenia korzystające z metody "page_action"
mogą aktywować i wyłączać dynamicznie, wywołując metodę pageAction.show
i pageAction.hide
.
Przykładowe rozszerzenie Mappy skanuje stronę internetową w poszukiwaniu adresu i wyświetla jej lokalizację na mapie statycznej w wyskakującym okienku. Rozszerzenie jest zależne od treści strony, więc nie można zadeklarować reguł określających, które strony będą trafne. Jeśli jednak adres zostanie znaleziony na stronie, wywołuje polecenie pageAction.show
, aby kolorować ikonę i sygnalizować, że na danej karcie można użyć rozszerzenia.
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});
});
Dodawanie ikon rozszerzeń
Rozszerzenia wymagają co najmniej 1 ikony, która je reprezentuje. Używaj ikon w formacie PNG, aby uzyskać najlepszy efekt wizualny. Akceptujemy jednak wszystkie formaty obsługiwane przez WebKit, w tym BMP, GIF, ICO i JPEG.
Wyznaczanie ikon na pasku narzędzi
Ikony paska narzędzi są rejestrowane w polu "default_icon"
w pliku browser_action
lub page_action
w pliku manifestu. Zaleca się uwzględnianie wielu rozmiarów,
aby mieściły się w 16-dipowej przestrzeni. Zalecane są co najmniej 16 x 16 i 32 x 32 piksele.
{
"name": "My Awesome page_action Extension",
...
"page_action": {
"default_icon": {
"16": "extension_toolbar_icon16.png",
"32": "extension_toolbar_icon32.png"
}
}
...
}
Wszystkie ikony powinny być kwadratowe, w przeciwnym razie mogą być zniekształcone. Jeśli nie zostaną dodane żadne ikony, Chrome doda do paska narzędzi standardową ikonę.
Utwórz i zarejestruj dodatkowe ikony
Dołącz dodatkowe ikony w następujących rozmiarach do użytku poza paskiem narzędzi.
Rozmiar ikony | Użycie ikony |
---|---|
16 × 16 | favikonę na stronach rozszerzenia |
32 × 32 | Taki rozmiar często wymagają komputerów z systemem Windows. Dzięki tej opcji zniekształcenia rozmiaru 48 x 48 nie zostaną zmniejszone. |
48 × 48 | wyświetla się na stronie zarządzania rozszerzeniami. |
128 × 128 | wyświetla się podczas instalacji i w Chrome Web Store |
Zarejestruj ikony w pliku manifestu w polu "icons"
.
{
"name": "My Awesome Extension",
...
"icons": {
"16": "extension_icon16.png",
"32": "extension_icon32.png",
"48": "extension_icon48.png",
"128": "extension_icon128.png"
}
...
}
Dodatkowe funkcje interfejsu
Wyskakujące okienko
Wyskakujące okienko to plik HTML, który wyświetla się w specjalnym oknie, gdy użytkownik kliknie ikonę na pasku narzędzi. Wyskakujące okienko działa bardzo podobnie do strony internetowej: może zawierać linki do arkuszy stylów i tagów skryptu, ale nie zezwala na wbudowany kod JavaScript.
Przykładowe wyskakujące okienko Drink Water Event (Zdarzenie na wodę) zawiera dostępne opcje licznika czasu. Użytkownicy ustawiają alarm, klikając jeden z dostępnych przycisków.
<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>
Wyskakujące okienko możesz zarejestrować w pliku manifestu jako działanie przeglądarki lub strona.
{
"name": "Drink Water Event",
...
"browser_action": {
"default_popup": "popup.html"
}
...
}
Wyskakujące okienka można też konfigurować dynamicznie, wywołując metodę browserAction.setPopup
lub 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'});
}
});
Etykietka
Używaj etykietki, aby po najechaniu kursorem na ikonę przeglądarki podawać użytkownikom krótkie opisy lub instrukcje.
Etykietki są rejestrowane w polu "default_title"
browser_action
lub page_action
w pliku manifestu.
{
"name": "Tab Flipper",
...
"browser_action": {
"default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
}
...
}
Etykiety można też ustawiać i aktualizować, wywołując metodę browserAction.setTitle
i pageAction.setTitle
.
chrome.browserAction.onClicked.addListener(function(tab) {
chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});
Wyspecjalizowane ciągi znaków regionalnych są implementowane za pomocą metody internacjonalizacji. Utwórz katalogi w folderze _locales
, w którym będą umieszczone wiadomości o określonym języku. Na przykład:
_locales/en/messages.json
_locales/es/messages.json
Formatuj wiadomości w sekcji messages.json
każdego języka.
{
"__MSG_tooltip__": {
"message": "Hello!",
"description": "Tooltip Greeting."
}
}
{
"__MSG_tooltip__": {
"message": "Hola!",
"description": "Tooltip Greeting."
}
}
Aby włączyć lokalizację, zamiast wiadomości podaj nazwę wiadomości w polu etykietki.
{
"name": "Tab Flipper",
...
"browser_action": {
"default_title": "__MSG_tooltip__"
}
...
}
Omnibox
Użytkownicy mogą wywoływać funkcję rozszerzenia za pomocą omniboksu. Dodaj do pliku manifestu pole "omnibox"
i wyznacz słowo kluczowe. Przykładowe rozszerzenie Wyszukiwanie nowej karty w omniboksie używa „nt” jako słowa kluczowego.
{
"name": "Omnibox New Tab Search",\
...
"omnibox": { "keyword" : "nt" },
"default_icon": {
"16": "newtab_search16.png",
"32": "newtab_search32.png"
}
...
}
Rozszerzenie jest aktywowane, gdy użytkownik wpisze w omniboksie „nt”. Aby zasygnalizować użytkownikowi, że ikona jest szara, ikona 16 x 16 jest skalowana na szaro i umieszczana w omniboksie obok nazwy rozszerzenia.
Rozszerzenie nasłuchuje zdarzenia omnibox.onInputEntered
. Po wywołaniu rozszerzenie otwiera nową kartę z wyszukiwaniem wpisu użytkownika w 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 });
});
Menu kontekstowe
Dodaj nowe opcje menu kontekstowego, przyznając uprawnienie "contextMenus"
w pliku manifestu.
{
"name": "Global Google Search",
...
"permissions": [
"contextMenus",
"storage"
],
"icons": {
"16": "globalGoogle16.png",
"48": "globalGoogle48.png",
"128": "globalGoogle128.png"
}
...
}
Obok nowego wpisu w menu wyświetlana jest ikona 16 x 16.
Utwórz menu kontekstowe, wywołując contextMenus.create
w skrypcie w tle. Należy to zrobić za pomocą zdarzenia detektora 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'
};
Przykład menu kontekstowego wyszukiwarki Google tworzy wiele opcji z listy w pliku locales.js . Gdy rozszerzenie zawiera więcej niż jedno menu kontekstowe, Google Chrome automatycznie zwija je w jedno menu nadrzędne.
Polecenia
Rozszerzenia mogą definiować określone polecenia i wiązać je z kombinacją klawiszy. Zarejestruj co najmniej 1 polecenie w pliku manifestu w polu "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"
}
}
...
}
Polecenia mogą służyć do określania nowych lub alternatywnych skrótów przeglądarki. Rozszerzenie przykładowe Tab Flipper nasłuchuje zdarzenia commands.onCommand
w skrypcie w tle i określa funkcje w przypadku każdej zarejestrowanej kombinacji.
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});
});
});
Polecenia mogą też tworzyć powiązania klawiszy, które działają specjalnie z jego rozszerzeniem. Przykładowe rozszerzenia Hello zawierają polecenie otwierające wyskakujące okienko.
{
"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"
}
}
}
Rozszerzenie definiuje browser_action
, dlatego w poleceniach, które otwierają wyskakujące okienko, można podać "execute_browser_action"
bez użycia skryptu w tle. Jeśli używasz page_action
, możesz go zastąpić wartością "execute_page_action"
. W ramach tego samego rozszerzenia można używać zarówno poleceń przeglądarki, jak i rozszerzeń.
Zastąp strony
Rozszerzenie może zastępować strony internetowe Historia, Nowa karta lub Zakładki własnym plikiem HTML. Podobnie jak wyskakujące okienko może zawierać specjalistyczną logikę i styl, ale nie zezwala na wbudowany kod JavaScript. Jedno rozszerzenie może zastąpić tylko jedną z trzech możliwych stron.
Zarejestruj stronę zastąpienia w pliku manifestu pod polem "chrome_url_overrides"
.
{
"name": "Awesome Override Extension",
...
"chrome_url_overrides" : {
"newtab": "override_page.html"
},
...
}
Podczas zastępowania tych stron pole "newtab"
należy zastąpić wartością "bookmarks"
lub "history"
.
<html>
<head>
<title>New Tab</title>
</head>
<body>
<h1>Hello World</h1>
<script src="logic.js"></script>
</body>
</html>