browser.management

說明

chrome.management API 提供管理已安裝應用程式和擴充功能的方法。

權限

management

您必須在擴充功能資訊清單中宣告「管理」權限，才能使用管理 API。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "management"
  ],
  ...
}

management.getPermissionWarningsByManifest()、management.uninstallSelf() 和 management.getSelf() 不需要管理權限。

類型

ExtensionDisabledReason

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

停用項目的原因。

列舉

"unknown"

"permissions_increase"

ExtensionInfo

已安裝擴充功能、應用程式或主題的相關資訊。

屬性

• appLaunchUrl

  字串 選填

  啟動網址 (僅適用於應用程式)。

• availableLaunchTypes

  LaunchType[] 選用

  目前可用的啟動類型 (僅適用於應用程式)。

• 說明

  字串

  這項擴充功能、應用程式或主題的說明。

• disabledReason

  ExtensionDisabledReason 選填

  停用項目的原因。

• 已啟用

  布林值

  目前是否已啟用。

• homepageUrl

  字串 選填

  這個擴充功能、應用程式或主題的首頁網址。

• hostPermissions

  string[]

  傳回主機權限清單。

• 圖示

  IconInfo[] 選用

  圖示資訊清單。請注意，這只是反映資訊清單中宣告的內容，該網址的實際圖片可能大於或小於宣告的大小，因此建議您在參照這些圖片的 img 標記上，使用明確的寬度和高度屬性。詳情請參閱圖示資訊清單說明文件。

• id

  字串

  擴充功能的專屬 ID。

• installType

  ExtensionInstallType

  擴充功能的安裝方式。

• isApp

  布林值

  已淘汰

  請使用 management.ExtensionInfo.type。

  如果這是應用程式，則為「true」。

• launchType

  LaunchType 選填

  應用程式啟動類型 (僅適用於應用程式)。

• mayDisable

  布林值

  使用者是否可以停用或解除安裝這項擴充功能。

• mayEnable

  布林值 選填

  Chrome 62+ 瀏覽器。*自 Chrome 148 起

  使用者是否可以啟用這項擴充功能。只有未啟用的擴充功能才會傳回這個值。

• 名稱

  字串

  這個擴充功能、應用程式或主題的名稱。

• offlineEnabled

  布林值

  擴充功能、應用程式或主題是否宣告支援離線。

• optionsUrl

  字串

  項目的選項頁面網址 (如果有的話)。

• 權限

  string[]

  傳回 API 權限清單。

• shortName

  字串

  這個擴充功能、應用程式或主題的簡短名稱。

• 類型

  ExtensionType

  這個擴充功能、應用程式或主題的類型。

• updateUrl

  字串 選填

  這個擴充功能、應用程式或主題的更新網址。

• 版本

  字串

  這個擴充功能、應用程式或主題的版本。

• versionName

  字串 選填

  Chrome 50 以上版本 Chrome 148 以上版本的 browser.*

  如果資訊清單有指定版本名稱，則為這個擴充功能、應用程式或主題的版本名稱。

ExtensionInstallType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

擴充功能的安裝方式。admin：擴充功能是依管理政策安裝， development：擴充功能是在開發人員模式中以未封裝狀態載入， normal：擴充功能是透過 .crx 檔案正常安裝， sideload：擴充功能是由機器上的其他軟體安裝， other：擴充功能是透過其他方式安裝。

列舉

"admin"

"development"

"normal"

"sideload"

"other"

ExtensionType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

這項擴充功能、應用程式或主題的類型。

列舉

"extension"

"hosted_app"

"packaged_app"

"legacy_packaged_app"

「主題」

"login_screen_extension"

IconInfo

擴充功能、應用程式或主題的圖示資訊。

屬性

• 大小

  數字

  代表圖示寬度和高度的數字。可能的值包括 (但不限於) 128、48、24 和 16。

• 網址

  字串

  這個圖示圖片的網址。如要顯示灰階版本的圖示 (例如表示擴充功能已停用)，請在網址後方附加 ?grayscale=true。

LaunchType

以下是所有可能的應用程式啟動類型。

列舉

"OPEN_AS_REGULAR_TAB"

"OPEN_AS_PINNED_TAB"

"OPEN_AS_WINDOW"

"OPEN_FULL_SCREEN"

UninstallOptions

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

擴充功能解除安裝的處理方式選項。

屬性

• showConfirmDialog

  布林值 選填

  是否應向使用者顯示確認解除安裝對話方塊。如果是自行解除安裝，預設值為 false。如果擴充功能解除安裝其他擴充功能，系統會忽略這個參數，一律顯示對話方塊。

方法

createAppShortcut()

browser.management.createAppShortcut(
  id: string,
): Promise<void>

顯示為應用程式建立捷徑的選項。在 Mac 上，只能建立封裝應用程式捷徑。

參數

• id

  字串

  這應該是 management.ExtensionInfo 應用程式項目的 ID。

傳回

• 承諾<void>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

generateAppForLink()

browser.management.generateAppForLink(
  url: string,
  title: string,
): Promise<ExtensionInfo>

為網址產生應用程式。傳回產生的書籤應用程式。

參數

• 網址

  字串

  網頁的網址。網址的配置只能是「http」或「https」。

• title

  字串

  生成應用程式的標題。

傳回

• <ExtensionInfo> 的 Promise

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

get()

browser.management.get(
  id: string,
): Promise<ExtensionInfo>

傳回已安裝擴充功能、應用程式或主題的資訊 (依指定 ID)。

參數

• id

  字串

  management.ExtensionInfo 項目的 ID。

傳回

• <ExtensionInfo> 的 Promise

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

getAll()

browser.management.getAll(): Promise<ExtensionInfo[]>

傳回已安裝擴充功能和應用程式的資訊清單。

傳回

• Promise<ExtensionInfo[]>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

getPermissionWarningsById()

browser.management.getPermissionWarningsById(
  id: string,
): Promise<string[]>

傳回指定擴充功能 ID 的權限警告清單。

參數

• id

  字串

  已安裝擴充功能的 ID。

傳回

• Promise<string[]>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

getPermissionWarningsByManifest()

browser.management.getPermissionWarningsByManifest(
  manifestStr: string,
): Promise<string[]>

針對指定的擴充功能資訊清單字串，傳回權限警告清單。注意：使用這項函式時，不必在資訊清單中要求「management」權限。

參數

• manifestStr

  字串

  擴充功能資訊清單 JSON 字串。

傳回

• Promise<string[]>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

getSelf()

browser.management.getSelf(): Promise<ExtensionInfo>

傳回呼叫擴充功能、應用程式或主題的相關資訊。注意：使用這項函式時，不必在資訊清單中要求「management」權限。

傳回

• <ExtensionInfo> 的 Promise

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

installReplacementWebApp()

Chrome 77 以上版本 瀏覽器。*自 Chrome 148 起

browser.management.installReplacementWebApp(): Promise<void>

啟動資訊清單中指定的 replacement_web_app。如果尚未安裝，系統會提示使用者安裝。

傳回

• 承諾<void>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

launchApp()

browser.management.launchApp(
  id: string,
): Promise<void>

啟動應用程式。

參數

• id

  字串

  應用程式的擴充功能 ID。

傳回

• 承諾<void>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

setEnabled()

browser.management.setEnabled(
  id: string,
  enabled: boolean,
): Promise<void>

啟用或停用應用程式或擴充功能。在多數情況下，這項函式必須在使用者手勢 (例如按鈕的 onclick 處理常式) 的情境中呼叫，且可能會向使用者顯示原生確認 UI，以防濫用。

參數

• id

  字串

  這應該是 management.ExtensionInfo 項目的 ID。

• 已啟用

  布林值

  是否應啟用或停用這個項目。

傳回

• 承諾<void>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

setLaunchType()

browser.management.setLaunchType(
  id: string,
  launchType: LaunchType,
): Promise<void>

設定應用程式的啟動類型。

參數

• id

  字串

  這應該是 management.ExtensionInfo 應用程式項目的 ID。

• launchType

  LaunchType

  目標啟動類型。請務必檢查並確認此啟動類型位於 ExtensionInfo.availableLaunchTypes 中，因為可用的啟動類型會因平台和設定而異。

傳回

• 承諾<void>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

uninstall()

browser.management.uninstall(
  id: string,
  options?: UninstallOptions,
): Promise<void>

解除安裝目前安裝的應用程式或擴充功能。注意：在受管理環境中，如果使用者不允許解除安裝指定的擴充功能/應用程式，這項函式就無法運作。如果解除安裝失敗 (例如使用者取消對話方塊)，系統會拒絕承諾，或呼叫回呼並設定 runtime.lastError。

參數

• id

  字串

  這應該是 management.ExtensionInfo 項目的 ID。

• 選項

  UninstallOptions 選填

傳回

• 承諾<void>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

uninstallSelf()

browser.management.uninstallSelf(
  options?: UninstallOptions,
): Promise<void>

解除安裝通話擴充功能。注意：使用這項函式時，不必在資訊清單中要求「管理」權限。在受管理環境中，如果使用者無法解除安裝指定的擴充功能/應用程式，這項功能就無法運作。

參數

• 選項

  UninstallOptions 選填

傳回

• 承諾<void>

  Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

事件

onDisabled

browser.management.onDisabled.addListener(
  callback: function,
)

在應用程式或擴充功能停用時觸發。

參數

• callback

  函式

  callback 參數如下：

  (info: ExtensionInfo) => void

  • 資訊

    ExtensionInfo

onEnabled

browser.management.onEnabled.addListener(
  callback: function,
)

在應用程式或擴充功能啟用時觸發。

參數

• callback

  函式

  callback 參數如下：

  (info: ExtensionInfo) => void

  • 資訊

    ExtensionInfo

onInstalled

browser.management.onInstalled.addListener(
  callback: function,
)

在安裝應用程式或擴充功能時觸發。

參數

• callback

  函式

  callback 參數如下：

  (info: ExtensionInfo) => void

  • 資訊

    ExtensionInfo

onUninstalled

browser.management.onUninstalled.addListener(
  callback: function,
)

在解除安裝應用程式或擴充功能時觸發。

參數

• callback

  函式

  callback 參數如下：

  (id: string) => void

  • id

    字串