Skip to content

Commit 3ffce2e

Browse files
rebloorRob--Wgithub-actions[bot]dotproto
authored
Addition of the webextensions.api.tabGroups documentation (#39370)
* Addition of the `webextensions.api.tabGroups` documentation * Update `tabs` API with reference to `tabGroups.TAB_GROUP_ID_NONE` * Additional documentation per Chrome * Clarified onMove differences in Chrome * Update files/en-us/mozilla/add-ons/webextensions/api/tabgroups/color/index.md Co-authored-by: Rob Wu <rob@robwu.nl> * Update files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md Co-authored-by: Rob Wu <rob@robwu.nl> * Update files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md Co-authored-by: Rob Wu <rob@robwu.nl> * Apply suggestions from review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Rob Wu <rob@robwu.nl> * Apply suggestions from review Co-authored-by: Rob Wu <rob@robwu.nl> * Apply suggestions from review Co-authored-by: Rob Wu <rob@robwu.nl> * Apply suggestions from review Co-authored-by: Rob Wu <rob@robwu.nl> * Apply suggestions from review Co-authored-by: Rob Wu <rob@robwu.nl> * Apply suggestions from linter Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Further feedback changes * Apply suggestions from review Co-authored-by: Rob Wu <rob@robwu.nl> * Apply suggestions from review Co-authored-by: Simeon Vincent <svincent@gmail.com> Co-authored-by: Rob Wu <rob@robwu.nl> * Linter feedback on review changes Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Feedback update updates * Review feedback Co-authored-by: Rob Wu <rob@robwu.nl> * Remove note about resolved bug --------- Co-authored-by: Rob Wu <rob@robwu.nl> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Simeon Vincent <svincent@gmail.com>
1 parent ee756fd commit 3ffce2e

File tree

19 files changed

+579
-6
lines changed

19 files changed

+579
-6
lines changed

‎files/en-us/mozilla/add-ons/webextensions/api/tabgroups/color/index.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: tabGroups.Color
3+
slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/Color
4+
page-type: webextension-api-type
5+
browser-compat: webextensions.api.tabGroups.Color
6+
---
7+
8+
{{AddonSidebar}}
9+
10+
The color of a tab group.
11+
12+
## Type
13+
14+
Values of this type are a string and can take these values:
15+
16+
- blue
17+
- cyan
18+
- grey
19+
- green
20+
- orange
21+
- pink
22+
- purple
23+
- red
24+
- yellow
25+
26+
{{WebExtExamples("h2")}}
27+
28+
## Browser compatibility
29+
30+
{{Compat}}

‎files/en-us/mozilla/add-ons/webextensions/api/tabgroups/get/index.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: tabGroups.get
3+
slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/get
4+
page-type: webextension-api-function
5+
browser-compat: webextensions.api.tabGroups.get
6+
---
7+
8+
{{AddonSidebar}}
9+
10+
Returns details about a tab group.
11+
12+
## Syntax
13+
14+
```js-nolint
15+
let tabGroupDetails = await browser.tabGroups.get(
16+
groupId // integer
17+
);
18+
```
19+
20+
### Parameters
21+
22+
- `groupId`
23+
- : `integer`. The ID of the tab group to return details for.
24+
25+
### Return value
26+
27+
A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message.
28+
29+
{{WebExtExamples("h2")}}
30+
31+
## Browser compatibility
32+
33+
{{Compat}}

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: tabGroups
3+
slug: Mozilla/Add-ons/WebExtensions/API/tabGroups
4+
page-type: webextension-api
5+
browser-compat: webextensions.api.tabGroups
6+
---
7+
8+
{{AddonSidebar}}
9+
10+
This API enables extensions to modify and rearrange [tab groups](https://support.mozilla.org/en-US/kb/tab-groups).
11+
12+
Tab groups may persist across browser restarts as part of session restore. Tab groups in private browsing windows do not persist across restarts. When a tab group is restored, its `groupId` may differ from its original value.
13+
14+
The `tabGroups` API doesn't offer the ability to create or remove tab groups. Use the {{WebExtAPIRef("tabs.group()")}} and {{WebExtAPIRef("tabs.ungroup()")}} methods instead. To query the position of a tab group within a window, use {{WebExtAPIRef("tabs.query()")}}. These APIs in the `tabs` namespace don't require any permissions.
15+
16+
## Permissions
17+
18+
To use this API, an extension must request the `"tabGroups"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. The `"tabGroups"` permission is not shown to users in permission prompts.
19+
20+
## Types
21+
22+
- {{WebExtAPIRef("tabGroups.Color")}}
23+
- : The color of a tab group.
24+
- {{WebExtAPIRef("tabGroups.TabGroup")}}
25+
- : The state of a tab group.
26+
27+
## Properties
28+
29+
- {{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}}
30+
- : The tab group ID value returned when a tab isn't in a tab group.
31+
32+
## Functions
33+
34+
- {{WebExtAPIRef("tabGroups.get()")}}
35+
- : Returns details about a tab group.
36+
- {{WebExtAPIRef("tabGroups.move()")}}
37+
- : Moves a tab group within or to another window.
38+
- {{WebExtAPIRef("tabGroups.query()")}}
39+
- : Returns all tab groups or finds tab groups with certain properties.
40+
- {{WebExtAPIRef("tabGroups.update()")}}
41+
- : Modifies the state of a tab group.
42+
43+
## Events
44+
45+
- {{WebExtAPIRef("tabGroups.onCreated")}}
46+
- : Fires when a tab group is created.
47+
- {{WebExtAPIRef("tabGroups.onMoved")}}
48+
- : Fires when a tab group is moved within a window or to another window.
49+
- {{WebExtAPIRef("tabGroups.onRemoved")}}
50+
- : Fires when a tab group is removed.
51+
- {{WebExtAPIRef("tabGroups.onUpdated")}}
52+
- : Fires when a tab group is updated.
53+
54+
{{WebExtExamples("h2")}}
55+
56+
## Browser compatibility
57+
58+
{{Compat}}
59+
60+
## See also
61+
62+
- {{WebExtAPIRef("tabs.group()")}}
63+
- {{WebExtAPIRef("tabs.ungroup()")}}
64+
- {{WebExtAPIRef("tabs.query()")}}
65+
- {{WebExtAPIRef("tabs.Tab")}}

‎files/en-us/mozilla/add-ons/webextensions/api/tabgroups/move/index.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: tabGroups.move
3+
slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/move
4+
page-type: webextension-api-function
5+
browser-compat: webextensions.api.tabGroups.move
6+
---
7+
8+
{{AddonSidebar}}
9+
10+
Moves a tab group within or to another window. Groups can't be moved before a pinned tab or inside another tab group.
11+
12+
## Syntax
13+
14+
```js-nolint
15+
let movedTabGroup = await browser.tabGroups.move(
16+
groupId, // integer
17+
moveProperties // object
18+
);
19+
```
20+
21+
### Parameters
22+
23+
- `groupId`
24+
25+
- : `integer` The ID of the tab group to move.
26+
27+
- `moveProperties`
28+
- : An object containing details of the location to move the tab group to.
29+
- `index`
30+
- : `integer`. The position to move the group to. After moving, the first tab in the tab group is at this index in the tab strip. Use -1 to place the group at the end of the window.
31+
- `windowId` {{optional_inline}}
32+
- : `integer`. The window to move the group to. Defaults to the window the group is in. Groups can only be moved to and from windows with {{WebExtAPIRef("windows.WindowType")}} type `"normal"`.
33+
34+
### Return value
35+
36+
A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message.
37+
38+
{{WebExtExamples("h2")}}
39+
40+
## Browser compatibility
41+
42+
{{Compat}}

‎files/en-us/mozilla/add-ons/webextensions/api/tabgroups/oncreated/index.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: tabGroups.onCreated
3+
slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onCreated
4+
page-type: webextension-api-event
5+
browser-compat: webextensions.api.tabGroups.onCreated
6+
---
7+
8+
{{AddonSidebar}}
9+
10+
Fires when a tab group is created.
11+
12+
In Chrome, this event is also fired when a tab group is moved between windows, instead of {{WebExtAPIRef("tabGroups.onMoved")}}.
13+
14+
## Syntax
15+
16+
```js-nolint
17+
browser.tabGroups.onCreated.addListener(listener)
18+
browser.tabGroups.onCreated.removeListener(listener)
19+
browser.tabGroups.onCreated.hasListener(listener)
20+
```
21+
22+
Events have three functions:
23+
24+
- `addListener(listener)`
25+
- : Adds a listener to this event.
26+
- `removeListener(listener)`
27+
- : Stops listening to this event. The `listener` argument is the listener to remove.
28+
- `hasListener(listener)`
29+
- : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
30+
31+
## addListener syntax
32+
33+
### Parameters
34+
35+
- `listener`
36+
37+
- : The function called when this event occurs. The function is passed this argument:
38+
39+
- `group`
40+
- : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the created tab group's state.
41+
42+
## Examples
43+
44+
Listen for and log tab group creation:
45+
46+
```js
47+
function tabGroupCreated(group) {
48+
console.log(
49+
`Tab group with ID ${group.id} was created in window ${group.windowId}.`,
50+
);
51+
}
52+
53+
browser.tabGroups.onCreated.addListener(tabGroupCreated);
54+
```
55+
56+
{{WebExtExamples}}
57+
58+
## Browser compatibility
59+
60+
{{Compat}}

‎files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: tabGroups.onMoved
3+
slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onMoved
4+
page-type: webextension-api-event
5+
browser-compat: webextensions.api.tabGroups.onMoved
6+
---
7+
8+
{{AddonSidebar}}
9+
10+
Fires when a tab group is moved within a window or to another window. {{WebExtAPIRef("tabs.onMoved")}} also fire for the tabs within the group.
11+
12+
The event is passed a {{WebExtAPIRef("tabGroups.TabGroup")}} object. This includes the `windowId` but not the position of the tab group. To determine the position of the tab group, use {{WebExtAPIRef("tabs.query()")}} with the `groupId`, and read the `index` property of the returned tab.
13+
14+
In Chrome, this event doesn't fire when a tab group is moved between windows; instead, the group is removed from one window and created in another (firing {{WebExtAPIRef("tabGroups.onRemoved")}} and {{WebExtAPIRef("tabGroups.onCreated")}}.
15+
16+
## Syntax
17+
18+
```js-nolint
19+
browser.tabGroups.onMoved.addListener(listener)
20+
browser.tabGroups.onMoved.removeListener(listener)
21+
browser.tabGroups.onMoved.hasListener(listener)
22+
```
23+
24+
Events have three functions:
25+
26+
- `addListener(listener)`
27+
- : Adds a listener to this event.
28+
- `removeListener(listener)`
29+
- : Stops listening to this event. The `listener` argument is the listener to remove.
30+
- `hasListener(listener)`
31+
- : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
32+
33+
## addListener syntax
34+
35+
### Parameters
36+
37+
- `listener`
38+
39+
- : The function called when this event occurs. The function is passed this argument:
40+
41+
- `group`
42+
- : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the moved tab group's state.
43+
44+
## Examples
45+
46+
Listen for and log tab group movement:
47+
48+
```js
49+
function tabGroupMoved(group) {
50+
console.log(
51+
`Tab group with ID ${group.id} was moved to window ${group.windowId}.`,
52+
);
53+
}
54+
55+
browser.tabGroups.onMoved.addListener(tabGroupMoved);
56+
```
57+
58+
Locate a tab group moved to another window.
59+
60+
```js
61+
browser.tabGroups.onMoved.addListener(group => {
62+
let tabs = await browser.tabs.query({
63+
groupId: group.id,
64+
});
65+
console.log(`Moved tab group to ${tabs[0].index} in window ${group.windowId}`);
66+
});
67+
```
68+
69+
{{WebExtExamples}}
70+
71+
## Browser compatibility
72+
73+
{{Compat}}

‎files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: tabGroups.onRemoved
3+
slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onRemoved
4+
page-type: webextension-api-event
5+
browser-compat: webextensions.api.tabGroups.onRemoved
6+
---
7+
8+
{{AddonSidebar}}
9+
10+
Fires when a tab group is removed. This occurs when a user closes a tab group or a tab group is closed automatically because another change means it no longer contained any tabs.
11+
12+
## Syntax
13+
14+
```js-nolint
15+
browser.tabGroups.onRemoved.addListener(listener)
16+
browser.tabGroups.onRemoved.removeListener(listener)
17+
browser.tabGroups.onRemoved.hasListener(listener)
18+
```
19+
20+
Events have three functions:
21+
22+
- `addListener(listener)`
23+
- : Adds a listener to this event.
24+
- `removeListener(listener)`
25+
- : Stops listening to this event. The `listener` argument is the listener to remove.
26+
- `hasListener(listener)`
27+
- : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
28+
29+
## addListener syntax
30+
31+
### Parameters
32+
33+
- `listener`
34+
35+
- : The function called when this event occurs. The function is passed this argument:
36+
37+
- `group`
38+
- : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the removed tab group's state.
39+
- `removeInfo`
40+
- : `object`. Information on why the tab group is closing.
41+
- `isWindowClosing`
42+
- : `boolean`. `true` if the tab group is removed because its window is closing.
43+
44+
## Examples
45+
46+
Listen for and log tab group removals:
47+
48+
```js
49+
function tabGroupRemoved(group) {
50+
console.log(`Tab group with ID ${group.id} was removed.`);
51+
}
52+
53+
browser.tabGroups.onRemoved.addListener(tabGroupRemoved);
54+
```
55+
56+
{{WebExtExamples}}
57+
58+
## Browser compatibility
59+
60+
{{Compat}}

0 commit comments

Comments
 (0)