chrome.windows

refresh date: 2026-09-25 robots: noindex

Описание

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

Манифест

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

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

Текущее окно

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

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

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

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

Примеры

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

Типы

CreateType

Chrome 44 и более поздних версий;

Указывает, какой тип окна браузера нужно создать. Значение panel устарело и доступно только для существующих расширений из белого списка в ChromeOS.

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

"normal"
Окно будет стандартным.

"popup"
Окно будет всплывающим.

"panel"
Окно открывается в виде панели.

QueryOptions

Chrome 88 и более поздних версий;

Свойства

• подставлять

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

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

• windowTypes

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

  Если задано, возвращаемый объект windows.Window фильтруется по типу. Если фильтр не задан, по умолчанию используется ['normal', 'popup'].

Window

Свойства

• alwaysOnTop

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

  Указывает, должно ли окно всегда находиться поверх других.

• сосредоточенность

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

  Указывает, находится ли окно в фокусе.

• высота

  number (необязательно)

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

• id

  number (необязательно)

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

• инкогнито

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

  Указывает, открыто ли окно в режиме инкогнито.

• влево

  number (необязательно)

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

• sessionId

  Строка (необязательно)

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

• штат

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

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

• вкладки

  Tab[] необязательный

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

• верхняя

  number (необязательно)

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

• тип

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

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

• ширина

  number (необязательно)

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

WindowState

Chrome 44 и более поздних версий;

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

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

"normal"
Обычное состояние окна (не свернуто, не развернуто и не в полноэкранном режиме).

"minimized"
Окно свернуто.

"maximized"
Развернутое окно.

"fullscreen"
Полноэкранный режим.

WindowType

Chrome 44 и более поздних версий;

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

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

"normal"
Обычное окно браузера.

popup
Всплывающее окно браузера.

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

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

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

Свойства

WINDOW_ID_CURRENT

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

Значение

-2

WINDOW_ID_NONE

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

Значение

-1

Методы

create()

Promise

chrome.windows.create(
  createData?: object,
  callback?: function,
): Promise<Window | undefined>

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

Параметры

• createData

  Объект (необязательно)

  • сосредоточенность

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

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

  • высота

    number (необязательно)

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

  • инкогнито

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

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

  • влево

    number (необязательно)

    Расстояние в пикселях от левого края экрана до нового окна. Если значение не указано, новое окно будет смещено относительно последнего активного окна. Для панелей это значение игнорируется.

  • setSelfAsOpener

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

    Chrome 64 и более поздних версий;

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

  • штат

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

    Chrome 44 и более поздних версий;

    Начальное состояние окна. Состояния minimized, maximized и fullscreen нельзя комбинировать с left, top, width или height.

  • tabId

    number (необязательно)

    Идентификатор вкладки, которую нужно добавить в новое окно.

  • верхняя

    number (необязательно)

    Расстояние в пикселях от верхнего края экрана до нового окна. Если значение не указано, новое окно будет смещено относительно последнего активного окна. Для панелей это значение игнорируется.

  • тип

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

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

  • url

    string | string[] optional

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

  • ширина

    number (необязательно)

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

• обратный вызов

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

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

  (window?: Window) => void

  • окно

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

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

Возвраты

• Promise<Window | undefined>

  Chrome 88 и более поздних версий;

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

get()

Promise

chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

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

Параметры

• windowId

  число

• queryOptions

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

  Chrome 88 и более поздних версий;
• обратный вызов

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

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

  (window: Window) => void

  • окно

    Окно;

Возвраты

• Promise<Window>

  Chrome 88 и более поздних версий;

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

getAll()

Promise

chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window[]>

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

Параметры

• queryOptions

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

  Chrome 88 и более поздних версий;
• обратный вызов

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

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

  (windows: Window[]) => void

  • окна

    Окно[]

Возвраты

• Promise<Window[]>

  Chrome 88 и более поздних версий;

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

getCurrent()

Promise

chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

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

Параметры

• queryOptions

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

  Chrome 88 и более поздних версий;
• обратный вызов

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

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

  (window: Window) => void

  • окно

    Окно;

Возвраты

• Promise<Window>

  Chrome 88 и более поздних версий;

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

getLastFocused()

Promise

chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

Возвращает окно, которое было в фокусе последним (обычно это окно, расположенное поверх остальных).

Параметры

• queryOptions

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

  Chrome 88 и более поздних версий;
• обратный вызов

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

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

  (window: Window) => void

  • окно

    Окно;

Возвраты

• Promise<Window>

  Chrome 88 и более поздних версий;

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

remove()

Promise

chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

Закрывает окно и все вкладки в нем.

Параметры

• windowId

  число

• обратный вызов

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

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

  () => void

Возвраты

• Promise<void>

  Chrome 88 и более поздних версий;

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

update()

Promise

chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
): Promise<Window>

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

Параметры

• windowId

  число

• updateInfo

  Объект

  • drawAttention

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

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

  • сосредоточенность

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

    Если задано значение true, окно перемещается на передний план. Нельзя использовать вместе со значением minimized. Если задано значение false, на передний план выводится следующее окно в порядке наложения. Нельзя использовать вместе с состояниями fullscreen и maximized.

  • высота

    number (необязательно)

    Высота окна в пикселях. Для панелей это значение игнорируется.

  • влево

    number (необязательно)

    Смещение от левого края экрана, на которое нужно переместить окно (в пикселях). Для панелей это значение игнорируется.

  • штат

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

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

  • верхняя

    number (необязательно)

    Смещение от верхнего края экрана, на которое нужно переместить окно (в пикселях). Для панелей это значение игнорируется.

  • ширина

    number (необязательно)

    Ширина окна в пикселях. Для панелей это значение игнорируется.

• обратный вызов

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

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

  (window: Window) => void

  • окно

    Окно;

Возвраты

• Promise<Window>

  Chrome 88 и более поздних версий;

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

События

onBoundsChanged

Chrome 86 и более поздних версий.

chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Срабатывает, когда размер окна изменен. Это событие отправляется только после того, как новые границы зафиксированы, а не во время изменения.

Параметры

• обратный вызов

  function

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

  (window: Window) => void

  • окно

    Окно;

onCreated

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

Срабатывает при создании окна.

Параметры

• обратный вызов

  function

  Chrome 46 и более поздних версий;

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

  (window: Window) => void

  • окно

    Окно;

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

• фильтры

  Объект (необязательно)

  • windowTypes

    WindowType[]

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

onFocusChanged

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

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

Параметры

• обратный вызов

  function

  Chrome 46 и более поздних версий;

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

  (windowId: number) => void

  • windowId

    число

    Идентификатор окна, которое только что оказалось в фокусе.

• фильтры

  Объект (необязательно)

  • windowTypes

    WindowType[]

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

onRemoved

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

Срабатывает, когда окно удалено (закрыто).

Параметры

• обратный вызов

  function

  Chrome 46 и более поздних версий;

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

  (windowId: number) => void

  • windowId

    число

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

• фильтры

  Объект (необязательно)

  • windowTypes

    WindowType[]

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