Description
Utilisez l'API chrome.windows
pour interagir avec les fenêtres du navigateur. Vous pouvez utiliser cette API pour créer, modifier et réorganiser les fenêtres du navigateur.
Autorisations
Lorsqu'il est demandé, un objet windows.Window
contient un tableau d'objets tabs.Tab
. Vous devez déclarer l'autorisation "tabs"
dans votre fichier manifeste si vous avez besoin d'accéder aux propriétés url
, pendingUrl
, title
ou favIconUrl
de tabs.Tab
. Exemple :
{
"name": "My extension",
...
"permissions": ["tabs"],
...
}
Concepts et utilisation
Fenêtre actuelle
De nombreuses fonctions du système d'extensions acceptent un argument windowId
facultatif, qui correspond par défaut à la fenêtre actuelle.
La fenêtre actuelle est celle qui contient le code en cours d'exécution. Il est important de comprendre qu'elle peut être différente de la fenêtre supérieure ou sélectionnée.
Par exemple, supposons qu'une extension crée plusieurs onglets ou fenêtres à partir d'un seul fichier HTML, et que le fichier HTML contient un appel à tabs.query()
. La fenêtre actuelle est celle qui contient la page qui a effectué l'appel, quelle que soit la fenêtre supérieure.
Dans le cas des service workers, la valeur de la fenêtre actuelle revient à la dernière fenêtre active. Dans certains cas, il est possible qu'aucune fenêtre ne s'affiche pour les pages en arrière-plan.
Exemples
Pour essayer cette API, installez l'exemple d'API Windows à partir du dépôt chrome-extension-samples.
![Deux fenêtres, chacune avec un onglet](https://developer.chrome.com/static/docs/extensions/reference/api/windows/images/windows.png?authuser=6&hl=fr)
Types
CreateType
Indique le type de fenêtre de navigateur à créer. "panel" est obsolète et n'est disponible que pour les extensions déjà ajoutées à la liste d'autorisation sur Chrome OS.
Enum
"normal"
Spécifie la fenêtre comme une fenêtre standard.
"popup"
Spécifie la fenêtre comme une fenêtre pop-up.
"panel"
Spécifie la fenêtre en tant que panneau.
QueryOptions
Propriétés
-
populate
Booléen facultatif
Si la valeur est "true", l'objet
windows.Window
possède une propriététabs
qui contient une liste des objetstabs.Tab
. Les objetsTab
ne contiennent les propriétésurl
,pendingUrl
,title
etfavIconUrl
que si le fichier manifeste de l'extension inclut l'autorisation"tabs"
. -
windowTypes
WindowType[] facultatif
S'il est défini, le
windows.Window
renvoyé est filtré en fonction de son type. Si cette règle n'est pas configurée, le filtre par défaut est défini sur['normal', 'popup']
.
Window
Propriétés
-
alwaysOnTop
boolean
Indique si la fenêtre est configurée pour être toujours au premier plan.
-
Concentration
boolean
Indique si la fenêtre est actuellement la fenêtre sélectionnée.
-
taille
numéro facultatif
Hauteur de la fenêtre, cadre compris, en pixels. Dans certains cas, il est possible qu'aucune propriété
height
ne soit attribuée à une fenêtre, par exemple lors d'une requête sur des fenêtres fermées à partir de l'APIsessions
. -
id
numéro facultatif
Identifiant de la fenêtre. Les ID de fenêtre sont uniques au sein d'une session de navigateur. Dans certains cas, aucune propriété
ID
ne peut être attribuée à une fenêtre, par exemple lorsque vous interrogez des fenêtres à l'aide de l'APIsessions
, auquel cas un ID de session peut être présent. -
navigation privée
boolean
Indique si la fenêtre est de navigation privée.
-
à gauche
numéro facultatif
Décalage de la fenêtre par rapport au bord gauche de l'écran en pixels. Dans certains cas, il est possible qu'aucune propriété
left
ne soit attribuée à une fenêtre, par exemple lors d'une requête sur des fenêtres fermées à partir de l'APIsessions
. -
sessionId
string facultatif
ID de session permettant d'identifier de manière unique une fenêtre, obtenu à partir de l'API
sessions
. -
state
WindowState facultatif
État de cette fenêtre du navigateur.
-
onglets
Tabulation[] facultatif
Tableau d'objets
tabs.Tab
représentant les onglets actuels de la fenêtre. -
en haut
numéro facultatif
Décalage de la fenêtre par rapport au bord supérieur de l'écran en pixels. Dans certains cas, il est possible qu'aucune propriété
top
ne soit attribuée à une fenêtre, par exemple lors d'une requête sur des fenêtres fermées à partir de l'APIsessions
. -
Type
WindowType : facultatif
Type de fenêtre de navigateur dont il s'agit.
-
largeur
numéro facultatif
Largeur de la fenêtre, cadre compris, en pixels. Dans certains cas, il est possible qu'aucune propriété
width
ne soit attribuée à une fenêtre, par exemple lors d'une requête sur des fenêtres fermées à partir de l'APIsessions
.
WindowState
État de cette fenêtre du navigateur. Dans certains cas, il est possible qu'aucune propriété state
ne soit attribuée à une fenêtre, par exemple lors d'une requête sur des fenêtres fermées à partir de l'API sessions
.
Enum
"normal"
État de fenêtre normal (pas réduit, agrandi ni plein écran).
"minimized"
État de la fenêtre réduite.
"maximized"
État de la fenêtre agrandie.
"fullscreen"
État de la fenêtre en plein écran.
"locked-fullscreen"
État de la fenêtre en plein écran verrouillée. Cet état plein écran ne peut pas être quitté par une action de l'utilisateur et n'est disponible que pour les extensions ajoutées à la liste d'autorisation sur Chrome OS.
WindowType
Type de fenêtre de navigateur dont il s'agit. Dans certaines circonstances, aucune propriété type
ne peut être attribuée à une fenêtre, par exemple lors d'une requête sur des fenêtres fermées à partir de l'API sessions
.
Enum
"normal"
Une fenêtre de navigateur normale.
"popup"
Une fenêtre pop-up de navigateur.
"panel"
Obsolète dans cette API. Fenêtre de style panneau de l'application Chrome. Les extensions ne peuvent voir que leurs propres fenêtres de panneau.
"app"
Obsolète dans cette API. Fenêtre de l'application Chrome. Les extensions ne peuvent voir que leurs propres fenêtres d'application.
"devtools"
Une fenêtre Outils pour les développeurs.
Propriétés
WINDOW_ID_CURRENT
Valeur windowId qui représente la fenêtre actuelle.
Valeur
-2
WINDOW_ID_NONE
Valeur windowId qui représente l'absence de fenêtre du navigateur Chrome.
Valeur
-1
Méthodes
create()
chrome.windows.create(
createData?: object,
callback?: function,
)
Crée (ouvre) une nouvelle fenêtre de navigateur avec un dimensionnement, une position ou une URL par défaut facultatifs.
Paramètres
-
createData
objet facultatif
-
Concentration
Booléen facultatif
Si la valeur est
true
, une fenêtre active s'ouvre. Si la valeur estfalse
, une fenêtre inactive s'ouvre. -
taille
numéro facultatif
Hauteur de la nouvelle fenêtre, cadre compris, en pixels. Si aucune valeur n'est spécifiée, la valeur par défaut est une hauteur naturelle.
-
navigation privée
Booléen facultatif
Indique si la nouvelle fenêtre doit être une fenêtre de navigation privée.
-
à gauche
numéro facultatif
Nombre de pixels dans lesquels positionner la nouvelle fenêtre à partir du bord gauche de l'écran. Si vous n'indiquez aucune valeur, la nouvelle fenêtre est décalée naturellement par rapport à la dernière fenêtre sélectionnée. Cette valeur est ignorée pour les panneaux.
-
setSelfAsOpener
Booléen facultatif
Chrome 64 ou version ultérieureSi la valeur est
true
, l'élément "window.opener" de la fenêtre nouvellement créée est défini sur l'appelant et se trouve dans la même unité de contextes de navigation associés que l'appelant. -
state
WindowState facultatif
Chrome 44 ou version ultérieureÉtat initial de la fenêtre. Les états
minimized
,maximized
etfullscreen
ne peuvent pas être combinés avecleft
,top
,width
ouheight
. -
tabId
numéro facultatif
ID de l'onglet à ajouter à la nouvelle fenêtre.
-
en haut
numéro facultatif
Nombre de pixels de positionnement de la nouvelle fenêtre à partir du bord supérieur de l'écran. Si vous n'indiquez aucune valeur, la nouvelle fenêtre est décalée naturellement par rapport à la dernière fenêtre sélectionnée. Cette valeur est ignorée pour les panneaux.
-
Type
CreateType facultatif
Indique le type de fenêtre de navigateur à créer.
-
url
string | string[] facultatif
URL ou tableau d'URL à ouvrir dans la fenêtre sous forme d'onglets. Les URL complètes doivent inclure un schéma (par exemple, "http://www.google.com", et non "www.google.com". Les URL non qualifiées sont considérées comme relatives dans l'extension. La page "Nouvel onglet" est utilisée par défaut.
-
largeur
numéro facultatif
Largeur de la nouvelle fenêtre, cadre compris, en pixels. Si aucune valeur n'est spécifiée, la valeur par défaut est une largeur naturelle.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(window?: Window) => void
-
fenêtre
Window (Fenêtre) facultatif
Contient des détails sur la fenêtre créée.
-
Renvoie
-
Promise<Window | undefined>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
Récupère les détails d'une fenêtre.
Paramètres
-
windowId
Nombre
-
queryOptions
QueryOptions facultatif
Chrome 88 et versions ultérieures -
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(window: Window) => void
-
fenêtre
-
Renvoie
-
Promesse<Window>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getAll()
chrome.windows.getAll(
queryOptions?: QueryOptions,
callback?: function,
)
Récupère toutes les fenêtres.
Paramètres
-
queryOptions
QueryOptions facultatif
Chrome 88 et versions ultérieures -
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(windows: Window[]) => void
-
fenêtres
Fenêtre[]
-
Renvoie
-
Promesse<Window[]>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
Récupère la fenêtre actuelle.
Paramètres
-
queryOptions
QueryOptions facultatif
Chrome 88 et versions ultérieures -
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(window: Window) => void
-
fenêtre
-
Renvoie
-
Promesse<Window>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
Récupère la dernière fenêtre sélectionnée, généralement la fenêtre "en haut".
Paramètres
-
queryOptions
QueryOptions facultatif
Chrome 88 et versions ultérieures -
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(window: Window) => void
-
fenêtre
-
Renvoie
-
Promesse<Window>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
Supprime (ferme) une fenêtre et tous les onglets qu'elle contient.
Paramètres
-
windowId
Nombre
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
Met à jour les propriétés d'une fenêtre. Spécifiez uniquement les propriétés à modifier. Les propriétés non spécifiées restent inchangées.
Paramètres
-
windowId
Nombre
-
updateInfo
objet
-
drawAttention
Booléen facultatif
Si la valeur est
true
, la fenêtre s'affiche de manière à attirer l'attention de l'utilisateur, sans modifier la fenêtre sélectionnée. L'effet dure jusqu'à ce que l'utilisateur sélectionne la fenêtre. Cette option n'a aucun effet si la fenêtre est déjà active. Définissez la valeur surfalse
pour annuler une requêtedrawAttention
précédente. -
Concentration
Booléen facultatif
Si la valeur est
true
, la fenêtre s'affiche au premier plan. Elle ne peut pas être combinée avec l'état "minimisé". Si la valeur estfalse
, la fenêtre suivante de l'ordre de plan s'affiche au premier plan. Elle ne peut pas être combinée avec l'état "plein écran" ou "agrandi". -
taille
numéro facultatif
Hauteur de la fenêtre en pixels pour le redimensionnement. Cette valeur est ignorée pour les panneaux.
-
à gauche
numéro facultatif
Décalage à partir du bord gauche de l'écran vers lequel déplacer la fenêtre (en pixels). Cette valeur est ignorée pour les panneaux.
-
state
WindowState facultatif
Nouvel état de la fenêtre. Les états "minimisé", "agrandi" et "plein écran" ne peuvent pas être combinés avec "gauche", "haut", "largeur" ou "hauteur".
-
en haut
numéro facultatif
Décalage à partir du bord supérieur de l'écran vers lequel déplacer la fenêtre, en pixels. Cette valeur est ignorée pour les panneaux.
-
largeur
numéro facultatif
Largeur de redimensionnement de la fenêtre en pixels. Cette valeur est ignorée pour les panneaux.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(window: Window) => void
-
fenêtre
-
Renvoie
-
Promesse<Window>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
Événements
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
Déclenché lorsqu'une fenêtre a été redimensionnée. Cet événement n'est envoyé que lorsque les nouvelles limites sont validées, et non pour les modifications en cours.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(window: Window) => void
-
fenêtre
-
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
Déclenché lors de la création d'une fenêtre
Paramètres
-
rappel
function
Chrome 46 ou version ultérieureLe paramètre
callback
se présente comme suit :(window: Window) => void
-
fenêtre
Détails de la fenêtre créée.
-
-
filtres
objet facultatif
-
windowTypes
Les conditions que le type de fenêtre en cours de création doivent remplir. Par défaut, il répond aux exigences de
['normal', 'popup']
.
-
onFocusChanged
chrome.windows.onFocusChanged.addListener(
callback: function,
filters?: object,
)
Déclenché lorsque la fenêtre actuellement sélectionnée change. Renvoie chrome.windows.WINDOW_ID_NONE
si toutes les fenêtres Chrome ont perdu le focus. Remarque:Dans certains gestionnaires de fenêtres Linux, WINDOW_ID_NONE
est toujours envoyé immédiatement avant le basculement d'une fenêtre Chrome à une autre.
Paramètres
-
rappel
function
Chrome 46 ou version ultérieureLe paramètre
callback
se présente comme suit :(windowId: number) => void
-
windowId
Nombre
ID de la fenêtre sélectionnée.
-
-
filtres
objet facultatif
-
windowTypes
Les conditions que le type de fenêtre à supprimer doivent remplir. Par défaut, il répond aux exigences de
['normal', 'popup']
.
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
Déclenché lorsqu'une fenêtre est supprimée (fermée).
Paramètres
-
rappel
function
Chrome 46 ou version ultérieureLe paramètre
callback
se présente comme suit :(windowId: number) => void
-
windowId
Nombre
ID de la fenêtre supprimée.
-
-
filtres
objet facultatif
-
windowTypes
Les conditions que le type de fenêtre à supprimer doivent remplir. Par défaut, il répond aux exigences de
['normal', 'popup']
.
-