понедельник, 17 февраля 2014 г.

Browser Actions

Используется для того чтобы добавить иконку на главную панель инструментов браузера, справа от адресной строки. Может иметь всплывающую подсказку, бэджик и всплывающее окно.

Объявляется в манифесте следующим образом:

"browser_action": { 
"default_icon": {
"19": "images/icon19.png",
"38": "images/icon38.png" },
"default_title": "Google Mail",
"default_popup": "popup.html"
}

1


Вот это все расширения с browser action. При нажатии на иконку расширения под ней открывается всплывающее окно.


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


Иконка


Можно использовать один размер, и указывать ее в старом стиле:

"default_icon": "images/icon19.png"  

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


Можно использовать форматы BMP, PNG, JPEG, GIF, ICO. Для несжатых расширений картинки должны быть в формате PNG.



Интересный пассаж. Т.е. при отладке используйте PNG, а потом, при релизе, из каких-то непонятных соображений можете поменять картинки на другие.


Машина может быть любого цвета, если она черная(с)


Теоретически, браузер подбирает картинку с наиболее подходящим размером в зависимости от разрешения экрана, фактически сейчас поддерживаются два размера – 19 и 38


Кроме использования статической картинки, иконку можно сформировать динамически через элемент canvas. Это имеет смысл если вы собираетесь ее анимировать. Для этого служит метод setIcon.


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


Задается параметром default_title в манифесте или вызовом метода setTitle.


Бэдж (badge)


image


Бэдж, это небольшой текст, который накладывается на иконку расширения. Как можно догадаться, много туда просто не поместится, размер бэджа не более 4ех символов. Поэтому если вы выводите число, как в данном примере, то уместно округлять и применять сокращения. Например 10К вместо 10167.


Формируется динамически, в манифесте отсутствует. Можно задать текст бэджа методом  setBadgeText и его цвет, методом setBadgeBackgroundColor.



Всплывающее окно (popup)


Появляется когда пользователь кликает по иконке расширения. Может содержать произвольный HTML код и автоматически подгоняет свой размер под содержимое. Задается параметром default_popup в манифесте, или вызовом метода setPopup.


Советы



  • Используйте browser actions для добавления возможностей, которые реально нужны на большей части страниц
  • Если это не так, используйте page actions.
  • Не поленитесь сделать большие, красивые иконки. Пользователь не любит когда у него перед глазами, на панели инструментов, торчат унылые какашки.
  • Не пытайтесь делать иконки в той же цветовой гамме, что и родные иконки браузера – их внешний вид все равно зависит от темы и хрен вы угадаете.
  • Используйте прозрачный фон, тогда ваши иконки будут выглядеть хорошо в любой теме (если вы не подгадаете с основным цветом под цвет темы. Тогда они будут выглядеть ужасно)
  • Не злоупотребляйте анимацией. Это раздражает

Примеры


Вы можете найти их тут: examples/api/browserAction. Или тут: Samples.

Справочник по chrome.browserAction


Типы



  • ColorArray массив целых чисел
  • ImageDataType картинка. Должен быть объектом ImageData (например, из элемента canvas).

Методы


setTitle


chrome.browserAction.setTitle(object details) 


Устанавливает текст, который будет показываться во всплывающей подсказке к иконке расширения.


Параметры:


details ( object )


Свойства:

  • title ( string ) текст подсказки
  • tabId ( optional integer ) задает конкретную вкладку для которой изменится подсказка. Автоматически сбрасывается, когда вкладка закрывается

getTitle


chrome.browserAction.getTitle(object details, function callback)


Получает подсказку, общую, или для указанной вкладки. Зачем-то ее сделали асинхронной.


Параметры:


details ( object )


Свойства:

  • tabId ( optional integer ) задает вкладку. Если не указан, возвращается общая подсказка

callback ( function ) задает функцию, которая вызывается для получения результата. Функция должна принимать строковый параметр: function(string result) {...};


setIcon


chrome.browserAction.setIcon(object details, function callback)


Устанавливает новую иконку. Иконка м.б. указана как путь к файлу, либо как объект ImageData, либо как словарь тех или других. Словарь имеет тот же смысл что и в манифесте – задается несколько вариантов картинки для разных разрешений экрана


Параметры:


details ( object )


Свойства:

  • imageData ( optional ImageDataType or object ) ImageData или словарь  {размер -> ImageData}
  • path ( optional string or object ) путь к файлу с картинкой или словарь  {размер -> путь}
  • tabId ( optional integer ) задает вкладку на которой меняется иконка. Автоматически сбрасывается когда она закрывается.

callback ( optional function ) функция вида function() {...}, которая вызывается после смены иконки. Сложно сказать зачем это надо, можно ли вызвать новую смену иконки раньше чем отработала предыдущая и что из этого получится.


setPopup


chrome.browserAction.setPopup(object details)


Устанавливает html файл, который будет открываться как всплывающее окно, когда пользователь кликнет по иконке.


Параметры:


details ( object )


Свойства:

  • tabId ( optional integer ) можно задать разные попапы для разных вкладок
  • popup ( string ) путь к файлу. Пустая строка – значит нет всплывающего окна.

getPopup


chrome.browserAction.getPopup(object details, function callback)


Возвращает путь к файлу всплывающего окна.


Параметры:


details ( object )


Свойства:

  • tabId ( optional integer ) можно получить попап для указанной вкладки, или общий, если параметр не задан 

callback ( function ) функция вида function(string result) {...} для получения результата


setBadgeText


chrome.browserAction.setBadgeText(object details)


Устанавливает текст бэджа – общий, или для указанной вкладки


Параметры:


details ( object )


Свойства:

  • text ( string ) Текст бэджа. Размер текста м.б. любым, но только 4 символа поместятся.
  • tabId ( optional integer ) задает вкладку.

getBadgeText


chrome.browserAction.getBadgeText(object details, function callback)


Возвращает тест бэджа.


Параметры:


details ( object )


Свойства:

  • tabId ( optional integer ) задает вкладку.  

callback ( function ) функция вида function(string result) {...};



setBadgeBackgroundColor


chrome.browserAction.setBadgeBackgroundColor(object details)


Устанавливает цвет бэджа


Параметры:


details ( object )


Свойства:

  • color ( string or ColorArray ) массив из четырех целых чисел в диапазоне 0-255, задающих цвет по модели RGBA. Либо строка со значением в формате, принятом в CSS
  • tabId ( optional integer ) задает вкладку.

getBadgeBackgroundColor


chrome.browserAction.getBadgeBackgroundColor(object details, function callback)


Возвращает цвет бэджа


Параметры:


details ( object )


Свойства:

  • tabId ( optional integer ) задает вкладку.  

callback ( function ) функция вида function(ColorArray result) {...}


enable


chrome.browserAction.enable(integer tabId)


Разрешает browser action для вкладки. По умолчанию оно и так разрешено.


Параметры:

tabId ( integer ) задает вкладку

disable


chrome.browserAction.disable(integer tabId)


Запрешает browser action для вкладки.


Параметры:

tabId ( integer ) задает вкладку

События


onClicked


Возникает, когда пользователь кликает по иконке расширения. Но только в том случае, если не назначено всплывающее окно.


addListener


Метод для добавления своего обработчика


chrome.browserAction.onClicked.addListener(function callback)


Параметры

callback ( function ) задает функцию вида function(tabs.Tab tab) {...}, т.е. мы получаем идентификатор текущей вкладки

Вопросы для самостоятельного размышления


А…э…так то, дружок (с)



  1. Если задать что либо (иконку, бэдж, всплывающее окно, подсказку) для конкретной вкладки, а потом вызвать тот же метод без указания конкретной вкладки? Изменится ли значение и на ней тоже, или к ней останется привязанным индивидуальное значение, которое будет перекрывать общее?
  2. Метод disable – делает иконку неактивной, или убирает ее с панели инструментов?

Советы


Я не рекомендую использовать методы getXXX без веской причины. Вы должны и так знать, что вы там устанавливали и логика вашего расширения должна основываться на внутренней модели. Доверять можно только своим данным и своему коду. Опять же, асинхронные методы усложняют логику и открывают потенциальную возможность логических гонок и стало быть – трудноуловимых глюков.

Комментариев нет:

Отправить комментарий