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.
Plik manifestu
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"],
...
}
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.
Typy
CreateType
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.
Typ wyliczeniowy
"normal"
Określa okno jako standardowe.
"popup"
Określa okno jako wyskakujące okienko.
"panel"
Określa okno jako panel.
QueryOptions
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ówtabs.Tab
. ObiektyTab
zawierają tylko właściwościurl
,pendingUrl
,title
ifavIconUrl
, 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 APIsessions
. -
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 APIsessions
, 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 APIsessions
. -
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 APIsessions
. -
Niestandardowy typ treści
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 APIsessions
.
WindowState
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
.
Typ wyliczeniowy
„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
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
.
Typ wyliczeniowy
"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()
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ślifalse
, 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 nowszychJeś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 wersjePoczątkowy stan okna. Stanów
minimized
,maximized
ifullscreen
nie można łączyć ze stanemleft
,top
,width
aniheight
. -
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.
-
Niestandardowy typ treści
CreateType opcjonalnie
Określa typ okna przeglądarki do utworzenia.
-
URL
string | string[] opcjonalny
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.
-
Zwroty
-
Promise<Window | undefined>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
get()
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
-
okno
-
Zwroty
-
Obietnica<Window>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getAll()
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
-
okna
Okno[]
-
Zwroty
-
Obietnica<Window[]>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getCurrent()
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
-
okno
-
Zwroty
-
Obietnica<Window>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getLastFocused()
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
-
okno
-
Zwroty
-
Obietnica<Window>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
remove()
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
Zwroty
-
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
update()
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 kategoriidrawAttention
. -
skupione
wartość logiczna opcjonalna
Jeśli
true
, powoduje przeniesienie okna na wierzch. Nie można go łączyć ze stanem „zminimalizowany”. Jeślifalse
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
-
okno
-
Zwroty
-
Obietnica<Window>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
Wydarzenia
onBoundsChanged
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
-
okno
-
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
Uruchamiane po utworzeniu okna.
Parametry
-
wywołanie zwrotne
funkcja
Chrome 46 i nowsze wersjeParametr
callback
wygląda tak:(window: Window) => void
-
okno
Szczegóły utworzonego okna.
-
-
filtry
obiekt opcjonalnie
-
windowTypes
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 wersjeParametr
callback
wygląda tak:(windowId: number) => void
-
windowId
Liczba
Identyfikator nowo wybranego okna.
-
-
filtry
obiekt opcjonalnie
-
windowTypes
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 wersjeParametr
callback
wygląda tak:(windowId: number) => void
-
windowId
Liczba
Identyfikator usuniętego okna.
-
-
filtry
obiekt opcjonalnie
-
windowTypes
Warunki, które musi spełniać usuwany typ okna. Domyślnie spełnia wymagania:
['normal', 'popup']
.
-