Projektowanie interfejsu

Interfejs rozszerzenia powinien być funkcjonalny i minimalistyczny. Podobnie jak same rozszerzenia, interfejs powinien dostosowywać lub ulepszać proces przeglądania, nie odwracając od niego uwagi.

Z tego przewodnika dowiesz się, jakie funkcje interfejsu są wymagane, a jakie opcjonalne. Poznasz też sposoby i momenty implementowania różnych elementów interfejsu w rozszerzeniu.

Aktywowanie rozszerzenia na wszystkich stronach

Użyj browser_action, gdy funkcje rozszerzenia działają w większości sytuacji.

Rejestrowanie działania przeglądarki

Pole "browser_action" jest zarejestrowane w pliku manifestu.

{
  "name": "My Awesome browser_action Extension",
  ...
  "browser_action": {
    ...
  }
  ...
}

Zadeklarowanie "browser_action" powoduje, że ikona jest kolorowa, co oznacza, że rozszerzenie jest dostępne dla użytkowników.

Dodawanie plakietki

Plakietki to kolorowe banery z maksymalnie 4 znakami wyświetlane nad ikoną przeglądarki. Mogą być używane tylko przez rozszerzenia, które deklarują "browser_action" w pliku manifestu.

Używaj plakietek, aby wskazywać stan rozszerzenia. Przykładowe zdarzenie Drink Water Event wyświetla plakietkę z napisem "ON", aby pokazać użytkownikowi, że alarm został ustawiony, a gdy rozszerzenie jest nieaktywne, nie wyświetla nic.

Tekst plakietki ustawisz, wywołując chrome.browserAction.setBadgeText, a kolor banera – wywołując chrome.browserAction.setBadgeBackgroundColor .

chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});

Aktywowanie rozszerzenia na wybranych stronach

Użyj page_action, gdy funkcje rozszerzenia są dostępne tylko w określonych okolicznościach.

Deklarowanie działania strony

Pole "page_action" jest zarejestrowane w pliku manifestu.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    ...
  }
  ...
}

Zadeklarowanie "page_action" spowoduje, że ikona będzie kolorowa tylko wtedy, gdy rozszerzenie jest dostępne dla użytkowników. W przeciwnym razie będzie wyświetlana w skali szarości.

Określanie reguł aktywowania rozszerzenia

Określ reguły, kiedy rozszerzenie jest użyteczne, wywołując chrome.declarativeContent w ramach runtime.onInstalled odbiornika w skrypcie w tle. Przykładowe rozszerzenie Page action by URL sample ustawia warunek, że adres URL musi zawierać literę „g”. Jeśli warunek jest spełniony, rozszerzenie wywołuje 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 używające "page_action" mogą być aktywowane i dezaktywowane dynamicznie przez wywołanie pageAction.show i pageAction.hide.

Przykładowe rozszerzenie Mappy skanuje stronę internetową w poszukiwaniu adresu i wyświetla jego lokalizację na statycznej mapie w wyskakującym okienku. Ponieważ rozszerzenie jest zależne od treści strony, nie może deklarować reguł przewidujących, które strony będą odpowiednie. Jeśli na stronie zostanie znaleziony adres, rozszerzenie wywoła pageAction.show, aby pokolorować ikonę i zasygnalizować, że rozszerzenie jest użyteczne na tej karcie.

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});
});

Udostępnianie ikon rozszerzenia

Rozszerzenia wymagają co najmniej 1 ikony. Aby uzyskać najlepsze efekty wizualne, używaj ikon w formacie PNG, ale akceptowane są też inne formaty obsługiwane przez WebKit, w tym BMP, GIF, ICO i JPEG.

Wyznaczanie ikon paska narzędzi

Ikony paska narzędzi są rejestrowane w polu "default_icon" w sekcji browser_action lub page_action w pliku manifestu. Zalecamy używanie ikon w różnych rozmiarach, aby można je było skalować do rozmiaru 16 dip. Zalecamy używanie ikon o rozmiarach co najmniej 16 × 16 i 32 × 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 podasz żadnych ikon, Chrome doda do paska narzędzi ikonę ogólną.

Tworzenie i rejestrowanie dodatkowych ikon

Używaj dodatkowych ikon w tych rozmiarach poza paskiem narzędzi.

Zarejestruj ikony w manifeście 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 jest wyświetlany w specjalnym oknie, gdy użytkownik kliknie ikonę na pasku narzędzi. Wyskakujące okienko działa podobnie jak strona internetowa. Może zawierać linki do arkuszy stylów i tagów skryptów, ale nie zezwala na JavaScript wbudowany.

Wyskakujące okienko w przykładzie Drink Water Event wyświetla dostępne opcje timera. Użytkownicy ustawiają alarm, klikając jeden z podanych 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żna zarejestrować w pliku manifestu w sekcji działania przeglądarki lub działania strony.

{
  "name": "Drink Water Event",
  ...
  "browser_action": {
    "default_popup": "popup.html"
  }
  ...
}

Wyskakujące okienka można też ustawiać dynamicznie, wywołując 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żyj etykietki, aby wyświetlać krótkie opisy lub instrukcje, gdy użytkownik najedzie kursorem na ikonę przeglądarki.

Etykietki są rejestrowane w polu "default_title" w sekcji 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"
  }
...
}

Etykietki można też ustawiać lub aktualizować, wywołując browserAction.setTitle i pageAction.setTitle.

chrome.browserAction.onClicked.addListener(function(tab) {
  chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});

Specjalne ciągi znaków w różnych językach są implementowane za pomocą internacjonalizacji. Utwórz katalogi, w których będą przechowywane wiadomości w poszczególnych językach, w folderze o nazwie _locales, np.:

• _locales/en/messages.json
• _locales/es/messages.json

Sformatuj wiadomości w pliku messages.json każdego języka.

{
  "__MSG_tooltip__": {
      "message": "Hello!",
      "description": "Tooltip Greeting."
  }
}

{
  "__MSG_tooltip__": {
      "message": "Hola!",
      "description": "Tooltip Greeting."
  }
}

Aby włączyć lokalizację, w polu etykietki umieść nazwę wiadomości zamiast samej wiadomości.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "__MSG_tooltip__"
  }
...
}

Omnibox

Użytkownicy mogą wywoływać funkcje rozszerzenia za pomocą omniboksu. W manifeście umieść pole "omnibox" i wyznacz słowo kluczowe. Przykładowe rozszerzenie Omnibox New Tab Search 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"
  }
  ...
}

Gdy użytkownik wpisze „nt” w omniboksie, rozszerzenie zostanie aktywowane. Aby to zasygnalizować, rozszerzenie wyświetla podaną ikonę 16 × 16 w skali szarości i umieszcza ją w omniboksie obok nazwy rozszerzenia.

Rozszerzenie nasłuchuje zdarzenia omnibox.onInputEntered. Po jego wywołaniu rozszerzenie otwiera nową kartę z wyszukiwaniem w Google wpisanego przez użytkownika hasła.

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

Aby dodać nowe opcje menu kontekstowego, przyznaj uprawnienie "contextMenus" w manifeście.

{
  "name": "Global Google Search",
  ...
  "permissions": [
    "contextMenus",
    "storage"
  ],
  "icons": {
    "16": "globalGoogle16.png",
    "48": "globalGoogle48.png",
    "128": "globalGoogle128.png"
  }
  ...
}

Obok nowej pozycji menu wyświetla się ikona 16 × 16.

Utwórz menu kontekstowe, wywołując contextMenus.create w skrypcie w tle. Należy to zrobić w ramach runtime.onInstalled odbiornika zdarzenia.

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 Global Google Search tworzy wiele opcji z listy w locales.js . Gdy rozszerzenie zawiera więcej niż 1 menu kontekstowe, Google Chrome automatycznie zwija je w jedno menu nadrzędne.

Polecenia

Rozszerzenia mogą definiować konkretne polecenia i przypisywać je do kombinacji klawiszy. Zarejestruj co najmniej 1 polecenie w manifeście 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 udostępniania nowych lub alternatywnych skrótów przeglądarki. Przykładowe rozszerzenie Tab Flipper nasłuchuje zdarzenia commands.onCommand w skrypcie w tle i definiuje funkcje dla 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ązanie klawiszy, które działa specjalnie z danym rozszerzeniem. Przykład Hello Extensions zawiera polecenie otwierania wyskakującego okienka.

{
  "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"
    }
  }
}

Ponieważ rozszerzenie definiuje browser_action, może określić "execute_browser_action" w poleceniach, aby otworzyć plik wyskakującego okienka bez skryptu w tle . Jeśli używasz page_action, możesz zastąpić ją poleceniem "execute_page_action". W tym samym rozszerzeniu można używać zarówno poleceń przeglądarki, jak i rozszerzenia.

Zastępowanie stron

Rozszerzenie może zastąpić stronę internetową Historia, Nowa karta lub Zakładki niestandardowym plikiem HTML. Podobnie jak wyskakujące okienko, może zawierać specjalną logikę i styl, ale nie zezwala na JavaScript wbudowany. Pojedyncze rozszerzenie może zastąpić tylko 1 z 3 możliwych stron.

Zarejestruj stronę zastępczą w manifeście w polu "chrome_url_overrides".

{
  "name": "Awesome Override Extension",
  ...

  "chrome_url_overrides" : {
    "newtab": "override_page.html"
  },
  ...
}

Gdy zastępujesz te strony, pole "newtab" należy zastąpić polem "bookmarks" lub "history".

<html>
  <head>
  <title>New Tab</title>
  </head>
  <body>
    <h1>Hello World</h1>
  <script src="logic.js"></script>
  </body>
</html>