chrome.windows

refresh date: 2026-09-25 robots: noindex

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 des fenêtres dans le navigateur.

Fichier manifeste

Lorsqu'il est demandé, un 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"],
  ...
}

La fenêtre actuelle

De nombreuses fonctions du système d'extension 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 que cette fenêtre peut être différente de la fenêtre située au premier plan ou de celle qui est sélectionnée.

Par exemple, supposons qu'une extension crée quelques onglets ou fenêtres à partir d'un seul fichier HTML et que ce fichier HTML contienne un appel à tabs.query(). La fenêtre actuelle est celle qui contient la page à l'origine de l'appel, quelle que soit la fenêtre située au premier plan.

Dans le cas des service workers, la valeur de la fenêtre actuelle est remplacée par la dernière fenêtre active. Dans certains cas, il se peut qu'il n'y ait pas de fenêtre active pour les pages d'arrière-plan.

Exemples

Pour essayer cette API, installez l'exemple d'API Windows à partir du dépôt chrome-extension-samples.

Types

CreateType

Chrome 44 ou version ultérieure

Spécifie le type de fenêtre de navigateur à créer. "panel" est obsolète et n'est disponible que pour les extensions existantes sur la liste d'autorisation sur ChromeOS.

Énumération

"normal"
Spécifie la fenêtre comme une fenêtre standard.

"popup"
Spécifie la fenêtre en tant que fenêtre pop-up.

"panel"
Spécifie la fenêtre en tant que panneau.

QueryOptions

Chrome 88 ou version ultérieure

Propriétés

• populate

  boolean facultatif

  Si la valeur est "true", l'objet windows.Window possède une propriété tabs qui contient une liste des objets tabs.Tab. Les objets Tab ne contiennent les propriétés url, pendingUrl, title et favIconUrl que si le fichier manifeste de l'extension inclut l'autorisation "tabs".

• windowTypes

  WindowType[] facultatif

  Si ce champ est défini, l'élément windows.Window renvoyé est filtré en fonction de son type. Si ce champ n'est pas défini, le filtre par défaut est défini sur ['normal', 'popup'].

Window

Propriétés

• alwaysOnTop

  booléen

  Indique si la fenêtre est configurée pour être toujours au premier plan.

• Concentration

  booléen

  Indique si la fenêtre est actuellement sélectionnée.

• height

  number facultatif

  Hauteur de la fenêtre, y compris le cadre, en pixels. Dans certains cas, il est possible qu'aucune propriété height ne soit attribuée à une fenêtre, par exemple lorsque vous interrogez des fenêtres fermées à l'aide de l'API sessions.

• id

  number facultatif

  ID de la fenêtre. Les ID de fenêtre sont uniques au sein d'une session de navigateur. Dans certains cas, il est possible qu'une fenêtre ne soit pas associée à une propriété ID, par exemple lors de l'interrogation de fenêtres à l'aide de l'API sessions. Dans ce cas, un ID de session peut être présent.

• navigation privée

  booléen

  Indique si la fenêtre est en mode navigation privée.

• gauche

  number 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 lorsque vous interrogez des fenêtres fermées à l'aide de l'API sessions.

• sessionId

  chaîne facultatif

  ID de session utilisé pour identifier une fenêtre de manière unique, obtenu à partir de l'API sessions.

• state

  WindowState facultatif

  État de cette fenêtre de navigateur.

• tabs

  Tab[] facultatif

  Tableau d'objets tabs.Tab représentant les onglets actuels de la fenêtre.

• top

  number 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 lorsque vous interrogez des fenêtres fermées à l'aide de l'API sessions.

• type

  WindowType facultatif

  Type de fenêtre de navigateur.

• width

  number facultatif

  Largeur de la fenêtre, y compris le cadre, en pixels. Dans certains cas, il est possible qu'aucune propriété width ne soit attribuée à une fenêtre, par exemple lorsque vous interrogez des fenêtres fermées à l'aide de l'API sessions.

WindowState

Chrome 44 ou version ultérieure

État de cette fenêtre de navigateur. Dans certains cas, il est possible qu'aucune propriété state ne soit attribuée à une fenêtre, par exemple lorsque vous interrogez des fenêtres fermées à l'aide de l'API sessions.

Énumération

"normal"
État normal de la fenêtre (ni réduite, ni agrandie, ni en 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.

WindowType

Chrome 44 ou version ultérieure

Type de fenêtre de navigateur. Dans certains cas, une fenêtre peut ne pas se voir attribuer de propriété type, par exemple lors de l'interrogation de fenêtres fermées à partir de l'API sessions.

Énumération

"normal"
Fenêtre de navigateur normale.

"popup"
Un pop-up de navigateur.

"panel"
Obsolète dans cette API. Fenêtre de style panneau d'une application Chrome. Les extensions ne peuvent voir que leurs propres fenêtres de panneau.

"app"
Obsolète dans cette API. Une fenêtre d'application Chrome. Les extensions ne peuvent voir que les fenêtres de leur propre application.

"devtools"
Fenêtre d'outils pour les développeurs.

Propriétés

WINDOW_ID_CURRENT

La valeur windowId qui représente la fenêtre actuelle.

Valeur

-2

WINDOW_ID_NONE

Valeur windowId qui représente l'absence d'une fenêtre du navigateur Chrome.

Valeur

-1

Méthodes

create()

Promise

chrome.windows.create(
  createData?: object,
  callback?: function,
): Promise<Window | undefined>

Crée (ouvre) une fenêtre de navigateur avec les paramètres facultatifs de taille, de position ou d'URL par défaut fournis.

Paramètres

• createData

  objet facultatif

  • Concentration

    boolean facultatif

    Si true, ouvre une fenêtre active. Si la valeur est false, ouvre une fenêtre inactive.

  • height

    number facultatif

    Hauteur en pixels de la nouvelle fenêtre, cadre compris. Si aucune valeur n'est spécifiée, la valeur par défaut est une hauteur naturelle.

  • navigation privée

    boolean facultatif

    Indique si la nouvelle fenêtre doit être une fenêtre de navigation privée.

  • gauche

    number facultatif

    Nombre de pixels pour positionner la nouvelle fenêtre à partir du bord gauche de l'écran. Si elle n'est pas spécifiée, la nouvelle fenêtre est décalée naturellement par rapport à la dernière fenêtre active. Cette valeur est ignorée pour les panneaux.

  • setSelfAsOpener

    boolean facultatif

    Chrome 64 ou version ultérieure

    Si la valeur est true, la propriété "window.opener" de la fenêtre nouvellement créée est définie 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 et fullscreen ne peuvent pas être combinés avec left, top, width ou height.

  • tabId

    number facultatif

    ID de l'onglet à ajouter à la nouvelle fenêtre.

  • top

    number facultatif

    Nombre de pixels pour positionner la nouvelle fenêtre à partir du bord supérieur de l'écran. Si elle n'est pas spécifiée, la nouvelle fenêtre est décalée naturellement par rapport à la dernière fenêtre active. Cette valeur est ignorée pour les panneaux.

  • type

    CreateType facultatif

    Spécifie le type de fenêtre de navigateur à créer.

  • url

    string | string[] facultatif

    URL ou tableau d'URL à ouvrir sous forme d'onglets dans la fenêtre. Les URL complètes doivent inclure un schéma, par exemple "http://www.google.com", et non "www.google.com". Les URL non complètes sont considérées comme relatives dans l'extension. La page "Nouvel onglet" est définie par défaut.

  • width

    number facultatif

    Largeur en pixels de la nouvelle fenêtre, cadre compris. Si aucune valeur n'est spécifiée, la valeur par défaut est une largeur naturelle.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (window?: Window) => void

  • fenêtre

    Window facultatif

    Contient des informations sur la fenêtre créée.

Renvoie

• Promise<Window | undefined>

  Chrome 88 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

get()

Promise

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

Récupère des informations sur une fenêtre.

Paramètres

• windowId

  nombre

• queryOptions

  QueryOptions facultatif

  Chrome 88 ou version ultérieure
• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (window: Window) => void

  • fenêtre

    Fenêtre

Renvoie

• Promise<Window>

  Chrome 88 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getAll()

Promise

chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window[]>

Récupère toutes les fenêtres.

Paramètres

• queryOptions

  QueryOptions facultatif

  Chrome 88 ou version ultérieure
• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (windows: Window[]) => void

  • fenêtres

    Fenêtre[]

Renvoie

• Promise<Window[]>

  Chrome 88 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getCurrent()

Promise

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

Récupère la fenêtre actuelle.

Paramètres

• queryOptions

  QueryOptions facultatif

  Chrome 88 ou version ultérieure
• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (window: Window) => void

  • fenêtre

    Fenêtre

Renvoie

• Promise<Window>

  Chrome 88 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getLastFocused()

Promise

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

Récupère la fenêtre qui a été sélectionnée le plus récemment (généralement la fenêtre "au premier plan").

Paramètres

• queryOptions

  QueryOptions facultatif

  Chrome 88 ou version ultérieure
• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (window: Window) => void

  • fenêtre

    Fenêtre

Renvoie

• Promise<Window>

  Chrome 88 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

remove()

Promise

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

Supprime (ferme) une fenêtre et tous les onglets qu'elle contient.

Paramètres

• windowId

  nombre

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  () => void

Renvoie

• Promise<void>

  Chrome 88 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

update()

Promise

chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
): Promise<Window>

Mettre à 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

    boolean 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 place le curseur sur la fenêtre. Cette option n'a aucun effet si la fenêtre est déjà active. Définissez cette option sur false pour annuler une requête drawAttention précédente.

  • Concentration

    boolean facultatif

    Si la valeur est true, la fenêtre est placée au premier plan. Ne peut pas être combiné avec l'état "minimized". Si la valeur est false, place la fenêtre suivante dans l'ordre Z au premier plan. Ne peut pas être combiné avec l'état "fullscreen" ou "maximized".

  • height

    number facultatif

    Hauteur de redimensionnement de la fenêtre, en pixels. Cette valeur est ignorée pour les panneaux.

  • gauche

    number facultatif

    Décalage par rapport au 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 "minimized", "maximized" et "fullscreen" ne peuvent pas être combinés avec "left", "top", "width" ou "height".

  • top

    number facultatif

    Décalage par rapport au bord supérieur de l'écran pour déplacer la fenêtre, en pixels. Cette valeur est ignorée pour les panneaux.

  • width

    number facultatif

    Largeur de la fenêtre redimensionnée, en pixels. Cette valeur est ignorée pour les panneaux.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (window: Window) => void

  • fenêtre

    Fenêtre

Renvoie

• Promise<Window>

  Chrome 88 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onBoundsChanged

Chrome 86 ou version ultérieure

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

Déclenché lorsqu'une fenêtre a été redimensionnée. Cet événement n'est distribué que lorsque les nouvelles limites sont validées, et non pour les modifications en cours.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (window: Window) => void

  • fenêtre

    Fenêtre

onCreated

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

Déclenché lorsqu'une fenêtre est créée.

Paramètres

• callback

  fonction

  Chrome 46 ou version ultérieure

  Le paramètre callback se présente comme suit :

  (window: Window) => void

  • fenêtre

    Fenêtre

    Détails de la fenêtre créée.

• filtres

  objet facultatif

  • windowTypes

    WindowType[]

    Conditions que le type de fenêtre en cours de création doit remplir. Par défaut, il satisfait à ['normal', 'popup'].

onFocusChanged

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

Se déclenche 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 : Sur certains gestionnaires de fenêtres Linux, WINDOW_ID_NONE est toujours envoyé immédiatement avant de passer d'une fenêtre Chrome à une autre.

Paramètres

• callback

  fonction

  Chrome 46 ou version ultérieure

  Le paramètre callback se présente comme suit :

  (windowId: number) => void

  • windowId

    nombre

    ID de la fenêtre récemment sélectionnée.

• filtres

  objet facultatif

  • windowTypes

    WindowType[]

    Conditions que le type de fenêtre en cours de suppression doit remplir. Par défaut, il satisfait à ['normal', 'popup'].

onRemoved

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

Se déclenche lorsqu'une fenêtre est supprimée (fermée).

Paramètres

• callback

  fonction

  Chrome 46 ou version ultérieure

  Le paramètre callback se présente comme suit :

  (windowId: number) => void

  • windowId

    nombre

    ID de la fenêtre supprimée.

• filtres

  objet facultatif

  • windowTypes

    WindowType[]

    Conditions que le type de fenêtre en cours de suppression doit remplir. Par défaut, il satisfait à ['normal', 'popup'].