chrome.pageAction

Описание

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

Доступность

≤ МВ2

Некоторые примеры:

  • Подпишитесь на 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 ).

Тип

Данные изображения

TabDetails

Хром 88+

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

  • идентификатор табуляции

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

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

Методы

getPopup()

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

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

Параметры

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

    ВкладкаПодробности

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

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

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

    (result: string) => void

    • результат

      нить

Возврат

  • Обещание<строка>

    Хром 101+

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

getTitle()

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

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

Параметры

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

    ВкладкаПодробности

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

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

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

    (result: string) => void

    • результат

      нить

Возврат

  • Обещание<строка>

    Хром 101+

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

hide()

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

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

Параметры

  • идентификатор табуляции

    число

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

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

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

    Хром 67+

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

    () => void

Возврат

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

    Хром 101+

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

setIcon()

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

Устанавливает значок для действия страницы. Значок можно указать либо как путь к файлу изображения, либо как данные пикселей из элемента холста, либо как словарь любого из них. Необходимо указать либо путь , либо свойство 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}'.

    • идентификатор табуляции

      число

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

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

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

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

    () => void

Возврат

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

    Хром 101+

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

setPopup()

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

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

Параметры

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

    объект

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

      нить

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

    • идентификатор табуляции

      число

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

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

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

    Хром 67+

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

    () => void

Возврат

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

    Хром 101+

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

setTitle()

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

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

Параметры

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

    объект

    • идентификатор табуляции

      число

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

    • заголовок

      нить

      Строка подсказки.

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

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

    Хром 67+

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

    () => void

Возврат

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

    Хром 101+

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

show()

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

Показывает действие страницы. Действие страницы отображается всякий раз, когда выбрана вкладка.

Параметры

  • идентификатор табуляции

    число

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

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

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

    Хром 67+

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

    () => void

Возврат

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

    Хром 101+

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

События

onClicked

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

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

Параметры

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

    функция

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

    (tab: tabs.Tab) => void