runtime.Port
============

Un objet `Port` represente une extrémité d'une connexion entre deux contextes spécifiques, qui peut-être utilisée pour échanger des messages.

Un côté initie la connexion à l'aide d'une API `connect()`. Cela retourne un objet `Port`. L'autre camp écoute les tentatives de connexion à l'aide d'un écouteur `onConnect`. Ceci est passé un objet `Port` correspondant.

Une fois que les deux côtés ont des objets `Port,` ils peuvent échanger des messages JSON en utilisant `Port.postMessage()` et `Port.onMessage`. Quand ils sont terminés, chaque extrémité peut se déconnecter en utilisant `Port.disconnect()`, ce qui générera un événement `Port.onDisconnect` à l'autre extrémité, permettant à l'autre extrémité de faire le nettoyage requis.

Vous pouvez utiliser ce modèle pour communiquer entre:

* différentes parties de votre extension (par exemple, entre les scripts de contenus et les scripts d'arrière-plan)
* entre votre extension et une application native s'exéutant sur l'ordinateur de l'utilisateur.
* entre votre extension et une extension différente

Vous devez utiliser différentes API de connexion pour différents types de connexions, comme indiqué dans le tableau ci-dessous.

| type de connection | Lancer une tentative de connexion | Gérer la tentative de connexion |
| --- | --- | --- |
| Script d'arrière-plan au script de contenu | `tabs.connect()` | `runtime.onConnect` |
| Script de contenu au script d'arrière-plan | `runtime.connect()` | `runtime.onConnect` |
| Extension à l'application native | `runtime.connectNative()` | N'est pas applicable (voir Native messaging). |
| Extension à l'extension | `runtime.connect()` | `runtime.onConnectExternal` |

Type
----

Les valeurs de ce type sont des objets. Ils contiennent les propriétés suivantes :

`name`

`string`. Le nom du port, défini dans `runtime.connect()` ou `tabs.connect()` appel qui l'a créé. Si ce port est connecté à une application native, son nom est le nom de l'application native.

`disconnect`

`function`. Déconnecte un port. Chaque extrémité peut appeler cela quand ils ont fini avec le port. Cela provoquera le déclenchement de `onDisconnect` à l'autre extrémité. Ceci est utile si l'autre extrémité maintient un état relatif à ce port, qui peut être nettoyé lors de la déconnexion. Si ce port est connecté à une application native, cette fonction ferme l'application native.

`error`

`object`. Si le port a été déconnecté en raison d'une erreur, il sera défini sur un objet avec un `message`, de propriété de chaîne, vous donnant plus d'informations sur l'erreur. Voir `onDisconnect`.

`onDisconnect`

`object`. Cela contient les fonctions `addListener()` et `removeListener()` communes à tous les événements pour les extensions créées à l'aide des API. WebExtension. Les fonctions de l'écouteur seront appelées lorsque l'autre extrémité aura appelé `Port.disconnect()`. Cet événement ne sera déclenché qu'une fois pour chaque port. La fonction d'écouteur recevra l'objet `Port`. Si le port a été déconnecté en raison d'une erreur, l'argument `Port` contiendra une propriété `error` donnant plus d'informations sur l'erreur :


```js
port.onDisconnect.addListener((p) => {
  if (p.error) {
    console.log(`Disconnected due to an error: ${p.error.message}`);
  }
});
```


Notez que dans Google Chrome `port.error` n'est pas supporté: utilisez plutôt `runtime.lastError` pour obtenir le message d'erreur.

`onMessage`

`object`. Cela contient les fonctions `addListener()` et `removeListener()` communes à tous les événements pour les extensions créées à l'aide des API WebExtension. Les fonctions de l'écouteur seront appelées lorsque l'autre extrémité aura envoyé un message à ce port. L'écouteur recevra l'objet JSON envoyé par l'autre extrémité.

`postMessage`

`function`. Envoyer un message à l'autre extrémité. Cela prend un argument, qui est un objet JSON représentant le message à envoyer. Il sera fourni à tout script écoutant l'événement `onMessage` du port, ou à l'application native si ce port est connecté à une application native.

`sender`Facultatif

`runtime.MessageSender`. Contient des informations sur l'expéditeur du message. ette propriété ne sera présente que sur les ports transmis aux écouteurs `onConnect`/`onConnectExternal`.

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Exemples
--------

### Connecting from content scripts

This content script:

* connects to the background script and stores the `Port` in a variable called `myPort`.
* listens for messages on `myPort` and logs them.
* sends messages to the background script, using `myPort`, when the user clicks the document.


```js
// content-script.js

var myPort = browser.runtime.connect({ name: "port-from-cs" });
myPort.postMessage({ greeting: "hello from content script" });

myPort.onMessage.addListener(function (m) {
  console.log("In content script, received message from background script: ");
  console.log(m.greeting);
});

document.body.addEventListener("click", function () {
  myPort.postMessage({ greeting: "they clicked the page!" });
});
```


The corresponding background script:

* listens for connection attempts from the content script.
* when it receives a connection attempt:
    + stores the port in a variable named `portFromCS`.
    + sends the content script a message using the port.
    + starts listening to messages received on the port, and logs them.
* sends messages to the content script, using `portFromCS`, when the user clicks the extension's browser action.


```js
// background-script.js

var portFromCS;

function connected(p) {
  portFromCS = p;
  portFromCS.postMessage({ greeting: "hi there content script!" });
  portFromCS.onMessage.addListener(function (m) {
    console.log("In background script, received message from content script");
    console.log(m.greeting);
  });
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(function () {
  portFromCS.postMessage({ greeting: "they clicked the button!" });
});
```


#### Script à contenu multiple

Si plusieurs scripts de contenu communiquent en même temps, vous voudrez peut-être stocker chaque connexion dans un tableau.


```js
// background-script.js

var ports = [];

function connected(p) {
  ports[p.sender.tab.id] = p;
  //...
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(function () {
  ports.forEach((p) => {
    p.postMessage({ greeting: "they clicked the button!" });
  });
});
```

### Connecting to native applications

This example connects to the native application "ping\_pong" and starts listening for messages from it. It also sends the native application a message when the user clicks a browser action icon:


```js
/\*
On startup, connect to the "ping\_pong" app.
\*/
var port = browser.runtime.connectNative("ping\_pong");

/\*
Listen for messages from the app.
\*/
port.onMessage.addListener((response) => {
  console.log("Received: " + response);
});

/\*
On a click on the browser action, send the app a message.
\*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending: ping");
  port.postMessage("ping");
});
```


**Note :**

Cette API est basée sur l'API Chromium `chrome.runtime`. Cette documentation est dérivée de `runtime.json` dans le code de Chromium code.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.