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

Типы

ContextType

Хром 44+

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

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

"все"

"страница"

"рамка"

"выбор"

"связь"

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

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

"видео"

"аудио"

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

"browser_action"

"страница_действие"

"действие"

CreateProperties

Хром 123+

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

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

  • проверено

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

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

  • контексты

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

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

  • ДокументUrlPatterns

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

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

  • включено

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

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

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

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

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

  • родительский идентификатор

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

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

  • таргетурлпаттернс

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

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

  • заголовок

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

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

  • тип

    Тип элемента необязательно

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

  • видимый

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

    Виден ли элемент в меню.

  • по клику

    аннулировать необязательно

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

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

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

    • информация

      OnClickData

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

    • вкладка

      Вкладка

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

ItemType

Хром 44+

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

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

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

"флажок"

"радио"

"сепаратор"

OnClickData

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

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

  • проверено

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

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

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

    логическое значение

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

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

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

    Хром 51+

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

  • фреймURL

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

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

  • URL-адрес ссылки

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

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

  • медиатип

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

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

  • идентификатор менюItemId

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

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

  • URL-адрес страницы

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

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

  • родительменуитемид

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

    Родительский идентификатор элемента, по которому щелкнули, если таковой имеется.

  • выбор текста

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

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

  • srcUrl

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

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

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

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

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

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

ACTION_MENU_TOP_LEVEL_LIMIT

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

Ценить

6

Методы

create()

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

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

Параметры

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

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

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

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

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

    () => void

Возврат

  • номер | нить

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

remove()

Обещать
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

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

Параметры

  • идентификатор менюItemId

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

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

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

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

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

    () => void

Возврат

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

    Хром 123+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

removeAll()

Обещать
chrome.contextMenus.removeAll(
  callback?: function,
)

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

Параметры

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

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

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

    () => void

Возврат

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

    Хром 123+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

update()

Обещать
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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

Параметры

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

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

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

  • ОбновлениеСвойства

    объект

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

    • проверено

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

    • контексты

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

    • ДокументUrlPatterns

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

    • включено

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

    • родительский идентификатор

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

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

    • таргетурлпаттернс

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

    • заголовок

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

    • тип

      Тип элемента необязательно

    • видимый

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

      Хром 62+

      Виден ли элемент в меню.

    • по клику

      аннулировать необязательно

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

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

      • информация

        OnClickData

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

        Вкладка

        Хром 44+

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

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

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

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

    () => void

Возврат

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

    Хром 123+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onClicked

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

Вызывается при нажатии на элемент контекстного меню.

Параметры

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

    функция

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

    (info: OnClickData, tab?: tabs.Tab) => void