хром.окна

Описание

Используйте API chrome.windows для взаимодействия с окнами браузера. Вы можете использовать этот API для создания, изменения и перестановки окон в браузере.

Разрешения

По запросу windows.Window содержит массив объектов tabs.Tab . Вы должны объявить разрешение "tabs" в своем манифесте , если вам нужен доступ к свойствам url , pendingUrl , title или favIconUrl tabs.Tab . Например:

{
  "name": "My extension",
  ...
  "permissions": ["tabs"],
  ...
}

Концепции и использование

Текущее окно

Многие функции в системе расширений принимают необязательный аргумент windowId , который по умолчанию соответствует текущему окну.

Текущее окно — это окно, содержащее код, который выполняется в данный момент. Важно понимать, что оно может отличаться от самого верхнего или сфокусированного окна.

Например, предположим, что расширение создает несколько вкладок или окон из одного файла HTML, и этот файл HTML содержит вызов tabs.query() . Текущее окно — это окно, содержащее страницу, выполнившую вызов, независимо от того, какое окно находится наверху.

В случае сервисных работников значение текущего окна возвращается к последнему активному окну. В некоторых случаях текущее окно для фоновых страниц может отсутствовать.

Примеры

Чтобы попробовать этот API, установите пример Windows API из репозитория chrome-extension-samples .

Два окна, каждое с одной вкладкой
Два окна, каждое с одной вкладкой.

Типы

CreateType

Хром 44+

Указывает, какой тип окна браузера нужно создать. «Панель» устарела и доступна только для существующих расширений из белого списка в Chrome OS.

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

"нормальный"
Определяет окно как стандартное.

"неожиданно возникнуть"
Определяет окно как всплывающее окно.

"панель"
Определяет окно как панель.

QueryOptions

Хром 88+

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

  • заселять

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

    Если это правда, объект windows.Window имеет свойство tabs , содержащее список объектов tabs.Tab . Объекты Tab содержат свойства url , pendingUrl , title и favIconUrl только в том случае, если файл манифеста расширения включает разрешение "tabs" .

  • Типы окон

    WindowType [] необязательно

    Если установлено, возвращаемое значение windows.Window фильтруется на основе его типа. Если этот параметр не установлен, фильтр по умолчанию установлен на ['normal', 'popup'] .

Window

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

  • всегдаонтоп

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

    Установлено ли окно всегда сверху.

  • сосредоточенный

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

    Является ли окно в настоящее время фокусным окном.

  • высота

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

    Высота окна, включая рамку, в пикселях. В некоторых случаях окну может не быть назначено свойство height ; например, при запросе закрытых окон из API sessions .

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

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

    Идентификатор окна. Идентификаторы окон уникальны в рамках сеанса браузера. В некоторых случаях окну может не быть присвоено свойство ID ; например, при запросе окон с использованием API sessions , в этом случае может присутствовать идентификатор сеанса.

  • инкогнито

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

    Является ли окно инкогнито.

  • левый

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

    Смещение окна от левого края экрана в пикселях. В некоторых случаях окну не может быть назначено left свойство; например, при запросе закрытых окон из API sessions .

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

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

    Идентификатор сеанса, используемый для уникальной идентификации окна, полученный из API sessions .

  • состояние

    WindowState необязательно

    Состояние этого окна браузера.

  • вкладки

    Вкладка [] необязательно

    Массив tabs.Tab Объекты Tab, представляющие текущие вкладки в окне.

  • вершина

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

    Смещение окна от верхнего края экрана в пикселях. В некоторых случаях окну не может быть назначено свойство top ; например, при запросе закрытых окон из API sessions .

  • тип

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

    Это тип окна браузера.

  • ширина

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

    Ширина окна, включая рамку, в пикселях. В некоторых случаях окну может не быть назначено свойство width ; например, при запросе закрытых окон из API sessions .

WindowState

Хром 44+

Состояние этого окна браузера. В некоторых случаях окну не может быть присвоено свойство state ; например, при запросе закрытых окон из API sessions .

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

"нормальный"
Нормальное состояние окна (не свернуто, не развернуто и не полноэкранно).

"минимизированный"
Свернутое состояние окна.

"максимизированный"
Максимизированное состояние окна.

"полноэкранный"
Состояние полноэкранного окна.

"заблокированный полноэкранный режим"
Состояние заблокированного полноэкранного окна. Из этого полноэкранного состояния невозможно выйти действием пользователя, оно доступно только для расширений из белого списка в Chrome OS.

WindowType

Хром 44+

Это тип окна браузера. В некоторых случаях окну может не быть присвоено свойство type ; например, при запросе закрытых окон из API sessions .

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

"нормальный"
Обычное окно браузера.

"неожиданно возникнуть"
Всплывающее окно браузера.

"панель"
Устарело в этом API. Окно в виде панели приложений Chrome. Расширения могут видеть только свои собственные окна панелей.

"приложение"
Устарело в этом API. Окно приложения Chrome. Расширения могут видеть только собственные окна приложения.

"инструменты разработчика"
Окно инструментов разработчика.

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

WINDOW_ID_CURRENT

Значение windowId, представляющее текущее окно .

Ценить

-2

WINDOW_ID_NONE

Значение windowId, обозначающее отсутствие окна браузера Chrome.

Ценить

-1

Методы

create()

Обещать
chrome.windows.create(
  createData?: object,
  callback?: function,
)

Создает (открывает) новое окно браузера с любым дополнительным размером, положением или URL-адресом по умолчанию.

Параметры

  • создать данные

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

    • сосредоточенный

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

      Если true , открывается активное окно. Если false , открывается неактивное окно.

    • высота

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

      Высота нового окна, включая рамку, в пикселях. Если не указано, по умолчанию используется естественная высота.

    • инкогнито

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

      Должно ли новое окно быть окном инкогнито.

    • левый

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

      Количество пикселей для расположения нового окна от левого края экрана. Если не указано, новое окно естественным образом смещается от последнего окна, находящегося в фокусе. Это значение игнорируется для панелей.

    • setSelfAsOpener

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

      Хром 64+

      Если true , «window.opener» вновь созданного окна устанавливается для вызывающего объекта и находится в той же единице связанных контекстов просмотра, что и вызывающий объект.

    • состояние

      WindowState необязательно

      Хром 44+

      Исходное состояние окна. minimized , maximized и fullscreen состояния нельзя комбинировать с параметрами left , top , width или height .

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

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

      Идентификатор вкладки, добавляемой в новое окно.

    • вершина

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

      Количество пикселей для расположения нового окна от верхнего края экрана. Если не указано, новое окно естественным образом смещается от последнего окна, находящегося в фокусе. Это значение игнорируется для панелей.

    • тип

      CreateType необязательно

      Указывает, какой тип окна браузера необходимо создать.

    • URL

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

      URL-адрес или массив URL-адресов, открываемых в виде вкладок в окне. Полные URL-адреса должны включать схему, например «http://www.google.com», а не «www.google.com». Неполные URL-адреса считаются относительными внутри расширения. По умолчанию используется страница новой вкладки.

    • ширина

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

      Ширина нового окна, включая рамку, в пикселях. Если не указано, по умолчанию используется естественная ширина.

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

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

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

    (window?: Window) => void

    • окно

      Окно опционально

      Содержит сведения о созданном окне.

Возврат

  • Обещание< Окно | не определено>

    Хром 88+

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

get()

Обещать
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

Получает сведения об окне.

Параметры

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

    число

  • Параметры запроса

    QueryOptions необязательно

    Хром 88+
  • перезвонить

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

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

    (window: Window) => void

Возврат

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

    Хром 88+

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

getAll()

Обещать
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

Получает все окна.

Параметры

  • Параметры запроса

    QueryOptions необязательно

    Хром 88+
  • перезвонить

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

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

    (windows: Window[]) => void

Возврат

  • Обещание< Окно []>

    Хром 88+

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

getCurrent()

Обещать
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

Получает текущее окно .

Параметры

  • Параметры запроса

    QueryOptions необязательно

    Хром 88+
  • перезвонить

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

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

    (window: Window) => void

Возврат

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

    Хром 88+

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

getLastFocused()

Обещать
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

Получает окно, фокус на котором был последним — обычно окно «сверху».

Параметры

  • Параметры запроса

    QueryOptions необязательно

    Хром 88+
  • перезвонить

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

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

    (window: Window) => void

Возврат

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

    Хром 88+

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

remove()

Обещать
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

Удаляет (закрывает) окно и все вкладки внутри него.

Параметры

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

    число

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

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

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

    () => void

Возврат

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

    Хром 88+

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

update()

Обещать
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

Обновляет свойства окна. Укажите только те свойства, которые необходимо изменить; неуказанные свойства не изменяются.

Параметры

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

    число

  • обновлениеинформация

    объект

    • привлечь внимание

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

      Если true , окно отображается таким образом, чтобы привлечь внимание пользователя к окну, без изменения фокусируемого окна. Эффект длится до тех пор, пока пользователь не переключит фокус на окно. Эта опция не имеет эффекта, если окно уже имеет фокус. Установите значение false , чтобы отменить предыдущий запрос drawAttention .

    • сосредоточенный

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

      Если true , окно перемещается на передний план; не может сочетаться с состоянием «свернуто». Если false , следующее окно в z-порядке перемещается на передний план; нельзя сочетать с состояниями «полноэкранный» или «развернутый».

    • высота

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

      Высота, до которой можно изменить размер окна в пикселях. Это значение игнорируется для панелей.

    • левый

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

      Смещение от левого края экрана, до которого перемещается окно, в пикселях. Это значение игнорируется для панелей.

    • состояние

      WindowState необязательно

      Новое состояние окна. Состояния «свернутое», «развернутое» и «полноэкранное» нельзя комбинировать с состояниями «слева», «сверху», «ширины» или «высоты».

    • вершина

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

      Смещение от верхнего края экрана, до которого перемещается окно, в пикселях. Это значение игнорируется для панелей.

    • ширина

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

      Ширина, до которой можно изменить размер окна в пикселях. Это значение игнорируется для панелей.

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

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

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

    (window: Window) => void

Возврат

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

    Хром 88+

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

События

onBoundsChanged

Хром 86+
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Вызывается при изменении размера окна; это событие отправляется только при фиксации новых границ, а не при незавершенных изменениях.

Параметры

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

    функция

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

    (window: Window) => void

onCreated

chrome.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

Вызывается при создании окна.

Параметры

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

    функция

    Хром 46+

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

    (window: Window) => void

    • окно

      Окно

      Детали созданного окна.

  • фильтры

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

    • Типы окон

      Тип окна []

      Условия, которым должен удовлетворять создаваемый тип окна. По умолчанию он соответствует ['normal', 'popup'] .

onFocusChanged

chrome.windows.onFocusChanged.addListener(
  callback: function,
  filters?: object,
)

Вызывается при изменении текущего фокусного окна. Возвращает chrome.windows.WINDOW_ID_NONE если все окна Chrome потеряли фокус. Примечание. В некоторых оконных менеджерах Linux WINDOW_ID_NONE всегда отправляется непосредственно перед переключением из одного окна Chrome в другое.

Параметры

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

    функция

    Хром 46+

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

    (windowId: number) => void

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

      число

      Идентификатор нового фокусируемого окна.

  • фильтры

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

    • Типы окон

      Тип окна []

      Условия, которым должен удовлетворять тип удаляемого окна. По умолчанию он соответствует ['normal', 'popup'] .

onRemoved

chrome.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

Вызывается, когда окно удаляется (закрывается).

Параметры

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

    функция

    Хром 46+

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

    (windowId: number) => void

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

      число

      Идентификатор удаленного окна.

  • фильтры

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

    • Типы окон

      Тип окна []

      Условия, которым должен удовлетворять тип удаляемого окна. По умолчанию он соответствует ['normal', 'popup'] .