Описание
Используйте 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
Указывает, какой тип окна браузера необходимо создать. «Панель» устарела и доступна только для существующих расширений из белого списка в Chrome OS.
Перечисление
"нормальный" "неожиданно возникнуть" "панель"
Определяет окно как стандартное.
Определяет окно как всплывающее окно.
Определяет окно как панель.
QueryOptions
Характеристики
- заселять
логическое значение необязательно
Если это правда, объект
windows.Window
имеет свойствоtabs
, содержащее список объектовtabs.Tab
. ОбъектыTab
содержат свойстваurl
,pendingUrl
,title
иfavIconUrl
только в том случае, если файл манифеста расширения включает разрешение"tabs"
. - Типы окон
WindowType [] необязательно
Если установлено, возвращаемое значение
windows.Window
фильтруется на основе его типа. Если этот параметр не установлен, фильтр по умолчанию установлен на['normal', 'popup']
.
Window
Характеристики
- всегдаонтоп
логическое значение
Установлено ли окно всегда сверху.
- сосредоточенный
логическое значение
Является ли окно в настоящее время фокусным окном.
- высота
номер необязательно
Высота окна, включая рамку, в пикселях. В некоторых случаях окну может не быть назначено свойство
height
; например, при запросе закрытых окон из APIsessions
. - идентификатор
номер необязательно
Идентификатор окна. Идентификаторы окон уникальны в рамках сеанса браузера. В некоторых случаях окну может не быть присвоено свойство
ID
; например, при запросе окон с использованием APIsessions
, в этом случае может присутствовать идентификатор сеанса. - инкогнито
логическое значение
Является ли окно инкогнито.
- левый
номер необязательно
Смещение окна от левого края экрана в пикселях. В некоторых случаях окну не может быть назначено
left
свойство; например, при запросе закрытых окон из APIsessions
. - идентификатор сеанса
строка необязательна
Идентификатор сеанса, используемый для уникальной идентификации окна, полученный из API
sessions
. - состояние
WindowState необязательно
Состояние этого окна браузера.
- вкладки
Вкладка [] необязательно
Массив
tabs.Tab
Объекты Tab, представляющие текущие вкладки в окне. - вершина
номер необязательно
Смещение окна от верхнего края экрана в пикселях. В некоторых случаях окну не может быть назначено свойство
top
; например, при запросе закрытых окон из APIsessions
. - тип
Тип окна необязательно
Это тип окна браузера.
- ширина
номер необязательно
Ширина окна, включая рамку, в пикселях. В некоторых случаях окну может не быть назначено свойство
width
; например, при запросе закрытых окон из APIsessions
.
WindowState
Состояние этого окна браузера. В некоторых случаях окну не может быть присвоено свойство state
; например, при запросе закрытых окон из API sessions
.
Перечисление
"нормальный" "минимизированный" "максимизированный" "полноэкранный" "заблокированный полноэкранный режим"
Нормальное состояние окна (не свернуто, не развернуто и не полноэкранно).
Свернутое состояние окна.
Максимизированное состояние окна.
Состояние полноэкранного окна.
Состояние заблокированного полноэкранного окна. Из этого полноэкранного состояния невозможно выйти действием пользователя, оно доступно только для расширений из белого списка в Chrome OS.
WindowType
Это тип окна браузера. В некоторых случаях окну может не быть присвоено свойство 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
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
Вызывается при изменении размера окна; это событие отправляется только при фиксации новых границ, а не при незавершенных изменениях.
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
Вызывается при создании окна.
Параметры
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']
.