вторник, 18 февраля 2014 г.

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

Кратко: chrome.contextMenus API позволяет добавлять элементы в контекстное меню. Можно выбрать для каких типов объектов эти элементы будут показываться, например картинки, гиперссылки или страница целиком. А также на каких сайтах. Для использования этой возможности в манифесте должно быть прописано разрешение.

Использование

Созданные вашим расширением пункты контекстного меню могут быть показаны в любом документе. Будь то веб-страница, локальный документ (file://) или встроенная страница браузера (chrome://). Это можно изменить с помощью поля documentUrlPatterns при вызове метода create() или update(). Можно создавать сколько угодно контекстных меню, но если активно более чем одно, браузер автоматически объединяет их вместе.

Манифест

Чтобы пользоваться контекстными меню, необходимо

  • указать contextMenus в правах доступа
  • включить в проект иконку размером 16х16
{
"name": "My extension",
...
"permissions": [
"contextMenus"
],
"icons": {
"16": "icon-bitty.png",
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}

Примеры использования можно найти тут


Справочник по API


Типы


OnClickData – информация, которая передается при активации элемента меню


Свойства



  • menuItemId ( integer or string ) идентификатор элемента меню

  • parentMenuItemId ( optional integer or string ) идентификатор самого меню

  • mediaType ( optional string ) 'image', 'video', или 'audio' если меню было вызвано для такого типа элементов

  • linkUrl ( optional string ) URL ссылки, если меню было вызвано для ссылки

  • srcUrl ( optional string ) URL из поля src (например для картинки)

  • pageUrl ( optional string ) URL страницы. Не устанавливается если контекстное меню вызывалось без текущей с страницы (не совсем понял как это, но так и быть, верю разработчикам на слово)

  • frameUrl ( optional string ) URL фрейма, если меню вызвано для фрейма

  • selectionText ( optional string ) текст выделенного фрагмента, если меню вызывалось для выделения.

  • editable ( boolean ) флаг, который показывает что элемент может редактироваться, например input, textarea и т.д.

  • wasChecked ( optional boolean ) показывает состояние чекбокса или радиокнопки перед тем как для вызвали контекстное меню

  • checked ( optional boolean ) показывает состояние чекбокса или радиокнопки, которое должно быть после того как вызвали контекстное меню.

Последние два пункта необходимо пояснить – пункт контекстного меню может быть чекбоксом или радиокнопкой. Именно он имеется в виду, а не элемент на странице. см. метод create


Методы


create


integer or string chrome.contextMenus.create(object createProperties, function callback)
Создает новый элемент контекстного меню.


Параметры


createProperties ( object )


Свойства



  • type ( optional enum of "normal", "checkbox", "radio", or "separator" ) тип элемента меню. По умолчанию normal

  • id ( optional string ) уникальный, в пределах расширения, ID элемента. Обязательно для страниц типа event.

  • title ( optional string ) текст отображаемый в элементе. Не нужен только для разделителя. Если вызывается для выделения можно использовать %s для включения выделенного текста. Например, "Перевести '%s' “ – в контекстное меню будет подставлен кусок текста, который предполагается перевести. (Нужно будет попробовать выделить страницу текста и посмотреть что вставится в меню.)

  • checked ( optional boolean ) Начальное значение чекбокса или радиокнопки. True для выбранного, false для невыбранного.

  • contexts ( optional массив значений из набора "all", "page", "frame", "selection", "link", "editable", "image", "video", "audio", или "launcher" ) список ситуаций в которых будет показываться создаваемый пункт контекстного меню. По умолчанию “page”, т.е. для любого элемента страницы ,куда ни ткни. “all” = все варианты кроме “launcher”. (Чем это отличается от page?) “launcher” – поддерживается только для приложений и используется чтобы добавить пункт в  контекстное меню на страницу/панель запуска приложений. Имеет различные ограничения в зависимости от платформы

  • onclick ( optional function ) функция, которая вызывается когда пользователь кликнул на этот элемент контекстного меню. Не используется для страниц типа “event” вместо этого такая страница должна зарегистрировать обработчик chrome.contextMenus.onClicked. Напомню – это фоновая страница, которая не загружена постоянно, а создается только при необходимости (при возникновении события) Функция должна иметь два параметра:


    • info ( OnClickData ) информация о активированном элементе меню и где он был активирован

    • tab ( tabs.Tab ) вкладка на которой это произошло (можно было включить это в OnClickData )

  • parentId ( optional integer or string ) идентификатор родительского элемента, если данный элемент является потомком ранее добавленного.

  • documentUrlPatterns ( optional array of string ) маска(и) URL страницы или фрейма. Элемент будет в меню только для страниц(фреймов) удовлетворяющих условию см. описание паттернов.

  • targetUrlPatterns ( optional array of string ) маска(и) URL атрибута src тэга img/audio/video или атрибута href ссылки.

  • enabled ( optional boolean ) по умолчанию true – разрешает или запрещает этот элемент меню

callback ( optional function ) функция вида function() {...}. Вызывается после того как элемент меню был создан. Если возникли какие-то проблемы, chrome.runtime.lastError будет содержать подробности


update


chrome.contextMenus.update(integer or string id, object updateProperties, function callback)
Обновляет ранее созданный элемент контекстного меню


Параметры


id ( integer or string ) идентификатор обновляемого элемента


updateProperties ( object ) новый набор свойств элемента – все тоже самое что для метода create. Нельзя только в качестве родительского элемента указывать собственный id, или id своих потомков (при создании это естественно не получится)callback ( optional function ) тоже что для create


remove


chrome.contextMenus.remove(integer or string menuItemId, function callback)
Удаляет элемент из контекстного меню.


Параметры


menuItemId ( integer or string ) идентификатор элемента
callback ( optional function ) функция вида function() {...}, вызывается когда элемент был удален


removeAll


chrome.contextMenus.removeAll(function callback)
Удаляет все определенные расширением элементы контекстного меню.


Параметры


callback ( optional function ) функция вида function() {...}, вызывается когда элементы были удалены


События


onClicked


Возникает когда пользователь выбрал элемент контекстного меню


addListener


Метод, добавляющий обработчик события


chrome.contextMenus.onClicked.addListener(function callback)
Параметры


callback ( function ) функция вида function(OnClickData info, tabs.Tab tab) {...}, вызывается при возникновении события



  • info ( OnClickData ) информация о событии

  • tab ( optional tabs.Tab ) вкладка где оно произошло

Примечательно что обработчик назначается не элементу, а является общим для всех элементов. Если у вас несколько элементов контекстного меню, то разделяются они уже внутри обработчика.

1 комментарий: