chrome.contextMenu

Описание

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

Разрешения

contextMenus

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

{
  "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, установите пример contextMenus API из репозитория chrome-extension-samples .

Типы

ContextType

Chrome 44+

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

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

"все"

"страница"

"рамка"

«выбор»

"связь"

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

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

"видео"

"аудио"

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

"browser_action"

"page_action"

"действие"

CreateProperties

Chrome 123+

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

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

  • проверено

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

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

  • контексты

    [ ContextType , ... ContextType []] optional

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

  • documentUrlPatterns

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

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

  • включено

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

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

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

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

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

  • parentId

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

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

  • targetUrlPatterns

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

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

  • заголовок

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

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

  • тип

    ItemType ( необязательный параметр)

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

  • видимый

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

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

  • при клике

    void optional

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

    Функция onclick выглядит следующим образом: 

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

    • информация

      OnClickData

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

    • вкладка

      Вкладка

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

ItemType

Chrome 44+

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

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

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

"флажок"

"радио"

«разделитель»

OnClickData

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

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

  • проверено

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

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

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

    логический

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

  • frameId

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

    Chrome 51+

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

  • frameUrl

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

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

  • linkUrl

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

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

  • медиаТип

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

    Если для одного из этих типов элементов было активировано контекстное меню, выберите один из вариантов: 'image', 'video' или 'audio'.

  • 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 .

Параметры

  • создатьСвойства

    СоздатьСвойства

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

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

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

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

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

remove()

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

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

Параметры

  • menuItemId

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

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

Возвраты

  • Обещание<пустота>

    Chrome 123+

    Проблема решается при удалении контекстного меню.

removeAll()

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

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

Возвраты

  • Обещание<пустота>

    Chrome 123+

    Проблема решается после завершения удаления.

update()

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

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

Параметры

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

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

    Идентификатор элемента, который необходимо обновить.

  • обновитьСвойства

    объект

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

    • проверено

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

    • контексты

      [ ContextType , ... ContextType []] optional

    • documentUrlPatterns

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

    • включено

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

    • parentId

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

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

    • targetUrlPatterns

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

    • заголовок

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

    • тип

      ItemType ( необязательный параметр)

    • видимый

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

      Chrome 62+

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

    • при клике

      void optional

      Функция onclick выглядит следующим образом: 

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

      • информация

        OnClickData

        Chrome 44+
      • вкладка

        Вкладка

        Chrome 44+

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

Возвраты

  • Обещание<пустота>

    Chrome 123+

    Проблема решается после обновления контекстного меню.

События

onClicked

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

Событие срабатывает при нажатии на пункт контекстного меню.

Параметры