Проектирование пользовательского интерфейса

Пользовательский интерфейс расширения должен быть функциональным и минималистичным. Как и сами расширения, интерфейс должен настраивать или улучшать процесс просмотра, не отвлекая от него.

This guide explores required and optional user interface features. Use it to understand how and when to implement different UI elements within an extension.

Активируйте расширение на всех страницах.

Используйте browser_action , когда функции расширения работают в большинстве ситуаций.

Зарегистрировать действие браузера

Поле "browser_action" регистрируется в манифесте.

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

Объявление параметра "browser_action" сохраняет цвет значка, указывая на то, что расширение доступно пользователям.

Добавить значок

Badges display a colored banner with up to four characters on top of the browser icon. They can only be used by extensions that declare "browser_action" in their manifest.

Используйте значки для индикации состояния расширения. В примере « Событие питья воды » отображается значок со словом «ВКЛ», показывающий пользователю, что будильник был успешно установлен, и ничего не отображается, когда расширение находится в режиме ожидания.

Задайте текст значка, вызвав метод 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" приведет к изменению цвета значка только тогда, когда расширение будет доступно пользователям; в противном случае он будет отображаться в оттенках серого.

Определите правила активации расширения.

Определите правила использования расширения, вызвав метод chrome.declarativeContent в обработчике runtime.onInstalled в фоновом скрипте . Пример расширения « Действия со страницей по URL» устанавливает условие, согласно которому URL-адрес должен содержать букву «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() ]
      }
    ]);
  });
});

Включить или отключить расширение

Extensions using "page_action" can activate and disable dynamically by calling pageAction.show and 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.

Укажите значки на панели инструментов

Значки, специфичные для панели инструментов, регистрируются в поле "default_icon" в разделе browser_action или page_action в манифесте. Рекомендуется использовать несколько размеров для масштабирования под пространство в 16 ячеек. Минимальные рекомендуемые размеры — 16x16 и 32x32.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    "default_icon": {
      "16": "extension_toolbar_icon16.png",
      "32": "extension_toolbar_icon32.png"
    }
  }
  ...
}

Все значки должны быть квадратными, иначе они могут быть искажены. Если значки не указаны, Chrome добавит на панель инструментов стандартный значок.

Создавайте и регистрируйте дополнительные значки.

Добавьте дополнительные значки следующих размеров для использования вне панели инструментов.

Register icons in the manifest under the "icons" field.

{
  "name": "My Awesome Extension",
  ...
  "icons": {
    "16": "extension_icon16.png",
    "32": "extension_icon32.png",
    "48": "extension_icon48.png",
    "128": "extension_icon128.png"
  }
  ...
}

Дополнительные функции пользовательского интерфейса

Неожиданно возникнуть

Всплывающее окно — это HTML-файл, который отображается в специальном окне при щелчке пользователя по значку на панели инструментов. Всплывающее окно работает очень похоже на веб-страницу; оно может содержать ссылки на таблицы стилей и теги <script>, но не допускает встраивания 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>

The popup can be registered in the manifest, under browser action or page action.

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

Popups can also be set dynamically by calling browserAction.setPopup or 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'});
  }
});

Всплывающая подсказка

Use a tooltip to give short descriptions or instructions to users when hovering over the browser icon.

Всплывающие подсказки регистрируются в поле "default_title" в параметрах browser_action или page_action манифеста.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
  }
...
}

Tooltips can also be set or updated by calling browserAction.setTitle and 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."
  }
}

Include the name of the message in the tooltip field instead of the message to enable localization.

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

Омнибокс

Пользователи могут вызывать функциональность расширения через адресную строку . Добавьте поле "omnibox" в манифест и укажите ключевое слово. В примере расширения Omnibox New Tab Search в качестве ключевого слова используется "nt".

{
  "name": "Omnibox New Tab Search",\
  ...
  "omnibox": { "keyword" : "nt" },
  "default_icon": {
    "16": "newtab_search16.png",
    "32": "newtab_search32.png"
  }
  ...
}

Когда пользователь вводит "nt" в адресную строку, расширение активируется. Чтобы сообщить об этом пользователю, предоставленная иконка размером 16x16 пикселей отображается в оттенках серого и добавляется в адресную строку рядом с названием расширения.

The extension listens to the omnibox.onInputEntered event. After it's triggered, the extension opens a new tab containing a Google search for the user's entry.

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

Контекстное меню

Add new context menu options by granting the "contextMenus" permission in the manifest.

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

Значок 16x16 отображается рядом с новым пунктом меню.

Create a context menu by calling contextMenus.create in the background script . This should be done under the runtime.onInstalled listener event.

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 автоматически сворачивает их в одно родительское меню.

Команды

Extensions can define specific commands and bind them to a key combination. Register one or more commands in the manifest under the "commands" field.

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

Commands can also create a key binding that works specially with its extension. The Hello Extensions example gives a command to open the popup.

{
  "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. Одно расширение может переопределять только одну из трех возможных страниц.

Register an override page in the manifest under the "chrome_url_overrides" field.

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

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

The "newtab" field should be replaced with "bookmarks" or "history" when overriding those pages.

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