diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/sidebaraction/settitle/index.md b/files/zh-cn/mozilla/add-ons/webextensions/api/sidebaraction/settitle/index.md new file mode 100644 index 00000000000000..0d1187527c5b70 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/sidebaraction/settitle/index.md @@ -0,0 +1,109 @@ +--- +title: sidebarAction.setTitle() +slug: Mozilla/Add-ons/WebExtensions/API/sidebarAction/setTitle +l10n: + sourceCommit: 665b94c45d49c71009c3e6c9a9e0f601b6af0d82 +--- + +{{AddonSidebar}} + +设置侧边栏的标题。标题会在浏览器列出可用侧边栏的地方显示。例如,Firefox 会在“查看 > 侧栏”菜单中显示这一标题。当侧边栏打开时,该标题还会显示在侧边栏的顶部。 + +## 标题类型 + +你的扩展应该在 [sidebar_action](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action) 清单键中指定侧边栏的标题(这被称为“_清单标题_”)。如果你没有指定清单标题,则将默认使用扩展名作为标题。 + +如果你使用 `setTitle()` 设置新标题,并包含了 `tabId` 选项,那么标题仅为给定的标签页设置。这个标题称为“_标签页特定标题_”。 + +如果你使用 `setTitle()` 设置新标题,并包含了 `windowId` 选项,那么标题仅为给定的窗口设置。这个标题称为“_窗口特定标题_”,并将出现在该窗口的所有没有设置标签页特定标题的标签页中。 + +如果你使用 `setTitle()` 设置新标题,并省略了 `tabId` 和 `windowId` 选项,那么这将设置“_全局标题_”。全局标题将出现在所有没有设置标签页特定标题的标签中,且其窗口没有设置窗口特定标题的标签页中。 + +## 语法 + +```js-nolint +browser.sidebarAction.setTitle( + details // 对象 +) +``` + +### 参数 + +- `details` + + - : `object`,包含下述属性的对象: + + - `title` + + - : `string` 或 `null`,侧边栏的新标题。 + + 如果 `title` 是空字符串,则使用扩展名作为标题,但 {{WebExtAPIRef("sidebarAction.getTitle")}} 仍会提供空字符串。 + + 如果 `title` 为 `null`,那么之前设置的标题将会被移除,并且: + + - 如果指定了 `tabId`,并且该标签页设置了标签页特定的标题,则该标签页将继承其所属窗口的标题。 + - 如果指定了 `windowId`,并且该窗口设置了特定的窗口标题,则该窗口将继承全局标题。 + - 否则,全局标题将被重置为清单标题。 + + - `tabId` {{optional_inline}} + - : `integer`。仅为指定的标签页设置标题。 + - `windowId` {{optional_inline}} + - : `integer`。仅为指定的窗口设置标题。 + + + +- 如果同时提供了 `windowId` 和 `tabId`,函数将失败且标题不会被设置。 +- 如果同时省略 `windowId` 和 `tabId`,则设置全局标题。 + +## 浏览器兼容性 + +{{Compat}} + +## 示例 + +下面代码在用户点击浏览器操作时更改侧边栏的标题(但仅对当前标签页更改): + +```js +let title = "一个不同的标题"; + +function setTitleForTab(tab) { + browser.sidebarAction.setTitle({ title, tabId: tab.id }); +} + +browser.browserAction.onClicked.addListener(setTitleForTab); +``` + +{{WebExtExamples}} + +> [!NOTE] +> 此 API 是基于 Opera 的 [`chrome.sidebarAction`](https://help.opera.com/en/extensions/sidebar-action-api/) API。 + +