recursal/MDN huggingface dataset:
webRequest.StreamFilter.write()
===============================

Writes some response data to the output stream.

You can only call this function after the `onstart` event has fired.

Syntax
------


```js
filter.write(
  data    // ArrayBuffer or Uint8Array
)
```

### Parameters

`data`

`Uint8Array` or `ArrayBuffer`: array of bytes containing the data to pass to the browser's rendering engine.

### Return value

None.

Browser compatibility
---------------------

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

Examples
--------

This example uses `write()`, to replace "Example" in the first chunk of the response with "WebExtension Example".


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);
  let decoder = new TextDecoder("utf-8");
  let encoder = new TextEncoder();

  filter.ondata = (event) => {
    let str = decoder.decode(event.data, { stream: true });
    // Just change any instance of Example in the HTTP response
    // to WebExtension Example.
    str = str.replace(/Example/g, "WebExtension Example");
    filter.write(encoder.encode(str));
    filter.disconnect();
  };

  //return {}; // not needed
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/\*"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.status
==============================

A string that describes the current status of the request. It will be one of the following values:

`"uninitialized"`

The filter is not fully initialized. No filter functions may be called.

`"transferringdata"`

The underlying channel is currently transferring data, which will be routed to the extension in one or more `ondata` events. The extension can call filter functions such as `write()`, `close()`, or `disconnect()`.

`"finishedtransferringdata"`

The underlying channel has finished transferring data. In this state the extension can still write response data using the filter's `write()` function.

`"suspended"`

Data transfer is currently suspended. In this state the extension can resume the request by calling the filter's `resume()` function, and can write response data using the filter's `write()` function.

`"closed"`

The extension has closed the request by calling the filter's `close()` function. The filter will not fire any more events, and the extension may not call any filter functions.

`"disconnected"`

The extension has disconnected the filter from the request by calling the filter's `disconnect()` function. All further data will be delivered directly, without passing through the filter. The filter will not fire any more events, and the extension may not call any filter functions.

`"failed"`

An error has occurred and the filter has been disconnected from the request. The extension can find an error message in `error`, and may not call any filter functions.

Browser compatibility
---------------------

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

Examples
--------


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);
  console.log(filter.status); // uninitialized

  filter.onstart = (event) => {
    console.log(filter.status); // transferringdata
  };

  filter.ondata = (event) => {
    console.log(filter.status); // transferringdata
    // pass through the response data
    filter.write(event.data);
  };

  filter.onstop = (event) => {
    console.log(filter.status); // finishedtransferringdata
    filter.disconnect();
    console.log(filter.status); // disconnected
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/\*"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.onstop
==============================

An event handler that will be called when the stream has no more data to deliver. In the event handler you can still call filter functions such as `write()`, `disconnect()`, or `close()`.

Browser compatibility
---------------------

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

Examples
--------

This example will append "extra stuff" to the response:


```js
function listener(details) {
  const filter = browser.webRequest.filterResponseData(details.requestId);
  const encoder = new TextEncoder();

  filter.ondata = (event) => {
    // pass through all the response data
    filter.write(event.data);
  };

  filter.onstop = (event) => {
    filter.write(encoder.encode("extra stuff"));
    filter.disconnect();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/\*"], types: ["main\_frame"] },
  ["blocking"],
);
```


Here's another version of the example above:


```js
function listener(details) {
  const filter = browser.webRequest.filterResponseData(details.requestId);
  const encoder = new TextEncoder();

  const data = [];
  filter.ondata = (event) => {
    data.push(event.data);
  };

  filter.onstop = (event) => {
    for (const buffer of data) {
      filter.write(buffer);
    }
    filter.write(encoder.encode("extra stuff"));
    filter.close();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.suspend()
=================================

Suspends a request. After this is called, no more data will be delivered until the request is resumed with a call to `resume()`.

You can't call this function until after the `onstart` event has fired.

Syntax
------


```js
filter.suspend()
```

### Parameters

None.

### Return value

None.

Browser compatibility
---------------------

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

Examples
--------

This example uses suspend/resume to delay a web request.


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    filter.suspend();

    setTimeout(() => {
      filter.resume();
      filter.disconnect();
    }, 1000);
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
tabs.reload()
=============

Reload a tab, optionally bypassing the local web cache.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let reloading = browser.tabs.reload(
  tabId,            // optional integer
  reloadProperties  // optional object
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab to reload. Defaults to the selected tab of the current window.

`reloadProperties` Optional

An object with the following properties:

`bypassCache` Optional

`boolean`. Bypass the local web cache. Default is `false`.


### Return value

A `Promise` that will be fulfilled with no arguments when the tab has been reloaded. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Reload the active tab of the current window:


```js
browser.tabs.reload();
```


Reload the active tab of the current window, bypassing the cache:


```js
browser.tabs.reload({ bypassCache: true });
```


Reload the tab whose ID is 2, bypassing the cache and calling a callback when done:


```js
function onReloaded() {
  console.log(`Reloaded`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let reloading = browser.tabs.reload(2, { bypassCache: true });
reloading.then(onReloaded, onError);
```

### Example extensions

* tabs-tabs-tabs
Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.onHighlightChanged
=======================

**Warning:** This event is deprecated. Use `tabs.onHighlighted` instead.

Fired when the highlighted or selected tabs in a window changes.

Syntax
------


```js
browser.tabs.onHighlightChanged.addListener(listener)
browser.tabs.onHighlightChanged.removeListener(listener)
browser.tabs.onHighlightChanged.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`selectInfo`

`object`. See the selectInfo section for more details.


Additional objects
------------------

### selectInfo

`windowId`

`integer`. The window whose tabs changed.

`tabIds`

`array` of `integer`. All highlighted tabs in the window.

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.onZoomChange
=================

Fired when a tab is zoomed.

Syntax
------


```js
browser.tabs.onZoomChange.addListener(listener)
browser.tabs.onZoomChange.removeListener(listener)
browser.tabs.onZoomChange.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`ZoomChangeInfo`

`object`. Information about the zoom event. See the ZoomChangeInfo section for more details.


Additional objects
------------------

### ZoomChangeInfo

`tabId`

`integer`. ID of the tab that was zoomed.

`oldZoomFactor`

`number`. The previous zoom factor.

`newZoomFactor`

`number`. The new zoom factor.

`zoomSettings`

`tabs.ZoomSettings`. Zoom settings for the tab.

Examples
--------

Listen for zoom events and log the info:


```js
function handleZoomed(zoomChangeInfo) {
  console.log(`Tab: ${zoomChangeInfo.tabId} zoomed`);
  console.log(`Old zoom: ${zoomChangeInfo.oldZoomFactor}`);
  console.log(`New zoom: ${zoomChangeInfo.newZoomFactor}`);
}

browser.tabs.onZoomChange.addListener(handleZoomed);
```

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.setZoomSettings()
======================

Sets zoom settings for the specified tab. These settings are reset to the default settings upon navigating the tab.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let settingZoomSettings = browser.tabs.setZoomSettings(
  tabId,           // optional integer
  zoomSettings     // ZoomSettings
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab to change the zoom settings for. Defaults to the active tab of the current window.

`zoomSettings`

`tabs.ZoomSettings`. Defines how zoom changes are handled and at what scope.

### Return value

A `Promise` that will be fulfilled with no arguments after the zoom settings have been changed. If the tab could not be found or some other error occurs, the promise will be rejected with an error message.getZoom

Examples
--------

Disable zooming for the current tab:


```js
function onSet() {
  console.log(`Set zoom factor`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let setting = browser.tabs.setZoomSettings({ mode: "disabled" });
setting.then(onSet, onError);
```

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.WindowType
===============

The type of window that hosts this tab.

Type
----

Values of this type are strings. Possible values are:

* **"normal"**
* **"popup"**
* **"panel"**
* **"devtools"**
Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.onDetached
===============

Fired when a tab is detached from a window, for example because it is being moved between windows.

Syntax
------


```js
browser.tabs.onDetached.addListener(listener)
browser.tabs.onDetached.removeListener(listener)
browser.tabs.onDetached.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`tabId`

`integer`. ID of the tab that was detached.

`detachInfo`

`object`. ID of the previous window, and index of the tab within it. See the detachInfo section for more details.


Additional objects
------------------

### detachInfo

`oldWindowId`

`integer`. ID of the previous window.

`oldPosition`

`integer`. Index position that the tab had in the old window.

Examples
--------

Listen for detach events, and log the info:


```js
function handleDetached(tabId, detachInfo) {
  console.log(`Tab: ${tabId} moved`);
  console.log(`Old window: ${detachInfo.oldWindowId}`);
  console.log(`Old index: ${detachInfo.oldPosition}`);
}

browser.tabs.onDetached.addListener(handleDetached);
```

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.sendRequest()
==================

**Warning:** This method has been deprecated. Use `tabs.sendMessage()` instead.

Sends a single request to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The `extension.onRequest` event is fired in each content script running in the specified tab for the current extension.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let sending = browser.tabs.sendRequest(
  tabId,                   // integer
  request                  // any
)
```

### Parameters

`tabId`

`integer`.

`request`

`any`.

### Return value

A `Promise` that will be fulfilled with the JSON response object sent by the handler of the message in the content script, or with no arguments if the content script did not send a response. If an error occurs while connecting to the specified tab or any other error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.ZoomSettings
=================

Defines zoom settings for a tab: `mode`, `scope`, and default zoom factor.

Type
----

Values of this type are objects. They contain the following properties:

`defaultZoomFactor` Optional

`number`. The default zoom level for the current tab. Note that this is only used in `tabs.getZoomSettings`.

`mode` Optional

`tabs.ZoomSettingsMode`. Defines whether zoom changes are handled by the browser, by the extension, or are disabled.

`scope` Optional

`tabs.ZoomSettingsScope`. Defines whether zoom changes will persist for the page's origin, or only take effect in this tab.

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.onMoved
============

Fired when a tab is moved within a window.

Only one move event is fired, representing the tab the user directly moved. Move events are not fired for the other tabs that must move in response. This event is not fired when a tab is moved between windows. For that, see `tabs.onDetached`.

Syntax
------


```js
browser.tabs.onMoved.addListener(listener)
browser.tabs.onMoved.removeListener(listener)
browser.tabs.onMoved.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`tabId`

`integer`. ID of the tab the user moved.

`moveInfo`

`object`. Information about the move. See the moveInfo section for more details.


Additional objects
------------------

### moveInfo

`windowId`

`integer`. ID of this tab's window.

`fromIndex`

`integer`. Initial index of this tab in the window.

`toIndex`

`integer`. Final index of this tab in the window.

Examples
--------

Listen for and log move events:


```js
function handleMoved(tabId, moveInfo) {
  console.log(
    `Tab ${tabId} moved from ${moveInfo.fromIndex} to ${moveInfo.toIndex}`,
  );
}

browser.tabs.onMoved.addListener(handleMoved);
```

### Example extensions

* tabs-tabs-tabs
Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.setZoom()
==============

Zooms the specified tab.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let zooming = browser.tabs.setZoom(
  tabId,           // optional integer
  zoomFactor       // number
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab to zoom. Defaults to the active tab of the current window.

`zoomFactor`

`number`. The new zoom factor. Use a value of 0 here to set the tab to its current default zoom factor. Otherwise, this must be a number between 0.3 and 5, specifying a zoom factor.

### Return value

A `Promise` that will be fulfilled with no arguments after the zoom factor has been changed. If the tab could not be found or some other error occurs, the promise will be rejected with an error message.

Examples
--------

Set the zoom factor for the current tab to 2:


```js
function onError(error) {
  console.log(`Error: ${error}`);
}

let setting = browser.tabs.setZoom(2);
setting.then(null, onError);
```


Set the zoom factor for the tab whose ID is 16 tab to 0.5:


```js
function onError(error) {
  console.log(`Error: ${error}`);
}

let setting = browser.tabs.setZoom(16, 0.5);
setting.then(null, onError);
```

### Example extensions

* tabs-tabs-tabs
Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.getCurrent()
=================

Get a `tabs.Tab` containing information about the tab that this script is running in.

**Note:** This function is only useful in contexts where there is a browser tab, such as an options page.

If you call it from a background script or a popup, it will return `undefined`.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
const gettingCurrent = browser.tabs.getCurrent()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with a `tabs.Tab` object containing information about the current tab. If any error occurs the promise will be rejected with an error message.

Examples
--------

Get information about the current tab:


```js
function onGot(tabInfo) {
  console.log(tabInfo);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const gettingCurrent = browser.tabs.getCurrent();
gettingCurrent.then(onGot, onError);
```

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.getZoomSettings()
======================

Gets the current zoom settings for a specified tab.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingZoomSettings = browser.tabs.getZoomSettings(
  tabId                       // optional integer
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab to get the current zoom settings from. Defaults to the active tab of the current window.

### Return value

A `Promise` that will be fulfilled with a `tabs.ZoomSettings` object representing the tab's current zoom settings. If the tab could not be found or some other error occurs, the promise will be rejected with an error message.

Examples
--------

Get the zoom settings for the current tab:


```js
function onGot(settings) {
  console.log(settings);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let gettingZoomSettings = browser.tabs.getZoomSettings();
gettingZoomSettings.then(onGot, onError);
```

Browser compatibility
---------------------

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

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.