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>