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.

Autorisations

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"],
  ...
}

Concepts et utilisation

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

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

<ph type="x-smartling-placeholder">

</ph>

Deux fenêtres, chacune avec un onglet.

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 sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

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

  • fenêtre

    Fenêtre

Renvoie

• Promise&lt;Window&gt;

  Chrome (version 88 ou ultérieure)

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

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

  • fenêtres

    Fenêtre[]

Renvoie

• Promise&lt;Window[]&gt;

  Chrome (version 88 ou ultérieure)

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

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

  • fenêtre

    Fenêtre

Renvoie

• Promise&lt;Window&gt;

  Chrome (version 88 ou ultérieure)

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

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

  • fenêtre

    Fenêtre

Renvoie

• Promise&lt;Window&gt;

  Chrome (version 88 ou ultérieure)

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

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 sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

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

  • fenêtre

    Fenêtre

Renvoie

• Promise&lt;Window&gt;

  Chrome (version 88 ou ultérieure)

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

É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

  • 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

  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'].