chrome.windows

refresh date: 2026-09-25 robots: noindex

Opis

Używaj interfejsu chrome.windows API do interakcji z oknami przeglądarki. Za pomocą tego interfejsu API możesz tworzyć, modyfikować i przenosić okna w przeglądarce.

Plik manifestu

Na żądanie obiekt windows.Window zawiera tablicę obiektów tabs.Tab. Jeśli potrzebujesz dostępu do właściwości url, pendingUrl, title lub favIconUrl obiektu tabs.Tab, musisz zadeklarować uprawnienie "tabs" w pliku manifestu. Na przykład:

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

bieżące okno,

Wiele funkcji w systemie rozszerzeń przyjmuje opcjonalny argument windowId, który domyślnie odnosi się do bieżącego okna.

Bieżące okno to okno zawierające kod, który jest obecnie wykonywany. Warto pamiętać, że może to być inne okno niż to, które jest na wierzchu lub jest aktywne.

Załóżmy na przykład, że rozszerzenie tworzy kilka kart lub okien z jednego pliku HTML, a plik HTML zawiera wywołanie funkcji tabs.query(). Bieżące okno to okno zawierające stronę, która wywołała funkcję, niezależnie od tego, które okno jest na wierzchu.

W przypadku service workerów wartość bieżącego okna jest zastępowana wartością ostatniego aktywnego okna. W niektórych przypadkach nie ma bieżącego okna stron działających w tle.

Przykłady

2 okna, każde z 1 kartą

Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu API Windows z repozytorium chrome-extension-samples.

Typy

CreateType

Chrome 44 lub nowsza

Określa typ okna przeglądarki do utworzenia. Wartość „panel” została wycofana i jest dostępna tylko w przypadku istniejących rozszerzeń na liście dozwolonych w ChromeOS.

Typ wyliczeniowy

„normal”
Określa okno jako standardowe.

„popup”
Określa okno jako wyskakujące.

„panel”
Określa okno jako panel.

QueryOptions

Chrome 88 lub nowsza

Właściwości

  • wypełnić : uzupełnić

    wartość logiczna opcjonalna

    Jeśli wartość to „true”, obiekt windows.Window ma właściwość tabs, która zawiera listę obiektów tabs.Tab. Obiekty Tab zawierają tylko właściwości url, pendingUrl, title i favIconUrl, jeśli plik manifestu rozszerzenia zawiera uprawnienie "tabs".

  • windowTypes

    WindowType[] opcjonalny

    Jeśli ten parametr jest ustawiony, zwrócony element windows.Window jest filtrowany na podstawie jego typu. Jeśli nie zostanie ustawiony, domyślny filtr będzie miał wartość ['normal', 'popup'].

Window

Właściwości

  • alwaysOnTop

    wartość logiczna

    Określa, czy okno ma być zawsze na wierzchu.

  • skupiony,

    wartość logiczna

    Określa, czy okno jest obecnie oknem aktywnym.

  • wysokość

    number opcjonalny

    Wysokość okna (wraz z ramką) w pikselach. W niektórych przypadkach okno może nie mieć przypisanej właściwości height, np. podczas wysyłania zapytań o zamknięte okna z interfejsu sessions API.

  • id

    number opcjonalny

    Identyfikator okna. Identyfikatory okien są unikalne w ramach sesji przeglądarki. W niektórych przypadkach okno może nie mieć przypisanej właściwości ID, np. podczas wysyłania zapytań dotyczących okien za pomocą interfejsu sessions API. W takim przypadku może być obecny identyfikator sesji.

  • incognito,

    wartość logiczna

    Określa, czy okno jest incognito.

  • w lewo

    number opcjonalny

    Przesunięcie okna od lewej krawędzi ekranu w pikselach. W niektórych przypadkach okno może nie mieć przypisanej właściwości left, np. podczas wysyłania zapytań o zamknięte okna z interfejsu sessions API.

  • sessionId

    ciąg znaków opcjonalny

    Identyfikator sesji używany do jednoznacznego identyfikowania okna, uzyskany z interfejsu sessions API.

  • stan

    WindowState opcjonalny

    Stan tego okna przeglądarki.

  • karty,

    Tab[] opcjonalny

    Tablica obiektów tabs.Tab reprezentujących bieżące karty w oknie.

  • góra

    number opcjonalny

    Przesunięcie okna od górnej krawędzi ekranu w pikselach. W niektórych przypadkach okno może nie mieć przypisanej właściwości top, np. podczas wysyłania zapytań o zamknięte okna z interfejsu sessions API.

  • typ

    WindowType opcjonalny

    Rodzaj okna przeglądarki.

  • szerokość

    number opcjonalny

    Szerokość okna, łącznie z ramką, w pikselach. W niektórych przypadkach okno może nie mieć przypisanej właściwości width, np. podczas wysyłania zapytań o zamknięte okna z interfejsu sessions API.

WindowState

Chrome 44 lub nowsza

Stan tego okna przeglądarki. W niektórych przypadkach okno może nie mieć przypisanej właściwości state, np. podczas wysyłania zapytań o zamknięte okna z interfejsu sessions API.

Typ wyliczeniowy

„normal”
Normalny stan okna (niezminimalizowany, niezmaksymalizowany ani niepełnoekranowy).

„zminimalizowane”
Stan zminimalizowanego okna.

„maximized”
Stan zmaksymalizowanego okna.

„fullscreen”
Stan okna w trybie pełnoekranowym.

WindowType

Chrome 44 lub nowsza

Rodzaj okna przeglądarki. W niektórych przypadkach okno może nie mieć przypisanej właściwości type, np. podczas wysyłania zapytań o zamknięte okna z interfejsu sessions API.

Typ wyliczeniowy

„normal”
Zwykłe okno przeglądarki.

„popup”
Wyskakujące okienko przeglądarki.

„panel”
Wycofano w tym interfejsie API. Okno w stylu panelu aplikacji Chrome. Rozszerzenia widzą tylko własne okna panelu.

„app”
Wycofane w tym interfejsie API. okno aplikacji Chrome, Rozszerzenia mogą wyświetlać tylko okna własnej aplikacji.

„devtools”
Okno Narzędzi deweloperskich.

Właściwości

WINDOW_ID_CURRENT

Wartość windowId reprezentująca bieżące okno.

Wartość

-2

WINDOW_ID_NONE

Wartość windowId, która oznacza brak okna przeglądarki Chrome.

Wartość

-1

Metody

create()

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

Tworzy (otwiera) nowe okno przeglądarki z opcjonalnymi rozmiarami, pozycją lub domyślnym adresem URL.

Parametry

  • createData

    obiekt opcjonalny

    • skupiony,

      wartość logiczna opcjonalna

      Jeśli true, otwiera aktywne okno. Jeśli false, otwiera nieaktywne okno.

    • wysokość

      number opcjonalny

      Wysokość nowego okna w pikselach, łącznie z ramką. Jeśli nie podasz żadnej wartości, domyślnie zostanie użyta naturalna wysokość.

    • incognito,

      wartość logiczna opcjonalna

      Określa, czy nowe okno ma być oknem incognito.

    • w lewo

      number opcjonalny

      Liczba pikseli, o którą nowe okno ma być odsunięte od lewej krawędzi ekranu. Jeśli nie podasz tego argumentu, nowe okno zostanie przesunięte w naturalny sposób względem ostatniego okna, na którym skupiono uwagę. Ta wartość jest ignorowana w przypadku paneli.

    • setSelfAsOpener

      wartość logiczna opcjonalna

      Chrome 64+

      Jeśli true, właściwość „window.opener” nowo utworzonego okna jest ustawiona na wywołującą stronę i znajduje się w tej samej jednostce powiązanych kontekstów przeglądania co wywołująca strona.

    • stan

      WindowState opcjonalny

      Chrome 44 lub nowsza

      Początkowy stan okna. Stanów minimized, maximized i fullscreen nie można łączyć ze stanami left, top, width ani height.

    • tabId

      number opcjonalny

      Identyfikator karty, która ma zostać dodana do nowego okna.

    • góra

      number opcjonalny

      Liczba pikseli, o którą nowe okno ma być odsunięte od górnej krawędzi ekranu. Jeśli nie podasz tego argumentu, nowe okno zostanie przesunięte w naturalny sposób względem ostatniego okna, na którym skupiono uwagę. Ta wartość jest ignorowana w przypadku paneli.

    • typ

      CreateType opcjonalne

      Określa typ okna przeglądarki, które ma zostać utworzone.

    • URL

      string | string[] opcjonalnie

      Adres URL lub tablica adresów URL do otwarcia jako karty w oknie. Pełne adresy URL muszą zawierać schemat, np. „http://www.google.com”, a nie „www.google.com”. Niepełne adresy URL są traktowane jako względne w ramach rozszerzenia. Domyślnie jest to strona Nowa karta.

    • szerokość

      number opcjonalny

      Szerokość nowego okna w pikselach, łącznie z ramką. Jeśli nie zostanie określona, domyślnie zostanie użyta naturalna szerokość.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (window?: Window) => void

    • okno

      Window opcjonalny

      Zawiera szczegóły utworzonego okna.

Zwroty

  • Promise<Window | undefined>

    Chrome 88 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

get()

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

Pobiera szczegóły okna.

Parametry

  • windowId

    liczba

  • queryOptions

    QueryOptions opcjonalny

    Chrome 88 lub nowsza
  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (window: Window) => void

Zwroty

  • Promise<Window>

    Chrome 88 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getAll()

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

Pobiera wszystkie okna.

Parametry

  • queryOptions

    QueryOptions opcjonalny

    Chrome 88 lub nowsza
  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (windows: Window[]) => void

Zwroty

  • Promise<Window[]>

    Chrome 88 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getCurrent()

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

Pobiera bieżące okno.

Parametry

  • queryOptions

    QueryOptions opcjonalny

    Chrome 88 lub nowsza
  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (window: Window) => void

Zwroty

  • Promise<Window>

    Chrome 88 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getLastFocused()

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

Pobiera okno, które było ostatnio aktywne – zwykle okno „na wierzchu”.

Parametry

  • queryOptions

    QueryOptions opcjonalny

    Chrome 88 lub nowsza
  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (window: Window) => void

Zwroty

  • Promise<Window>

    Chrome 88 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

remove()

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

Usuwa (zamyka) okno i wszystkie karty w nim otwarte.

Parametry

  • windowId

    liczba

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 88 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

update()

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

Aktualizuje właściwości okna. Określ tylko właściwości, które mają zostać zmienione. Właściwości, które nie zostały określone, pozostaną bez zmian.

Parametry

  • windowId

    liczba

  • updateInfo

    obiekt

    • drawAttention

      wartość logiczna opcjonalna

      Jeśli true, powoduje wyświetlenie okna w sposób, który przyciąga uwagę użytkownika, bez zmiany aktywnego okna. Efekt ten trwa do momentu, gdy użytkownik przełączy się na okno. Ta opcja nie działa, jeśli okno jest już aktywne. Ustaw wartość false, aby anulować poprzednią prośbę drawAttention.

    • skupiony,

      wartość logiczna opcjonalna

      Jeśli true, okno zostanie przeniesione na pierwszy plan. Nie można łączyć ze stanem „zminimalizowane”. Jeśli false, przenosi następne okno w kolejności z do przodu; nie można łączyć ze stanem „pełny ekran” ani „zmaksymalizowany”.

    • wysokość

      number opcjonalny

      Wysokość, do której ma zostać zmieniony rozmiar okna (w pikselach). Ta wartość jest ignorowana w przypadku paneli.

    • w lewo

      number opcjonalny

      Przesunięcie od lewej krawędzi ekranu, na który ma zostać przeniesione okno, w pikselach. Ta wartość jest ignorowana w przypadku paneli.

    • stan

      WindowState opcjonalny

      Nowy stan okna. Stanów „zminimalizowany”, „zmaksymalizowany” i „pełny ekran” nie można łączyć ze stanami „lewy”, „górny”, „szerokość” ani „wysokość”.

    • góra

      number opcjonalny

      Przesunięcie od górnej krawędzi ekranu, na który ma zostać przeniesione okno, w pikselach. Ta wartość jest ignorowana w przypadku paneli.

    • szerokość

      number opcjonalny

      Szerokość, na jaką ma zostać zmieniony rozmiar okna (w pikselach). Ta wartość jest ignorowana w przypadku paneli.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (window: Window) => void

Zwroty

  • Promise<Window>

    Chrome 88 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onBoundsChanged

Chrome w wersji 86 lub nowszej 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Wywoływane, gdy rozmiar okna został zmieniony. To zdarzenie jest wysyłane tylko wtedy, gdy nowe granice zostaną zatwierdzone, a nie w przypadku zmian w trakcie.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (window: Window) => void

onCreated

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

Wywoływane, gdy tworzone jest okno.

Parametry

  • callback

    funkcja

    Chrome 46 lub nowsza

    Parametr callback wygląda tak:

    (window: Window) => void

    • okno

      Okno

      Szczegóły utworzonego przedziału.

  • filtry

    obiekt opcjonalny

    • windowTypes

      WindowType[]

      Warunki, które musi spełniać tworzony typ okna. Domyślnie spełnia warunek ['normal', 'popup'].

onFocusChanged

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

Wyzwalane, gdy zmieni się aktualnie aktywne okno. Zwraca wartość chrome.windows.WINDOW_ID_NONE, jeśli wszystkie okna Chrome utraciły fokus. Uwaga: w przypadku niektórych menedżerów okien w Linuksie znak WINDOW_ID_NONE jest zawsze wysyłany bezpośrednio przed przełączeniem z jednego okna Chrome na inne.

Parametry

  • callback

    funkcja

    Chrome 46 lub nowsza

    Parametr callback wygląda tak:

    (windowId: number) => void

    • windowId

      liczba

      Identyfikator nowo aktywowanego okna.

  • filtry

    obiekt opcjonalny

    • windowTypes

      WindowType[]

      Warunki, które musi spełniać usuwany typ okna. Domyślnie spełnia warunek ['normal', 'popup'].

onRemoved

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

Wywoływane, gdy okno zostanie usunięte (zamknięte).

Parametry

  • callback

    funkcja

    Chrome 46 lub nowsza

    Parametr callback wygląda tak:

    (windowId: number) => void

    • windowId

      liczba

      Identyfikator usuniętego okna.

  • filtry

    obiekt opcjonalny

    • windowTypes

      WindowType[]

      Warunki, które musi spełniać usuwany typ okna. Domyślnie spełnia warunek ['normal', 'popup'].