Skip to content

Commit fc88cd9

Browse files
rebloorrebloor
authored
browser.tab.onUpdated.addListener clarifications & edits (mdn#20774)
1 parent 6b4bbc0 commit fc88cd9

File tree

1 file changed

+20
-28
lines changed
  • files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated

1 file changed

+20
-28
lines changed

‎files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md

Lines changed: 20 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@ browser-compat: webextensions.api.tabs.onUpdated
1616

1717
Fired when a tab is updated.
1818

19-
When the user navigates to a new URL in a tab, this will typically generate several `onUpdated` events as various properties of the {{WebExtAPIRef("tabs.Tab")}} object are updated. This includes the `url`, but also potentially the `title` and `favIconUrl` properties. The `status` property will cycle through `"loading"` and `"complete"`.
19+
When the user navigates to a new URL in a tab, this typically generates several `onUpdated` events as various properties of the {{WebExtAPIRef("tabs.Tab")}} object are updated. This includes the `url`, but also potentially the `title` and `favIconUrl` properties. The `status` property will cycle through `"loading"` and `"complete"`.
2020

21-
This event will also be fired for changes to a tab's properties that don't involve navigation, like pinning and unpinning (which updates the `pinned` property) and muting or unmuting (which updates the `audible` and `mutedInfo` properties).
21+
This event also fires for changes to a tab's properties that don't involve navigation, such as pinning and unpinning (which updates the `pinned` property) and muting or unmuting (which updates the `audible` and `mutedInfo` properties).
2222

23-
You can filter this event, making it only fire for tabs whose URLs match specific [patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), or for changes to specific properties, or for changes to a specific tab or window, or any combinations of these restrictions.
23+
You can filter this event, making it only fire for tabs whose URLs match specific [patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), changes to particular properties, changes to a tab or window, or any combinations of these restrictions.
2424

2525
## Syntax
2626

@@ -45,24 +45,24 @@ Events have three functions:
4545

4646
- `callback`
4747

48-
- : Function that will be called when this event occurs. The function will be passed the following arguments:
48+
- : The function called when this event occurs. The function is passed these arguments:
4949

5050
- `tabId`
51-
- : `integer`. ID of the tab that was updated.
51+
- : `integer`. The ID of the updated tab.
5252
- `changeInfo`
53-
- : [`object`](#changeinfo). Contains properties for the tab properties that have changed. See [`changeInfo`](#changeinfo_2) below.
53+
- : [`object`](#changeinfo). Properties of the tab that changed. See [`changeInfo`](#changeinfo_2) below.
5454
- `tab`
5555
- : {{WebExtAPIRef('tabs.Tab')}}. The new state of the tab.
5656

5757
- `extraParameters` {{optional_inline}}
5858

59-
- : `object`. A set of filters that restricts the events that will be sent to this listener. This is an object which may have one or more of the following properties. Events will only be sent if they satisfy all the filters given.
59+
- : `object`. A set of filters that restrict the events sent to this listener. This object can have one or more of these properties. Events are only sent if they satisfy all the filters provided.
6060

6161
- `urls`
62-
- : `Array`. An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns). Fire the event only for tabs whose current `url` property matches any one of the patterns.
62+
- : `Array`. An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns). Fires the event only for tabs whose current `url` property matches any one of the patterns.
6363
- `properties`
6464

65-
- : `Array`. An array of strings, which are the names of properties of the {{WebExtAPIRef("tabs.Tab")}} object. Fire this event only for changes to one of the properties named in this array. The following properties may be listed here:
65+
- : `Array`. An array of strings consisting of supported {{WebExtAPIRef("tabs.Tab")}} object property names. Fires the event only for changes to one of the properties named in the array. These properties can be used:
6666

6767
- "attention"
6868
- "audible"
@@ -72,32 +72,31 @@ Events have three functions:
7272
- "isArticle"
7373
- "mutedInfo"
7474
- "pinned"
75-
- "sharingState"
7675
- "status"
7776
- "title"
7877
- "url"
7978

80-
> **Note:** The "url" value is supported since Firefox 88. In Firefox 87 and earlier, "url" changes can be observed by filtering by "status".
79+
> **Note:** The "url" value has been supported since Firefox 88. In Firefox 87 and earlier, "url" changes can be observed by filtering by "status".
8180
8281
- `tabId`
83-
- : `Integer`. Fire this event only for the tab identified by this ID.
82+
- : `Integer`. Fires this event only for the tab identified by this ID.
8483
- `windowId`
85-
- : `Integer`. Fire this event only for tabs which are currently in the window identified by this ID.
84+
- : `Integer`. Fires this event only for tabs in the window identified by this ID.
8685

8786
## Additional objects
8887

8988
### changeInfo
9089

91-
Lists the changes to the state of the tab that was updated. To learn more about these properties, see the {{WebExtAPIRef("tabs.Tab")}} documentation.
90+
Lists the changes to the state of the tab that is updated. To learn more about these properties, see the {{WebExtAPIRef("tabs.Tab")}} documentation. Note that not all {{WebExtAPIRef("tabs.Tab")}} properties are supported.
9291

9392
- `attention` {{optional_inline}}
94-
- : `boolean`. Indicates whether the tab is drawing attention. For example, when the tab displays a modal dialog, `attention` will be `true`.
93+
- : `boolean`. Indicates whether the tab is drawing attention. For example, `attention` is `true` when the tab displays a modal dialog.
9594
- `audible` {{optional_inline}}
9695
- : `boolean`. The tab's new audible state.
9796
- `discarded` {{optional_inline}}
98-
- : `boolean`. Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content gets reloaded the next time it's activated.
97+
- : `boolean`. Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory but is visible in the tab strip. Its content gets reloaded the next time it's activated.
9998
- `favIconUrl` {{optional_inline}}
100-
- : `string`. The tab's new favicon URL. Not included when a tab loses its favicon (navigating from a page with a favicon to a page that without one), please check `favIconUrl` in [tab](#tab) instead.
99+
- : `string`. The tab's new favicon URL. Not included when a tab loses its favicon (navigating from a page with a favicon to a page without one). Check `favIconUrl` in [tab](#tab) instead.
101100
- `hidden` {{optional_inline}}
102101
- : `boolean`. True if the tab is {{WebExtAPIRef("tabs.hide()", "hidden")}}.
103102
- `isArticle` {{optional_inline}}
@@ -111,7 +110,7 @@ Lists the changes to the state of the tab that was updated. To learn more about
111110
- `title` {{optional_inline}}
112111
- : `string`. The tab's new title.
113112
- `url` {{optional_inline}}
114-
- : `string`. The tab's URL if it has changed.
113+
- : `string`. The tab's URL, if it has changed.
115114

116115
## Examples
117116

@@ -160,7 +159,7 @@ function handleUpdated(tabId, changeInfo, tabInfo) {
160159
browser.tabs.onUpdated.addListener(handleUpdated, filter);
161160
```
162161

163-
Log changes only to the `pinned` property of tabs (i.e. pin and unpin actions):
162+
Log changes only to the `pinned` property of tabs (that is, pin and unpin actions):
164163

165164
```js
166165
const filter = {
@@ -176,10 +175,7 @@ function handleUpdated(tabId, changeInfo, tabInfo) {
176175
browser.tabs.onUpdated.addListener(handleUpdated, filter);
177176
```
178177

179-
Combine both the previous filters: log changes only:
180-
181-
- to the `pinned` property of tabs
182-
- whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet`:
178+
Combine both the previous filters, log only when the `pinned` property of tabs changes for tabs whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet`:
183179

184180
```js
185181
const pattern1 = "https://developer.mozilla.org/*";
@@ -201,11 +197,7 @@ browser.tabs.onUpdated.addListener(
201197
filter);
202198
```
203199

204-
Log changes only:
205-
206-
- to the `pinned` property of tabs
207-
- whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet`
208-
- and which are part of the current browser window at the time the update event is fired:
200+
Log changes only when the `pinned` property of tabs changes for tabs whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet` where the tab was part of the current browser window when the update event fired:
209201

210202
```js
211203
const pattern1 = "https://developer.mozilla.org/*";

0 commit comments

Comments
 (0)