chrome.windows

Opis

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

Uprawnienia

Na żądanie windows.Window zawiera tablicę obiektów tabs.Tab. Musisz zadeklaruj w manifeście uprawnienia "tabs", jeśli potrzebujesz dostępu do url, pendingUrl, title i favIconUrl wartości tabs.Tab. Na przykład:

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

Pojęcia i wykorzystanie

Bieżące okno

Wiele funkcji w systemie rozszerzeń przyjmuje opcjonalny argument windowId, który domyślnie przyjmuje wartość w bieżącym oknie.

Bieżące okno to okno zawierające wykonywany obecnie kod. Jest pamiętaj, że może się ono różnić od okna najwyższego lub najwyższego poziomu.

Jeśli na przykład rozszerzenie tworzy kilka kart lub okien z jednego pliku HTML, a rozszerzenie Plik HTML zawiera wywołanie tabs.query(). Bieżące okno to okno zawierające stronę, na której wykonano połączenie, niezależnie od tego, które okno znajduje się najwyżej.

W przypadku skryptów service worker bieżący okres wraca do ostatniego aktywnego okna. okno. W niektórych okolicznościach bieżące okno stron działających w tle może być niedostępne.

Przykłady

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

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

Typy

CreateType

Chrome w wersji 44 lub nowszej .

Określa typ okna przeglądarki do utworzenia. panel została wycofana i jest dostępna tylko dla istniejących rozszerzeń na liście dozwolonych w Chrome OS.

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 i nowsze .

Właściwości

  • wypełnić : uzupełnić

    Wartość logiczna opcjonalna

    Jeśli wartość to prawda, 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 jest ustawiony, zwracana wartość windows.Window jest filtrowana na podstawie typu. Jeśli zasada jest nieskonfigurowana, domyślnym filtrem jest ['normal', 'popup'].

Window

Właściwości

  • alwaysOnTop

    wartość logiczna

    Określa, czy okno ma być zawsze na górze.

  • skupiony

    wartość logiczna

    Określa, czy okno jest obecnie zaznaczone.

  • 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. na przykład w przypadku zapytań dotyczących zamkniętych okien za pomocą interfejsu API sessions.

  • id

    liczba opcjonalnie

    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. na przykład podczas wysyłania zapytań do okien przy użyciu interfejsu API sessions – w takim przypadku może być obecny identyfikator sesji.

  • incognito

    wartość logiczna

    Określa, czy okno jest w trybie incognito.

  • w lewo

    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. na przykład w przypadku zapytań dotyczących zamkniętych okien za pomocą interfejsu API sessions.

  • sessionId

    ciąg znaków opcjonalny

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

  • stan

    Opcjonalny WindowState

    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. na przykład w przypadku zapytań dotyczących zamkniętych okien za pomocą interfejsu API sessions.

  • typ

    Opcjonalny WindowType

    Typ okna przeglądarki.

  • szerokość

    liczba opcjonalnie

    Szerokość okna wraz z ramką (w pikselach). W niektórych przypadkach okno może nie mieć przypisanej właściwości width. na przykład w przypadku zapytań dotyczących zamkniętych okien za pomocą interfejsu API sessions.

WindowState

Chrome w wersji 44 lub nowszej .

Stan tego okna przeglądarki. W niektórych przypadkach okno może nie mieć przypisanej właściwości state. na przykład w przypadku zapytań dotyczących zamkniętych okien za pomocą interfejsu API sessions.

Typ wyliczeniowy

"normal"
Normalny stan okna (nie zminimalizowany, zmaksymalizowany ani pełny ekran).

„zminimalizowany”
Stan zminimalizowanego okna.

"zmaksymalizowany"
stan zmaksymalizowanego okna.

"fullscreen"
Stan pełnego ekranu.

"locked-fullscreen"
Zablokowany stan okna pełnego ekranu. Z tego stanu pełnego ekranu nie można wyjść przez działanie użytkownika. Jest on dostępny tylko w przypadku rozszerzeń z listy dozwolonych w Chrome OS.

WindowType

Chrome w wersji 44 lub nowszej .

Typ okna przeglądarki. W niektórych przypadkach okno może nie mieć przypisanej właściwości type. na przykład w przypadku zapytań dotyczących zamkniętych okien za pomocą interfejsu API sessions.

Typ wyliczeniowy

"normal"
Normalne okno przeglądarki.

"popup"
Wyskakujące okienko przeglądarki.

"panel"
Wycofano w tym interfejsie API. Okno stylizowane na panel aplikacji Chrome. Rozszerzenia widzą tylko własne okna paneli.

"app"
Wycofano w tym interfejsie API. Okno aplikacji Chrome. Rozszerzenia widzą tylko własne okna 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 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 dowolnymi opcjonalnymi rozmiarami, położeniem i 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ść

      liczba opcjonalnie

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

    • incognito

      Wartość logiczna opcjonalna

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

    • w lewo

      liczba opcjonalnie

      Liczba pikseli, w których znajduje się nowe okno od lewej krawędzi ekranu. Jeśli nie określono tego ustawienia, nowe okno zostanie odsunięte naturalnie od ostatniego zaznaczonego okna. Ta wartość jest ignorowana w przypadku paneli.

    • setSelfAsOpener

      Wartość logiczna opcjonalna

      Chrome w wersji 64 lub nowszej .

      Jeśli true, parametr „window.opener” nowo utworzonego okna jest ustawiony na element wywołujący i należy do tej samej jednostki powiązanych kontekstów przeglądania co element wywołujący.

    • stan

      Opcjonalny WindowState

      Chrome w wersji 44 lub nowszej .

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

    • tabId

      liczba opcjonalnie

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

    • góra

      liczba opcjonalnie

      Liczba pikseli, w których znajduje się nowe okno od górnej krawędzi ekranu. Jeśli nie określono tego ustawienia, nowe okno zostanie odsunięte naturalnie od ostatniego zaznaczonego okna. Ta wartość jest ignorowana w przypadku paneli.

    • typ

      Opcjonalny CreateType

      Określa typ okna przeglądarki do utworzenia.

    • URL

      string | string[] opcjonalnie

      Adres URL lub tablica adresów URL, które mają być otwierane 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ą uznawane w rozszerzeniu za względne. Domyślnie jest to strona nowej karty.

    • szerokość

      liczba opcjonalnie

      Szerokość nowego okna z ramką w pikselach. Jeśli nie podasz żadnej wartości, zostanie użyta domyślna szerokość naturalna.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (window?: Window) => void

    • okno

      Okno opcjonalne

      Zawiera szczegółowe informacje o utworzonym oknie.

Zwroty

  • Promise<Window | niezdefiniowane>

    Chrome 88 i nowsze .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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óły okna.

Parametry

  • windowId

    liczba

  • queryOptions

    Opcjonalne QueryOptions

    Chrome 88 i nowsze .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (window: Window) => void

Zwroty

  • Promise<Window>

    Chrome 88 i nowsze .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (windows: Window[]) => void

Zwroty

  • Promise<Window[]>

    Chrome 88 i nowsze .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (window: Window) => void

Zwroty

  • Promise<Window>

    Chrome 88 i nowsze .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 to okno „Na górze”.

Parametry

  • queryOptions

    Opcjonalne QueryOptions

    Chrome 88 i nowsze .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (window: Window) => void

Zwroty

  • Promise<Window>

    Chrome 88 i nowsze .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 znajdujące się w nim karty.

Parametry

  • windowId

    liczba

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome 88 i nowsze .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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ślać tylko właściwości do zmiany; nieokreślone właściwości pozostaną niezmienione.

Parametry

  • windowId

    liczba

  • updateInfo

    Obiekt

    • drawAttention

      Wartość logiczna opcjonalna

      Jeśli zasada ma wartość true, okno wyświetla się w sposób, który przyciąga uwagę użytkownika do okna, ale nie zmienia zaznaczonego 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 jako false, aby anulować poprzednią prośbę o drawAttention.

    • skupiony

      Wartość logiczna opcjonalna

      Jeśli true, przenosi okno na wierzch; nie można łączyć ze stanem „zminimalizowany”. Jeśli false, przenosi następne okno na wierzch zgodnie ze właściwością Z. nie można łączyć ze stanem „pełnoekranowy” lub „zmaksymalizowane”.

    • wysokość

      liczba opcjonalnie

      Wysokość w pikselach, do której należy zmienić rozmiar okna. Ta wartość jest ignorowana w przypadku paneli.

    • w lewo

      liczba opcjonalnie

      Przesunięcie okna od lewej krawędzi ekranu (w pikselach). Ta wartość jest ignorowana w przypadku paneli.

    • stan

      Opcjonalny WindowState

      Nowy stan okna. „Zminimalizowane”, „zmaksymalizowane” i „pełnoekranowe” stanów nie można łączyć z wartościami „left”, „top”, „width” i „height”.

    • góra

      liczba opcjonalnie

      Przesunięcie okna od górnej krawędzi ekranu (w pikselach). Ta wartość jest ignorowana w przypadku paneli.

    • szerokość

      liczba opcjonalnie

      Szerokość w pikselach, pod jaką zmienia się rozmiar okna. Ta wartość jest ignorowana w przypadku paneli.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (window: Window) => void

Zwroty

  • Promise&lt;Window&gt;

    Chrome 88 i nowsze .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onBoundsChanged

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

Uruchamiane po zmianie rozmiaru okna. to zdarzenie jest wysyłane tylko po zatwierdzeniu nowych granic, 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 w wersji 46 lub nowszej, .

    Parametr callback wygląda tak: 

    (window: Window) => void

    • okno

      Okno

      Szczegóły utworzonego okna.

  • filtry

    obiekt opcjonalny

    • windowTypes

      WindowType[]

      Warunki, które muszą być spełnione przez tworzone okno. Domyślnie spełnia wymogi ['normal', 'popup'].

onFocusChanged

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

Uruchamiane po zmianie aktualnie zaznaczonego okna. Zwraca wartość chrome.windows.WINDOW_ID_NONE, jeśli wszystkie okna Chrome są nieaktywne. Uwaga: w przypadku niektórych menedżerów okien z Linuksem okno WINDOW_ID_NONE jest zawsze wysyłane bezpośrednio przed przejściem z jednego okna Chrome do innego.

Parametry

  • wywołanie zwrotne

    funkcja

    Chrome w wersji 46 lub nowszej, .

    Parametr callback wygląda tak: 

    (windowId: number) => void

    • windowId

      liczba

      Identyfikator nowego okna.

  • filtry

    obiekt opcjonalny

    • windowTypes

      WindowType[]

      Warunki, które muszą być spełnione przez usuwany typ okna. Domyślnie spełnia wymogi ['normal', 'popup'].

onRemoved

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

Uruchamiane, gdy okno zostanie usunięte (zamknięte).

Parametry

  • wywołanie zwrotne

    funkcja

    Chrome w wersji 46 lub nowszej, .

    Parametr callback wygląda tak: 

    (windowId: number) => void

    • windowId

      liczba

      Identyfikator usuniętego okna.

  • filtry

    obiekt opcjonalny

    • windowTypes

      WindowType[]

      Warunki, które muszą być spełnione przez usuwany typ okna. Domyślnie spełnia wymogi ['normal', 'popup'].