chrome.windows

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 contenant un onglet.

Types

CreateType

Chrome 44 ou version ultérieure

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

Chrome 88 et versions ultérieures

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

  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'API sessions.

• 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'API sessions, 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'API sessions.

• 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.

• top

  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'API sessions.

• 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'API sessions.

WindowState

Chrome 44 ou version ultérieure

É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

Chrome 44 ou version ultérieure

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()

Promesse

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 est false, 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érieure

    Si 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 et fullscreen ne peuvent pas être combinés avec left, top, width ou height.

  • tabId

    numéro facultatif

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

  • top

    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[] optional

    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érieures

  Les 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()

Promesse

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

Récupère les détails d'une fenêtre.

Paramètres

• windowId

  number

• 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

    Fenêtre

Renvoie

• Promesse<Window>

  Chrome 88 et versions ultérieures

  Les 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()

Promesse

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érieures

  Les 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()

Promesse

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

    Fenêtre

Renvoie

• Promesse<Window>

  Chrome 88 et versions ultérieures

  Les 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()

Promesse

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

    Fenêtre

Renvoie

• Promesse<Window>

  Chrome 88 et versions ultérieures

  Les 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()

Promesse

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

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

Paramètres

• windowId

  number

• rappel

  fonction facultative

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

  ()=>void

Renvoie

• Promise<void>

  Chrome 88 et versions ultérieures

  Les 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()

Promesse

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

  number

• 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 sur false pour annuler une requête drawAttention 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 est false, 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".

  • top

    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

    Fenêtre

Renvoie

• Promesse<Window>

  Chrome 88 et versions ultérieures

  Les 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 86 et versions ultérieures

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

    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é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[]

    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érieure

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

  (windowId: number)=>void

  • windowId

    number

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

• filtres

  objet facultatif

  • windowTypes

    WindowType[]

    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érieure

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

  (windowId: number)=>void

  • windowId

    number

    ID de la fenêtre supprimée.

• filtres

  objet facultatif

  • windowTypes

    WindowType[]

    Les conditions que le type de fenêtre à supprimer doivent remplir. Par défaut, il répond aux exigences de ['normal', 'popup'].