chrome.windows

Opis

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

Uprawnienia

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

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

Pojęcia i zastosowanie

Bieżące okno

Wiele funkcji w systemie rozszerzeń przyjmuje opcjonalny argument windowId, który domyślnie przyjmuje bieżące okno.

Bieżące okno to okno zawierające aktualnie wykonywany kod. Pamiętaj, że ten element może się różnić od okna najwyższego poziomu lub okna zaznaczonego.

Załóżmy na przykład, że rozszerzenie tworzy kilka kart lub okien z pojedynczego pliku HTML, a plik HTML zawiera wywołanie tabs.query(). Bieżące okno to okno zawierające stronę, która wywołała połączenie, niezależnie od tego, jakie jest okno najwyższego poziomu.

W przypadku skryptów service worker wartość bieżącego okna wraca do ostatniego aktywnego okna. W pewnych przypadkach strony w tle mogą nie być widoczne.

Przykłady

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

2 okna, każde z 1 kartą
2 okna, każde z 1 kartą.

Typy

CreateType

Chrome 44 i nowsze wersje

Określa typ okna przeglądarki do utworzenia. Atrybut „panel” został wycofany i jest dostępny tylko w przypadku istniejących rozszerzeń z listy dozwolonych w Chrome OS.

Enum

"normal"
Określa okno jako standardowe.

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

"panel"
Określa okno jako panel.

QueryOptions

Chrome 88 i nowsze wersje

Właściwości

  • wypełnić : uzupełnić

    wartość logiczna opcjonalna

    Jeśli ma wartość prawda, 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 jest ustawiony, zwrócony windows.Window będzie filtrowany na podstawie swojego typu. Jeśli zasada nie jest skonfigurowana, domyślnym filtrem jest ['normal', 'popup'].

Window

Właściwości

  • alwaysOnTop

    boolean

    Określa, czy okno jest ustawione tak, aby zawsze było na górze.

  • skupione

    boolean

    Określa, czy okno jest obecnie aktywne.

  • wysokość

    Liczba opcjonalnie

    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 poziomu interfejsu API sessions.

  • id

    Liczba opcjonalnie

    Identyfikator okna. Identyfikatory okien są unikalne w ramach sesji przeglądarki. W pewnych okolicznościach okno może nie mieć przypisanej właściwości ID, np. podczas wysyłania zapytań dotyczących okien za pomocą interfejsu API sessions, wtedy może być podany identyfikator sesji.

  • incognito

    boolean

    Określa, czy okno jest incognito.

  • lewa

    Liczba opcjonalnie

    Odsunię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 poziomu interfejsu API sessions.

  • sessionId

    ciąg znaków opcjonalny

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

  • state

    WindowState opcjonalnie

    Stan tego okna przeglądarki.

  • karty

    Tab[] opcjonalnie

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

  • góra

    Liczba opcjonalnie

    Odsunię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 poziomu interfejsu API sessions.

  • typ

    WindowType opcjonalnie

    Typ okna przeglądarki.

  • szerokość

    Liczba opcjonalnie

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

WindowState

Chrome 44 i nowsze wersje

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 poziomu interfejsu API sessions.

Enum

„normalny”
Normalny stan okna (bez zminimalizowania, zmaksymalizowania ani pełnego ekranu).

„zminimalizowany”
Zminimalizowany stan okna.

"maximized"
Zmaksymalizowany stan okna.

"pełnoekranowy"
Stan okna pełnoekranowego.

"locked-fullscreen"
zablokowane okno pełnoekranowe. Z tego stanu nie można wyjść w wyniku działania użytkownika. Ten tryb jest dostępny tylko w przypadku rozszerzeń znajdujących się na liście dozwolonych w Chrome OS.

WindowType

Chrome 44 i nowsze wersje

Typ tego typu okna przeglądarki. W niektórych przypadkach do okna może nie być przypisana właściwość type, np. podczas wysyłania zapytań o zamknięte okna z poziomu interfejsu API sessions.

Enum

"normal"
Zwykłe okno przeglądarki.

"wyskakujące okienko"
Wyskakujące okienko przeglądarki.

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

"app"
Wycofany w tym interfejsie API. Okno aplikacji Chrome. Rozszerzenia widzą tylko własne okna swojej aplikacji.

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

Właściwości

WINDOW_ID_CURRENT

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

Wartość

–2

WINDOW_ID_NONE

Wartość windowId reprezentująca brak okna przeglądarki Chrome.

Wartość

–1

Metody

create()

Obietnica 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

Tworzy (otwiera) nowe okno przeglądarki z dowolnym podanym opcjonalnym rozmiarem, położeniem lub domyślnym adresem URL.

Parametry

  • createData

    obiekt opcjonalnie

    • skupione

      wartość logiczna opcjonalna

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

    • wysokość

      Liczba opcjonalnie

      Wysokość nowego okna (w tym klatkę) w pikselach. Jeśli nie podasz żadnej wartości, domyślnie zostanie użyta wysokość naturalna.

    • incognito

      wartość logiczna opcjonalna

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

    • lewa

      Liczba opcjonalnie

      Liczba pikseli odsunięcia nowego okna od lewej krawędzi ekranu. Jeśli nie podasz żadnej wartości, nowe okno zostanie automatycznie przesunięte względem ostatniego aktywnego okna. Ta wartość jest ignorowana w przypadku paneli.

    • setSelfAsOpener

      wartość logiczna opcjonalna

      Chrome w wersji 64 i nowszych

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

    • state

      WindowState opcjonalnie

      Chrome 44 i nowsze wersje

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

    • tabId

      Liczba opcjonalnie

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

    • góra

      Liczba opcjonalnie

      Liczba pikseli odsunięcia nowego okna od górnej krawędzi ekranu. Jeśli nie podasz żadnej wartości, nowe okno zostanie automatycznie przesunięte względem ostatniego aktywnego okna. Ta wartość jest ignorowana w przypadku paneli.

    • typ

      CreateType opcjonalnie

      Określa typ okna przeglądarki do utworzenia.

    • URL

      string|string[] optional

      Adres URL lub tablica adresów URL do otwierania jako kart w oknie. Pełne adresy URL muszą zawierać schemat, np. „http://www.google.com”, a nie „www.google.com”. Niepełne adresy URL są uznawane w rozszerzeniu za względne. Domyślna strona to strona nowej karty.

    • szerokość

      Liczba opcjonalnie

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (window?: Window)=>void

    • okno

      Okno opcjonalnie

      Zawiera informacje o utworzonym oknie.

Akcje powrotne

  • Obietnica<okno|undefined>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

get()

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

Pobiera szczegółowe informacje o oknie.

Parametry

  • windowId

    Liczba

  • queryOptions

    Opcjonalne QueryOptions

    Chrome 88 i nowsze wersje
  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (window: Window)=>void

Akcje powrotne

  • Obietnica<Window>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAll()

Obietnica 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

Pobiera wszystkie okna.

Parametry

  • queryOptions

    Opcjonalne QueryOptions

    Chrome 88 i nowsze wersje
  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (windows: Window[])=>void

Akcje powrotne

  • Obietnica<Window[]>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getCurrent()

Obietnica 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

Pobiera bieżące okno.

Parametry

  • queryOptions

    Opcjonalne QueryOptions

    Chrome 88 i nowsze wersje
  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (window: Window)=>void

Akcje powrotne

  • Obietnica<Window>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getLastFocused()

Obietnica 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

Pobiera ostatnio zaznaczone okno – zwykle jest ono „na górze”.

Parametry

  • queryOptions

    Opcjonalne QueryOptions

    Chrome 88 i nowsze wersje
  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (window: Window)=>void

Akcje powrotne

  • Obietnica<Window>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

remove()

Obietnica 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

Parametry

  • windowId

    Liczba

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

update()

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

Aktualizuje właściwości okna. Określ tylko właściwości, które mają zostać zmienione. Właściwości nieokreślone pozostają niezmienione.

Parametry

  • windowId

    Liczba

  • updateInfo

    obiekt

    • drawAttention

      wartość logiczna opcjonalna

      Jeśli true, powoduje, że okno wyświetla się w sposób, który przyciąga uwagę użytkownika, bez zmiany aktywnego okna. Efekt będzie działać, dopóki użytkownik nie zmieni zaznaczenia okna. Ta opcja nie działa, jeśli okno jest już zaznaczone. Ustaw wartość false, aby anulować poprzednią prośbę o dodanie do kategorii drawAttention.

    • skupione

      wartość logiczna opcjonalna

      Jeśli true, powoduje przeniesienie okna na wierzch. Nie można go łączyć ze stanem „zminimalizowany”. Jeśli false przenosi następne okno na początek, w kolejności Z. Nie można go łączyć ze stanem „pełny ekran” ani „zmaksymalizowane”.

    • wysokość

      Liczba opcjonalnie

      Wysokość okna, do której ma zostać powiększone okno, w pikselach. Ta wartość jest ignorowana w przypadku paneli.

    • lewa

      Liczba opcjonalnie

      Odsunięcie okna od lewej krawędzi ekranu (w pikselach), o które ma ono zostać przesuwane. Ta wartość jest ignorowana w przypadku paneli.

    • state

      WindowState opcjonalnie

      Nowy stan okna. Stany „zminimalizowany”, „zmaksymalizowany” i „pełnoekranowy” nie mogą być łączone z wartościami „left”, „top”, „width” ani „height”.

    • góra

      Liczba opcjonalnie

      Odsunięcie okna od górnej krawędzi ekranu (w pikselach), o które ma ono zostać przesuwane. Ta wartość jest ignorowana w przypadku paneli.

    • szerokość

      Liczba opcjonalnie

      Szerokość okna, do którego ma być dostosowywana wartość w pikselach. Ta wartość jest ignorowana w przypadku paneli.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (window: Window)=>void

Akcje powrotne

  • Obietnica<Window>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onBoundsChanged

Chrome 86 i nowsze wersje 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Uruchamiane po zmianie rozmiaru okna. To zdarzenie jest wysyłane tylko po zatwierdzeniu nowych progów, a nie w przypadku zmian w toku.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (window: Window)=>void

onCreated

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

Uruchamiane po utworzeniu okna.

Parametry

  • wywołanie zwrotne

    funkcja

    Chrome 46 i nowsze wersje

    Parametr callback wygląda tak: 

    (window: Window)=>void

    • okno

      Okno

      Szczegóły utworzonego okna.

  • filtry

    obiekt opcjonalnie

    • windowTypes

      WindowType[]

      Warunki, które muszą spełniać typ tworzonego okna. Domyślnie spełnia wymagania: ['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 przestały być aktywne. Uwaga: w niektórych menedżerach okien w Linuksie obiekt WINDOW_ID_NONE jest zawsze wysyłany bezpośrednio przed przejściem z jednego okna Chrome do drugiego.

Parametry

  • wywołanie zwrotne

    funkcja

    Chrome 46 i nowsze wersje

    Parametr callback wygląda tak: 

    (windowId: number)=>void

    • windowId

      Liczba

      Identyfikator nowo wybranego okna.

  • filtry

    obiekt opcjonalnie

    • windowTypes

      WindowType[]

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

onRemoved

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

Uruchamiane, gdy okno zostało usunięte (zamknięte).

Parametry

  • wywołanie zwrotne

    funkcja

    Chrome 46 i nowsze wersje

    Parametr callback wygląda tak: 

    (windowId: number)=>void

    • windowId

      Liczba

      Identyfikator usuniętego okna.

  • filtry

    obiekt opcjonalnie

    • windowTypes

      WindowType[]

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