chrome.windows

Description

Utilisez l'API chrome.windows pour interagir avec les fenêtres du navigateur. Cette API vous permet de créer, modifier et réorganiser des fenêtres dans le navigateur.

Fichier manifeste

Lorsqu'elle est demandée, une windows.Window contient un tableau d'objets tabs.Tab. Vous devez Déclarez l'autorisation "tabs" dans votre fichier manifeste si vous avez besoin d'accéder à url. pendingUrl, title ou favIconUrl de tabs.Tab. Exemple :

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

Fenêtre actuelle

De nombreuses fonctions du système d'extension acceptent un argument windowId facultatif, dont la valeur par défaut est la la fenêtre actuelle.

La fenêtre actuelle est celle qui contient le code en cours d'exécution. Il est il est important de comprendre que cette fenêtre peut être différente de la fenêtre supérieure ou ciblée.

Supposons, par exemple, qu'une extension crée plusieurs onglets ou fenêtres à partir d'un seul fichier HTML, et que la fonction Le fichier HTML contient un appel à tabs.query(). La fenêtre actuelle est celle qui contient à partir de la page qui a passé l'appel, quelle que soit la fenêtre supérieure.

Dans le cas de service workers, la valeur de la fenêtre actuelle revient au dernier actif fenêtre. Dans certains cas, il se peut qu'aucune fenêtre ne s'affiche pour les pages en arrière-plan.

Exemples

Deux fenêtres, chacune avec un onglet

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

Types

CreateType

Chrome (version 44 ou ultérieure)

Indique le type de fenêtre de navigateur à créer. "panel" (panneau) est obsolète et n'est disponible que pour les extensions existantes de Chrome OS figurant sur la liste d'autorisation.

Énumération

"normal"
Spécifie la fenêtre en tant que 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 (version 88 ou ultérieure)

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

    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.

  • hauteur

    numéro facultatif

    Hauteur de la fenêtre, cadre compris, en pixels. Dans certains cas, une propriété height ne peut pas être attribuée à une fenêtre. par exemple, lorsque vous interrogez des fenêtres fermées à partir de l'API sessions.

  • id

    numéro facultatif

    ID de la fenêtre. Les identifiants de fenêtre sont uniques au sein d'une session de navigateur. Dans certains cas, une propriété ID ne peut pas ê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

    booléen

    Indique si la fenêtre est en mode 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, une propriété left ne peut pas être attribuée à une fenêtre. par exemple, lorsque vous interrogez des fenêtres fermées à partir de l'API sessions.

  • sessionId

    chaîne facultatif

    ID de session utilisé pour 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 dans 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, une propriété top ne peut pas être attribuée à une fenêtre. par exemple, lorsque vous interrogez 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, une propriété width ne peut pas être attribuée à une fenêtre. par exemple, lorsque vous interrogez des fenêtres fermées à partir de l'API sessions.

WindowState

Chrome (version 44 ou ultérieure)

État de cette fenêtre du navigateur. Dans certains cas, une propriété state ne peut pas être attribuée à une fenêtre. par exemple, lorsque vous interrogez des fenêtres fermées à partir de l'API sessions.

Énumération

"normal"
État normal de la fenêtre (non réduite, agrandie ou 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. L'utilisateur ne peut pas quitter le mode plein écran et n'est disponible que pour les extensions figurant sur la liste d'autorisation sur ChromeOS.

WindowType

Chrome (version 44 ou ultérieure)

Type de fenêtre de navigateur dont il s'agit. Dans certains cas, une propriété type ne peut pas être attribuée à une fenêtre. par exemple, lorsque vous interrogez des fenêtres fermées à partir de l'API sessions.

Énumération

"normal"
Une fenêtre de navigateur normale.

"popup"
Pop-up de navigateur.

"panel"
Obsolète dans cette API. Fenêtre de type panneau de l'application Chrome. Les extensions ne peuvent voir que leur propre fenêtre de panneau.

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

"devtools"
Fenêtre "Developer Tools" (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()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

Crée (ouvre) une nouvelle fenêtre de navigateur avec la taille, la position ou l'URL par défaut éventuellement fournies.

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.

    • hauteur

      numéro 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

      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 pour positionner la nouvelle fenêtre par rapport au bord gauche de l'écran. Si aucune valeur n'est spécifiée, 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 (version 64 ou ultérieure)

      Si la valeur est true, la valeur "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 (version 44 ou 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 pour positionner la nouvelle fenêtre à partir du bord supérieur de l'écran. Si aucune valeur n'est spécifiée, 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 sous forme d'onglets dans la fenêtre. Les URL complètes doivent inclure un schéma, tel que "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 utilisée par défaut.

    • largeur

      numéro 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.

  • rappel

    function facultatif

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

    (window?: Window) => void

    • fenêtre

      Fenêtre facultatif

      Contient des détails sur la fenêtre créée.

Renvoie

  • Promise&lt;Window | indéfini>

    Chrome (version 88 ou ultérieure)

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

get()

<ph type="x-smartling-placeholder"></ph> Promesse 
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 (version 88 ou ultérieure)
  • rappel

    function facultatif

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

    (window: Window) => void

Renvoie

  • Promise&lt;Window&gt;

    Chrome (version 88 ou ultérieure)

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

getAll()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

Récupère toutes les fenêtres.

Paramètres

  • queryOptions

    QueryOptions facultatif

    Chrome (version 88 ou ultérieure)
  • rappel

    function facultatif

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

    (windows: Window[]) => void

Renvoie

  • Promise&lt;Window[]&gt;

    Chrome (version 88 ou ultérieure)

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

getCurrent()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

Récupère la fenêtre actuelle.

Paramètres

  • queryOptions

    QueryOptions facultatif

    Chrome (version 88 ou ultérieure)
  • rappel

    function facultatif

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

    (window: Window) => void

Renvoie

  • Promise&lt;Window&gt;

    Chrome (version 88 ou ultérieure)

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

getLastFocused()

<ph type="x-smartling-placeholder"></ph> 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 (version 88 ou ultérieure)
  • rappel

    function facultatif

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

    (window: Window) => void

Renvoie

  • Promise&lt;Window&gt;

    Chrome (version 88 ou ultérieure)

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

remove()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

Paramètres

  • windowId

    Nombre

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome (version 88 ou ultérieure)

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

update()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

Met à jour les propriétés d'une fenêtre. spécifier uniquement les propriétés à modifier ; 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 sur la fenêtre, 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 ce paramètre sur false pour annuler une requête drawAttention précédente.

    • Concentration

      Booléen facultatif

      Si la valeur est true, la fenêtre est placée au premier plan. ne peut pas être associé à l'état "minimisé". Si la valeur est false, la fenêtre suivante dans l'ordre de plan est placée au premier plan. ne peut pas être associé à l'état "plein écran" ou "maximisée".

    • hauteur

      numéro facultatif

      Hauteur en pixels à laquelle la fenêtre doit être redimensionnée. Cette valeur est ignorée pour les panneaux.

    • gauche

      numéro facultatif

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

    • state

      WindowState facultatif

      Nouvel état de la fenêtre. Les options "réduite", "maximisée" et "plein écran" ne peuvent pas être combinés avec "left", "top", "width" ou "height".

    • top

      numéro facultatif

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

    • largeur

      numéro facultatif

      Largeur en pixels à laquelle la fenêtre doit être redimensionnée. Cette valeur est ignorée pour les panneaux.

  • rappel

    function facultatif

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

    (window: Window) => void

Renvoie

  • Promise&lt;Window&gt;

    Chrome (version 88 ou ultérieure)

    Les promesses ne sont compatibles qu'avec Manifest V3 et 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 envoyé que lorsque les nouvelles limites ont été validées, et non pour les modifications en cours.

Paramètres

  • rappel

    fonction

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

    (window: Window) => void

onCreated

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

Déclenché lors de la création d'une fenêtre.

Paramètres

  • rappel

    fonction

    Chrome (version 46 ou 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 auxquelles le type de fenêtre en cours de création doit satisfaire. La valeur par défaut est ['normal', 'popup'].

onFocusChanged

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

Déclenché lorsque la fenêtre active change. Affiche la valeur chrome.windows.WINDOW_ID_NONE si toutes les fenêtres Chrome ont été désactivées. Remarque:Dans certains gestionnaires de fenêtres Linux, WINDOW_ID_NONE est toujours envoyé juste avant le basculement d'une fenêtre Chrome à une autre.

Paramètres

  • rappel

    fonction

    Chrome (version 46 ou ultérieure)

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

    (windowId: number) => void

    • windowId

      Nombre

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

  • filtres

    objet facultatif

    • windowTypes

      WindowType[]

      Conditions auxquelles le type de fenêtre en cours de suppression doit satisfaire. La valeur par défaut est ['normal', 'popup'].

onRemoved

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

Déclenché lors de la suppression d'une fenêtre (fermée).

Paramètres

  • rappel

    fonction

    Chrome (version 46 ou 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 auxquelles le type de fenêtre en cours de suppression doit satisfaire. La valeur par défaut est ['normal', 'popup'].