chrome.contextMenu

Описание

Используйте API chrome.contextMenus для добавления пунктов в контекстное меню Google Chrome. Вы можете выбрать, к каким типам объектов будут применяться дополнения в контекстном меню, например к изображениям, гиперссылкам и страницам.

Разрешения

contextMenus

Для использования API необходимо указать разрешение "contextMenus" в манифесте расширения. Также необходимо указать значок размером 16x16 пикселей для отображения рядом с пунктом меню. Например:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

Концепции и использование

Пункты контекстного меню могут отображаться в любом документе (или фрейме внутри документа), даже в тех, где URL-адреса имеют вид file:// или chrome://. Чтобы управлять документами, в которых могут отображаться ваши пункты, укажите поле documentUrlPatterns при вызове методов create() или update() .

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

Примеры

Чтобы опробовать этот API, установите пример API contextMenus из репозитория chrome-extension-samples .

Типы

ContextType

Хром 44+

Различные контексты, в которых может отображаться меню. Указание значения «все» эквивалентно комбинации всех других контекстов, за исключением «панели запуска». Контекст «панель запуска» поддерживается только приложениями и используется для добавления пунктов меню в контекстное меню, которое появляется при нажатии на значок приложения на панели запуска/панели задач/в доке и т. д. Различные платформы могут накладывать ограничения на поддерживаемые элементы контекстного меню панели запуска.

Перечисление

"все"

"страница"

"рамка"

"выбор"

"связь"

"редактируемый"

"изображение"

"видео"

"аудио"

"пусковая установка"

"browser_action"

"page_action"

"действие"

CreateProperties

Хром 123+

Свойства нового пункта контекстного меню.

Характеристики

  • проверено

    логическое необязательное

    Начальное состояние флажка или переключателя: true — выбрано, false — не выбрано. В данной группе одновременно может быть выбран только один переключатель.

  • контексты

    [ ContextType , ... ContextType []] необязательно

    Список контекстов, в которых будет отображаться этот пункт меню. По умолчанию ['page'] .

  • documentUrlPatterns

    строка[] необязательная

    Ограничивает применение элемента только к документам или фреймам, URL-адрес которых соответствует одному из заданных шаблонов. Подробнее о форматах шаблонов см. в разделе «Шаблоны соответствия» .

  • включено

    логическое необязательное

    Включен или отключен этот пункт контекстного меню. Значение по умолчанию — true .

  • идентификатор

    строка необязательная

    Уникальный идентификатор для этого элемента. Обязательно для страниц событий. Не может совпадать с другим идентификатором этого расширения.

  • parentId

    строка | число необязательно

    Идентификатор родительского пункта меню; это делает пункт дочерним по отношению к ранее добавленному пункту.

  • targetUrlPatterns

    строка[] необязательная

    Аналогично documentUrlPatterns , фильтры основаны на атрибуте src тегов img , audio и video , а также на атрибуте href a .

  • заголовок

    строка необязательная

    Текст, отображаемый в элементе; это обязательное поле, если только type не является separator . Если контекст — selection , используйте %s в строке для отображения выделенного текста. Например, если значение этого параметра — «Перевести '%s' на Pig Latin», и пользователь выбирает слово «cool», пункт контекстного меню для выбранного элемента — «Перевести 'cool' на Pig Latin».

  • тип

    ItemType необязательный

    Тип пункта меню. По умолчанию — normal .

  • видимый

    логическое необязательное

    Виден ли пункт в меню.

  • по клику

    необязательный

    Функция, которая вызывается при щелчке по пункту меню. Она недоступна внутри сервис-воркера; вместо этого следует зарегистрировать прослушиватель для contextMenus.onClicked .

    Функция onclick выглядит так: 

    (info: OnClickData, tab: Tab) => {...}

    • информация

      OnClickData

      Информация о нажатом элементе и контексте, в котором произошел щелчок.

    • вкладка

      Вкладка

      Информация о вкладке, на которой был выполнен клик. Этот параметр отсутствует для приложений платформы.

ItemType

Хром 44+

Тип пункта меню.

Перечисление

"нормальный"

"флажок"

"радио"

"разделитель"

OnClickData

Информация, отправляемая при щелчке по пункту контекстного меню.

Характеристики

  • проверено

    логическое необязательное

    Флаг, указывающий состояние флажка или переключателя после щелчка по нему.

  • редактируемый

    булев

    Флаг, указывающий, доступен ли элемент для редактирования (ввод текста, текстовая область и т. д.).

  • frameId

    номер необязательно

    Хром 51+

    Идентификатор фрейма элемента, в котором был выполнен щелчок по контекстному меню, если он находился во фрейме.

  • frameUrl

    строка необязательная

    URL-адрес фрейма элемента, в котором был выполнен щелчок по контекстному меню, если он находился во фрейме.

  • ссылкаUrl

    строка необязательная

    Если элемент является ссылкой, то URL-адрес, на который она указывает.

  • mediaType

    строка необязательная

    Одно из «изображение», «видео» или «аудио», если контекстное меню было активировано на одном из этих типов элементов.

  • menuItemId

    строка | число

    Идентификатор пункта меню, на который был нажат клик.

  • pageUrl

    строка необязательная

    URL-адрес страницы, на которой был нажат пункт меню. Это свойство не устанавливается, если нажатие произошло в контексте, где текущей страницы нет, например, в контекстном меню панели запуска.

  • parentMenuItemId

    строка | число необязательно

    Родительский идентификатор, если таковой имеется, для выбранного элемента.

  • выделениеТекст

    строка необязательная

    Текст для выбора контекста, если таковой имеется.

  • srcUrl

    строка необязательная

    Будет присутствовать для элементов с URL-адресом «src».

  • был проверен

    логическое необязательное

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

Характеристики

ACTION_MENU_TOP_LEVEL_LIMIT

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

Ценить

6

Методы

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
): number | string

Создаёт новый пункт контекстного меню. Если во время создания возникла ошибка, она может быть не обнаружена до срабатывания обратного вызова создания; подробности будут в runtime.lastError .

Параметры

  • createProperties

    CreateProperties

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • число | строка

    Идентификатор вновь созданного элемента.

remove()

chrome.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

Удаляет пункт контекстного меню.

Параметры

  • menuItemId

    строка | число

    Идентификатор пункта контекстного меню, который необходимо удалить.

Возврат

  • Обещание<void>

    Хром 123+

removeAll()

chrome.contextMenus.removeAll(): Promise<void>

Удаляет все пункты контекстного меню, добавленные этим расширением.

Возврат

  • Обещание<void>

    Хром 123+

update()

chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

Обновляет ранее созданный пункт контекстного меню.

Параметры

  • идентификатор

    строка | число

    Идентификатор обновляемого элемента.

  • updateProperties

    объект

    Свойства для обновления. Принимает те же значения, что и функция contextMenus.create .

    • проверено

      логическое необязательное

    • контексты

      [ ContextType , ... ContextType []] необязательно

    • documentUrlPatterns

      строка[] необязательная

    • включено

      логическое необязательное

    • parentId

      строка | число необязательно

      Идентификатор элемента, который будет сделан родительским для данного элемента. Примечание: элемент нельзя сделать дочерним для его собственного потомка.

    • targetUrlPatterns

      строка[] необязательная

    • заголовок

      строка необязательная

    • тип

      ItemType необязательный

    • видимый

      логическое необязательное

      Хром 62+

      Виден ли пункт в меню.

    • по клику

      необязательный

      Функция onclick выглядит так: 

      (info: OnClickData, tab: Tab) => {...}

      • информация

        OnClickData

        Хром 44+
      • вкладка

        Вкладка

        Хром 44+

        Информация о вкладке, на которой был выполнен клик. Этот параметр отсутствует для приложений платформы.

Возврат

  • Обещание<void>

    Хром 123+

События

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

Срабатывает при щелчке по элементу контекстного меню.

Параметры