chrome.windows

refresh date: 2026-09-25 robots: noindex

Opis

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

Plik manifestu

W odpowiedzi na żądanie windows.Window zawiera tablicę obiektów tabs.Tab. Jeśli potrzebujesz dostępu do właściwości url, pendingUrl, title lub favIconUrl interfejsu 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. Pamiętaj, że może to być inne okno niż to, które jest na samej górze lub jest aktywne.

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

W przypadku skryptów service worker wartość bieżącego okna jest przywracana do ostatniego aktywnego okna. W niektórych okolicznościach może nie być bieżącego okna dla stron działających w tle.

Przykłady

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

Typy

CreateType

Chrome 44 lub nowsza wersja

Określa typ okna przeglądarki, które ma zostać utworzone. Wartość „panel” została wycofana i jest dostępna tylko w przypadku rozszerzeń, które znajdują się już na liście dozwolonych w ChromeOS.

Typ wyliczeniowy

"normal"
Określa okno jako standardowe.

"popup"
Określa okno jako wyskakujące okienko.

"panel"
Określa okno jako panel.

QueryOptions

Chrome 88 lub nowsza wersja

Właściwości

• wypełnić : uzupełnić

  boolean opcjonalne

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

• windowTypes

  WindowType[] opcjonalny

  Jeśli ta opcja jest ustawiona, zwracany obiekt windows.Window jest filtrowany na podstawie typu. Jeśli nie określisz tego ustawienia, domyślny filtr to ['normal', 'popup'].

Window

Właściwości

• alwaysOnTop

  wartość logiczna

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

• skupienie

  wartość logiczna

  Określa, czy okno jest obecnie aktywne.

• wysokość

  number optional

  Wysokość okna, w tym ramki, w pikselach. W niektórych przypadkach okno może nie mieć przypisanej właściwości height, np. podczas wysyłania zapytania o zamknięte okna z interfejsu API sessions.

• id

  number optional

  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ń do okien za pomocą interfejsu API sessions. W takiej sytuacji może być obecny identyfikator sesji.

• incognito

  wartość logiczna

  Określa, czy okno jest w trybie incognito.

• w lewo

  number optional

  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 zapytania o zamknięte okna z interfejsu API sessions.

• sessionId

  ciąg znaków opcjonalny

  Identyfikator sesji używany do jednoznacznej identyfikacji okna, uzyskany z interfejsu API sessions.

• stan

  WindowState opcjonalne

  Stan tego okna przeglądarki.

• tabulatory

  Tab[] opcjonalny

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

• góra

  number optional

  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 zapytania o zamknięte okna z interfejsu API sessions.

• typ

  WindowType opcjonalny

  Typ okna przeglądarki.

• szerokość

  number optional

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

WindowState

Chrome 44 lub nowsza wersja

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

Typ wyliczeniowy

"normal"
Normalny stan okna (nie zminimalizowane, zmaksymalizowane ani pełnoekranowe).

"minimized"
Okno jest zminimalizowane.

"maximized"
Stan zmaksymalizowanego okna.

"fullscreen"
Stan okna pełnoekranowego.

WindowType

Chrome 44 lub nowsza wersja

Typ okna przeglądarki. W niektórych przypadkach oknu może nie zostać przypisana właściwość type, na przykład podczas wysyłania zapytania o zamknięte okna z interfejsu API sessions.

Typ wyliczeniowy

"normal"
Zwykłe okno przeglądarki.

"popup"
Wyskakujące okienko przeglądarki.

"panel"
Wycofane w tym interfejsie API. Okno aplikacji Chrome w stylu panelu. Rozszerzenia widzą tylko własne okna paneli.

"app"
Wycofane w tym interfejsie API. Okno aplikacji Chrome. Rozszerzenia widzą tylko okna własnej aplikacji.

"devtools"
Okno narzędzi dla programistów.

Właściwości

WINDOW_ID_CURRENT

Wartość windowId, która reprezentuje bieżące okno.

Wartość

-2

WINDOW_ID_NONE

Wartość windowId, która reprezentuje 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 opcjonalnym rozmiarem, pozycją lub domyślnym adresem URL.

Parametry

• createData

  object opcjonalny

  • skupienie

    boolean opcjonalne

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

  • wysokość

    number optional

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

  • incognito

    boolean opcjonalne

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

  • w lewo

    number optional

    Liczba pikseli, o jaką nowe okno ma być przesunięte względem lewej krawędzi ekranu. Jeśli nie określisz tej wartości, nowe okno zostanie przesunięte w naturalny sposób względem ostatniego aktywnego okna. W przypadku paneli ta wartość jest ignorowana.

  • setSelfAsOpener

    boolean opcjonalne

    Chrome 64 lub nowsza wersja

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

  • stan

    WindowState opcjonalne

    Chrome 44 lub nowsza wersja

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

  • tabId

    number optional

    Identyfikator karty, którą chcesz dodać do nowego okna.

  • góra

    number optional

    Liczba pikseli, o którą nowe okno ma być odsunięte od górnej krawędzi ekranu. Jeśli nie określisz tej wartości, nowe okno zostanie przesunięte w naturalny sposób względem ostatniego aktywnego okna. W przypadku paneli ta wartość jest ignorowana.

  • 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, które mają zostać otwarte jako karty w oknie. Pełne i jednoznaczne adresy URL muszą zawierać schemat, np. „http://www.google.com”, a nie „www.google.com”. Adresy URL, które nie są pełne i jednoznaczne, są traktowane jako względne w rozszerzeniu. Domyślnie jest to strona nowej karty.

  • szerokość

    number optional

    Szerokość nowego okna w pikselach, w tym ramki. Jeśli nie podasz tu żadnej wartości, zostanie użyta domyślna szerokość.

• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (window?: Window) => void

  • okno

    Window opcjonalny

    Zawiera szczegółowe informacje o utworzonym oknie.

Zwroty

• Promise<Window | undefined>

  Chrome 88 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

get()

Obietnica

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

Pobiera szczegółowe informacje o oknie.

Parametry

• windowId

  liczba

• queryOptions

  QueryOptions opcjonalny

  Chrome 88 lub nowsza wersja
• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (window: Window) => void

  • okno

    Okno

Zwroty

• Promise<Window>

  Chrome 88 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy 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 wersja
• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (windows: Window[]) => void

  • okna

    Window[]

Zwroty

• Promise<Window[]>

  Chrome 88 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy 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 wersja
• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (window: Window) => void

  • okno

    Okno

Zwroty

• Promise<Window>

  Chrome 88 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy 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 górze”.

Parametry

• queryOptions

  QueryOptions opcjonalny

  Chrome 88 lub nowsza wersja
• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (window: Window) => void

  • okno

    Okno

Zwroty

• Promise<Window>

  Chrome 88 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

remove()

Obietnica

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

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

Parametry

• windowId

  liczba

• callback

  function opcjonalne

  Parametr callback wygląda tak:

  () => void

Zwroty

• thought Promise<void>

  Chrome 88 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy 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 te właściwości, które mają zostać zmienione. Nieokreślone właściwości pozostaną bez zmian.

Parametry

• windowId

  liczba

• updateInfo

  obiekt

  • drawAttention

    boolean opcjonalne

    Jeśli wartość to true, okno jest wyświetlane w sposób, który przyciąga uwagę użytkownika, ale nie zmienia aktywnego okna. Efekt utrzymuje się, dopóki użytkownik nie 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.

  • skupienie

    boolean opcjonalne

    Jeśli true, przenosi okno na pierwszy plan; nie można połączyć ze stanem „minimized”. Jeśli false, przenosi następne okno w kolejności osi Z na pierwszy plan; nie można łączyć ze stanem „fullscreen” ani „maximized”.

  • wysokość

    number optional

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

  • w lewo

    number optional

    Przesunięcie od lewej krawędzi ekranu, do którego ma zostać przeniesione okno (w pikselach). W przypadku paneli ta wartość jest ignorowana.

  • stan

    WindowState opcjonalne

    Nowy stan okna. Stanów „zminimalizowany”, „zmaksymalizowany” i „pełny ekran” nie można łączyć z wartościami „left”, „top”, „width” ani „height”.

  • góra

    number optional

    Przesunięcie od górnej krawędzi ekranu, do którego ma zostać przeniesione okno (w pikselach). W przypadku paneli ta wartość jest ignorowana.

  • szerokość

    number optional

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

• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (window: Window) => void

  • okno

    Okno

Zwroty

• Promise<Window>

  Chrome 88 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onBoundsChanged

Chrome 86 lub nowsza wersja

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

Uruchamiane, gdy rozmiar okna został zmieniony. To zdarzenie jest wysyłane tylko wtedy, gdy nowe granice zostały zatwierdzone, a nie w przypadku zmian w toku.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (window: Window) => void

  • okno

    Okno

onCreated

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

Uruchamiane po utworzeniu okna.

Parametry

• callback

  funkcja

  Chrome 46 lub nowsza wersja

  Parametr callback wygląda tak:

  (window: Window) => void

  • okno

    Okno

    Szczegóły utworzonego okna.

• filtry

  object opcjonalny

  • windowTypes

    WindowType[]

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

onFocusChanged

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

Uruchamiane, gdy zmienia się aktualnie aktywne okno. Zwraca wartość chrome.windows.WINDOW_ID_NONE, jeśli wszystkie okna Chrome utraciły zaznaczenie. Uwaga: w przypadku niektórych menedżerów okien w systemie Linux klawisz 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 wersja

  Parametr callback wygląda tak:

  (windowId: number) => void

  • windowId

    liczba

    Identyfikator okna, które właśnie zostało aktywowane.

• filtry

  object opcjonalny

  • windowTypes

    WindowType[]

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

onRemoved

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

Uruchamiane po usunięciu (zamknięciu) okna.

Parametry

• callback

  funkcja

  Chrome 46 lub nowsza wersja

  Parametr callback wygląda tak:

  (windowId: number) => void

  • windowId

    liczba

    Identyfikator usuniętego okna.

• filtry

  object opcjonalny

  • windowTypes

    WindowType[]

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