Описание
Используйте API chrome.contextMenus
для добавления элементов в контекстное меню Google Chrome. Вы можете выбрать, к каким типам объектов будут применяться дополнения контекстного меню, например к изображениям, гиперссылкам и страницам.
Разрешения
contextMenus
Использование
Пункты контекстного меню могут появляться в любом документе (или фрейме внутри документа), даже в тех, которые имеют URL-адреса file:// или chrome://. Чтобы контролировать, в каких документах могут отображаться ваши элементы, укажите поле documentUrlPatterns при вызове метода create()
или update()
.
Вы можете создать столько элементов контекстного меню, сколько вам нужно, но если одновременно отображается более одного элемента вашего расширения, Google Chrome автоматически сворачивает их в одно родительское меню.
Манифест
Чтобы использовать API, вы должны объявить разрешение contextMenus в манифесте вашего расширения. Также вам следует указать значок размером 16x16 пикселей для отображения рядом с вашим пунктом меню. Например:
{
"name": "My extension",
...
"permissions": [
"contextMenus"
],
"icons": {
"16": "icon-bitty.png",
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}
Примеры
Чтобы попробовать этот API, установите пример API contextMenus из репозитория chrome-extension-samples .
Типы
ContextType
Различные контексты, в которых может появляться меню. Указание «все» эквивалентно комбинации всех других контекстов, кроме «панель запуска». Контекст «панели запуска» поддерживается только приложениями и используется для добавления пунктов в контекстное меню, которое появляется при нажатии значка приложения на панели запуска/панели задач/док-станции/и т. д. Различные платформы могут налагать ограничения на то, что фактически поддерживается в контекстном меню программы запуска.
Перечисление
"все" "страница" "рамка" "выбор" "связь" "редактируемый" "изображение" "видео" "аудио" "пусковая установка" "browser_action" "страница_действие" "действие"
CreateProperties
Свойства нового пункта контекстного меню.
Характеристики
- проверено
логическое значение необязательно
Исходное состояние флажка или переключателя:
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) => {...}
- информация
Информация об элементе, по которому был сделан щелчок, и контексте, в котором произошел щелчок.
- вкладка
Подробная информация о вкладке, на которой произошел щелчок. Этот параметр отсутствует для приложений платформы.
ItemType
Тип пункта меню.
Перечисление
"нормальный" "флажок" "радио" "сепаратор"
OnClickData
Информация, отправляемая при нажатии на пункт контекстного меню.
Характеристики
- проверено
логическое значение необязательно
Флаг, указывающий состояние флажка или переключателя после его щелчка.
- редактируемый
логическое значение
Флаг, указывающий, доступен ли элемент для редактирования (ввод текста, текстовая область и т. д.).
- идентификатор кадра
номер необязательно
Хром 51+Идентификатор кадра элемента, в котором был сделан щелчок по контекстному меню, если он находился внутри кадра.
- фреймURL
строка необязательна
URL-адрес фрейма элемента, в котором было выполнено нажатие контекстного меню, если оно было внутри фрейма.
- URL-адрес ссылки
строка необязательна
Если элемент является ссылкой, URL-адрес, на который она указывает.
- медиатип
строка необязательна
Одно из значений «изображение», «видео» или «аудио», если контекстное меню было активировано для одного из этих типов элементов.
строка | число
Идентификатор пункта меню, по которому был выполнен щелчок.
- 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,
)
Удаляет пункт контекстного меню.
Параметры
строка | число
Идентификатор пункта контекстного меню, который нужно удалить.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Хром 123+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
Удаляет все элементы контекстного меню, добавленные этим расширением.
Параметры
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Хром 123+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
Обновляет ранее созданный элемент контекстного меню.
Параметры
- идентификатор
строка | число
Идентификатор элемента, который необходимо обновить.
- ОбновлениеСвойства
объект
Свойства для обновления. Принимает те же значения, что и функция
contextMenus.create
.- проверено
логическое значение необязательно
- контексты
[ ContextType , ... ContextType []] необязательно
- ДокументUrlPatterns
строка[] необязательно
- включено
логическое значение необязательно
- родительский идентификатор
строка | номер необязательно
Идентификатор элемента, который будет сделан родительским для этого элемента. Примечание. Вы не можете сделать элемент дочерним по отношению к своему потомку.
- таргетурлпаттернс
строка[] необязательно
- заголовок
строка необязательна
- тип
Тип элемента необязательно
- видимый
логическое значение необязательно
Хром 62+Виден ли элемент в меню.
- по клику
аннулировать необязательно
Функция
onclick
выглядит так:(info: OnClickData, tab: Tab) => {...}
- информацияХром 44+
- вкладкаХром 44+
Подробности вкладки, на которой произошел щелчок. Этот параметр отсутствует для приложений платформы.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Хром 123+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
События
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
Вызывается при нажатии на элемент контекстного меню.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(info: OnClickData, tab?: tabs.Tab) => void
- информация
- вкладка
tabs.Tab необязательно