chrome.pageAction

дата обновления: 2026-09-25 robots: noindex

Описание

Используйте API chrome.pageAction , чтобы разместить значки на главной панели инструментов Google Chrome справа от адресной строки. Действия страницы — это действия, которые можно выполнить на текущей странице, но которые не применимы ко всем страницам. Действия страницы отображаются серым цветом, когда они неактивны.

Доступность

≤ MV2

Несколько примеров:

  • Подпишитесь на RSS-ленту этой страницы
  • Создайте слайд-шоу из фотографий с этой страницы.

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

Скрытые действия на странице отображаются серым цветом. Например, RSS-лента ниже недоступна, так как вы не можете подписаться на ленту для текущей страницы:

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

Манифест

Зарегистрируйте действие вашей страницы в манифесте расширения следующим образом:

{
  "name": "My extension",
  ...
  "page_action": {
    "default_icon": {                    // optional
      "16": "images/icon16.png",           // optional
      "24": "images/icon24.png",           // optional
      "32": "images/icon32.png"            // optional
    },
    "default_title": "Google Mail",      // optional; shown in tooltip
    "default_popup": "popup.html"        // optional
  },
  ...
}

Поскольку устройства с менее распространенными коэффициентами масштабирования, такими как 1,5x или 1,2x, становятся все более распространенными, рекомендуется предоставлять несколько размеров для ваших значков. Chrome выберет ближайший размер и масштабирует его, чтобы заполнить пространство в 16 ячеек. Это также гарантирует, что если размер отображения значка когда-либо изменится, вам не придется дополнительно предоставлять разные значки! Однако, если разница в размерах слишком велика, такое масштабирование может привести к потере детализации значка или его размытости.

Старый синтаксис для регистрации значка по умолчанию по-прежнему поддерживается:

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Части пользовательского интерфейса

Подобно действиям браузера, действия страницы могут иметь значок, всплывающую подсказку и всплывающее окно; однако они не могут иметь значки-памятки. Кроме того, действия страницы могут быть неактивными (серыми). Информацию о значках, всплывающих подсказках и всплывающих окнах можно найти в разделе «Интерфейс действий браузера» .

Вы можете сделать действие на странице видимым или затемненным с помощью методов pageAction.show и pageAction.hide соответственно. По умолчанию действие на странице отображается затемненным. При отображении значка необходимо указать вкладку, на которой он должен появиться. Значок остается видимым до тех пор, пока вкладка не будет закрыта или не начнет отображать другой URL-адрес (например, если пользователь щелкнет ссылку).

Советы

Для достижения наилучшего визуального эффекта следуйте этим рекомендациям:

  • Используйте действия на странице только для тех функций, которые имеют смысл использовать лишь на нескольких страницах.
  • Не используйте действия страницы для функций, которые актуальны для большинства страниц. Вместо этого используйте действия браузера .
  • Не нужно постоянно анимировать иконку. Это просто раздражает.

Типы

ImageDataType

Пиксельные данные изображения. Должны быть объектом ImageData (например, из элемента canvas ).

Тип

ImageData

TabDetails

Chrome 88+

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

  • tabId

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

    Идентификатор вкладки, для которой нужно запросить состояние. Если вкладка не указана, возвращается состояние, не привязанное к вкладке.

Методы

getPopup()

Обещать
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

Параметры

  • подробности

    TabDetails

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

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

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

    (result: string) => void

    • результат

      нить

Возвраты

  • Promise<string>

    Chrome 101+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getTitle()

Обещать
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

Получает заголовок страницы.

Параметры

  • подробности

    TabDetails

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

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

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

    (result: string) => void

    • результат

      нить

Возвраты

  • Promise<string>

    Chrome 101+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

hide()

Обещать
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

Скрывает действие страницы. Скрытые действия страницы по-прежнему отображаются на панели инструментов Chrome, но выделены серым цветом.

Параметры

  • tabId

    число

    Идентификатор вкладки, для которой вы хотите изменить действие страницы.

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

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

    Chrome 67+

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

    () => void

Возвраты

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

    Chrome 101+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setIcon()

Обещать
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

Задает значок для действия на странице. Значок может быть указан либо как путь к файлу изображения, либо как пиксельные данные элемента canvas, либо как словарь, содержащий либо то, либо другое. Необходимо указать либо путь , либо свойство imageData .

Параметры

  • подробности

    объект

    • iconIndex

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

      Устарело. Этот аргумент игнорируется.

    • данные изображения

      ImageData | объект необязателен

      Либо объект ImageData, либо словарь {size -> ImageData}, представляющий иконку, которую нужно установить. Если иконка указана в виде словаря, фактическое изображение для использования выбирается в зависимости от плотности пикселей экрана. Если количество пикселей изображения, помещающихся в одну единицу экранного пространства, равно scale , то будет выбрано изображение размером scale * n, где n — размер иконки в пользовательском интерфейсе. Необходимо указать как минимум одно изображение. Обратите внимание, что 'details.imageData = foo' эквивалентно 'details.imageData = {'16': foo}'

    • путь

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

      Указывается либо относительный путь к изображению, либо словарь {размер -> относительный путь к изображению}, указывающий на устанавливаемую иконку. Если иконка указана в виде словаря, фактическое используемое изображение выбирается в зависимости от плотности пикселей экрана. Если количество пикселей изображения, помещающихся в одну единицу экранного пространства, равно scale , то будет выбрано изображение размером scale * n, где n — размер иконки в пользовательском интерфейсе. Необходимо указать как минимум одно изображение. Обратите внимание, что 'details.path = foo' эквивалентно 'details.path = {'16': foo}'

    • tabId

      число

      Идентификатор вкладки, для которой вы хотите изменить действие страницы.

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

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

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

    () => void

Возвраты

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

    Chrome 101+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setPopup()

Обещать
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

Задает HTML-документ, который будет открываться во всплывающем окне при щелчке пользователя по значку действия на странице.

Параметры

  • подробности

    объект

    • неожиданно возникнуть

      нить

      Относительный путь к HTML-файлу, который будет отображаться во всплывающем окне. Если задана пустая строка ( '' ), всплывающее окно не отображается.

    • tabId

      число

      Идентификатор вкладки, для которой вы хотите изменить действие страницы.

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

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

    Chrome 67+

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

    () => void

Возвраты

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

    Chrome 101+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setTitle()

Обещать
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

Задает заголовок действия на странице. Он отображается во всплывающей подсказке над действием на странице.

Параметры

  • подробности

    объект

    • tabId

      число

      Идентификатор вкладки, для которой вы хотите изменить действие страницы.

    • заголовок

      нить

      Строка всплывающей подсказки.

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

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

    Chrome 67+

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

    () => void

Возвраты

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

    Chrome 101+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

show()

Обещать
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

Отображает действие на странице. Действие на странице отображается при выборе вкладки.

Параметры

  • tabId

    число

    Идентификатор вкладки, для которой вы хотите изменить действие страницы.

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

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

    Chrome 67+

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

    () => void

Возвраты

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

    Chrome 101+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

onClicked

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

Событие срабатывает при нажатии на значок действия на странице. Это событие не сработает, если действие на странице содержит всплывающее окно.

Параметры

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

    функция

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

    (tab: tabs.Tab) => void