browser.contentSettings

說明

使用 chrome.contentSettings API 變更設定，控制網站是否能使用 Cookie、JavaScript 和外掛程式等功能。一般來說，內容設定可讓您自訂 Chrome 在個別網站上的行為，而非全域行為。

權限

contentSettings

您必須在擴充功能的資訊清單中宣告 "contentSettings" 權限，才能使用 API。例如：

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

概念和用途

內容設定模式

您可以使用模式指定每項內容設定會影響哪些網站。舉例來說，https://*.youtube.com/* 會指定 youtube.com 及其所有子網域。內容設定模式的語法與比對模式相同，但有幾項差異：

  • 如果是 http、https 和 ftp 網址，路徑必須是萬用字元 (/*)。如果是 file 網址，則必須完整指定路徑，且「不得」包含萬用字元。
  • 與比對模式不同，內容設定模式可以指定通訊埠編號。如果指定通訊埠號碼，模式只會比對具有該通訊埠的網站。如未指定通訊埠編號，則模式會比對所有通訊埠。

模式優先順序

如果特定網站適用多項內容設定規則，系統會優先採用模式較明確的規則。

舉例來說，下列模式是依優先順序排列：

  1. https://www.example.com/*
  2. https://*.example.com/* (比對 example.com 和所有子網域)
  3. <all_urls> (比對所有網址)

有三種萬用字元會影響模式的具體程度：

  • 通訊埠中的萬用字元 (例如 https://www.example.com:*/*)
  • 配置中的萬用字元 (例如 *://www.example.com:123/*)
  • 主機名稱中的萬用字元 (例如 https://*.example.com:123/*)

如果某個模式在某個部分比另一個模式更具體，但在另一個部分較不具體，系統會依下列順序檢查不同部分：主機名稱、配置、通訊埠。舉例來說，下列模式會依優先順序排列：

  1. https://www.example.com:*/* 指定主機名稱和配置。
  2. *:/www.example.com:123/* 不高，因為雖然指定了主機名稱，但未指定配置。
  3. https://*.example.com:123/* 較低，因為雖然指定了通訊埠和配置，但主機名稱中有萬用字元。

主要和次要模式

系統會根據內容類型，決定要套用哪項內容設定。 舉例來說，contentSettings.notifications 設定是根據網址列中顯示的網址而定。這個網址稱為「主要」網址。

某些內容類型可納入其他網址。舉例來說，系統會根據 HTTP 要求的網址 (在本例中為主要網址) 和網址列中顯示的網址 (稱為「次要」網址)，決定是否允許網站設定 contentSettings.cookies。

如果有多項規則具有主要和次要模式，則以主要模式較明確的規則為準。如果多項規則的主要模式相同，則以次要模式較明確的規則為準。舉例來說，下列主要/次要模式組合清單是依優先順序排列：

優先順序主要模式次要模式
1https://www.moose.com/*、https://www.wombat.com/*
2https://www.moose.com/*、<all_urls>
3<all_urls>、https://www.wombat.com/*
4<all_urls>、<all_urls>

圖片內容設定不支援次要模式。

資源 ID

資源 ID 可讓你為特定內容類型的子類型指定內容設定。目前，唯一支援資源 ID 的內容類型是 contentSettings.plugins，其中資源 ID 會識別特定外掛程式。套用內容設定時，系統會先檢查特定外掛程式的設定。如果找不到特定外掛程式的設定，系統會檢查外掛程式的一般內容設定。

舉例來說，如果內容設定規則具有資源 ID adobe-flash-player 和模式 <all_urls>，則其優先順序會高於沒有資源 ID 和模式 https://www.example.com/* 的規則，即使該模式更具體也一樣。

您可以呼叫 contentSettings.ContentSetting.getResourceIdentifiers() 方法，取得內容類型的資源 ID 清單。傳回的清單可能會隨著使用者機器上安裝的外掛程式組合而變更，但 Chrome 會盡量在更新外掛程式時保持 ID 穩定。

範例

如要試用這個 API，請從 chrome-extension-samples 存放區安裝 contentSettings API 範例。

類型

AutoVerifyContentSetting

Chrome 113 以上版本 Chrome 148 起為 browser.*

列舉

"allow"

"block"

CameraContentSetting

Chrome 46 以上版本 Chrome 148 以上版本為 browser.*

列舉

"allow"

"block"

「ask」

ClipboardContentSetting

Chrome 121 以上版本 Chrome 148 以上版本為 browser.*

列舉

"allow"

"block"

「ask」

ContentSetting

屬性

  • 關閉

    void

    清除這項擴充功能設定的所有內容設定規則。

    clear 函式如下所示： 

    (details: object) => {...}

    • 詳細資料

      物件

      • 範圍

        Scope 選填

        清除設定的位置 (預設：一般)。

    • returns

      承諾<void>

      Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*
  • get

    void

    取得指定網址組合目前的內容設定。

    get 函式如下所示： 

    (details: object) => {...}

    • 詳細資料

      物件

      • incognito

        布林值 選填

        是否要檢查無痕模式工作階段的內容設定。(預設為 false)

      • primaryUrl

        字串

        要擷取內容設定的主要網址。請注意，主要網址的意義取決於內容類型。

      • resourceIdentifier

        ResourceIdentifier 選用

        更明確的 ID，用於指定要擷取設定的內容類型。

      • secondaryUrl

        字串 選填

        要擷取內容設定的次要網址。預設為主要網址。請注意，次要網址的意義取決於內容類型，且並非所有內容類型都會使用次要網址。

    • returns

      Promise<object>

      Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*
  • getResourceIdentifiers

    void

    getResourceIdentifiers 函式如下所示： 

    () => {...}

    • returns

      Promise<ResourceIdentifier[]>

      Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*
  • set

    void

    套用新的內容設定規則。

    set 函式如下所示： 

    (details: object) => {...}

    • 詳細資料

      物件

      • primaryPattern

        字串

        主要網址的模式。如要進一步瞭解模式格式，請參閱「內容設定模式」。

      • resourceIdentifier

        ResourceIdentifier 選用

        內容類型的資源 ID。

      • 範圍

        Scope 選填

        設定位置 (預設：一般)。

      • secondaryPattern

        字串 選填

        次要網址的模式。預設會比對所有網址。如要進一步瞭解模式格式，請參閱「內容設定模式」。

      • 設定

        任何

        這項規則套用的設定。如要查看可能的值，請參閱個別 ContentSetting 物件的說明。

    • returns

      承諾<void>

      Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

CookiesContentSetting

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

列舉

"allow"

"block"

"session_only"

FullscreenContentSetting

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

值

"allow"

ImagesContentSetting

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

列舉

"allow"

"block"

JavascriptContentSetting

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

列舉

"allow"

"block"

LocationContentSetting

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

列舉

"allow"

"block"

「ask」

MicrophoneContentSetting

Chrome 46 以上版本 Chrome 148 以上版本為 browser.*

列舉

"allow"

"block"

「ask」

MouselockContentSetting

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

值

"allow"

MultipleAutomaticDownloadsContentSetting

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

列舉

"allow"

"block"

「ask」

NotificationsContentSetting

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

列舉

"allow"

"block"

「ask」

PluginsContentSetting

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

值

"block"

PopupsContentSetting

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

列舉

"allow"

"block"

PpapiBrokerContentSetting

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

值

"block"

ResourceIdentifier

唯一使用資源 ID 的內容類型是 contentSettings.plugins。詳情請參閱「資源 ID」。

屬性

  • 說明

    字串 選填

    人類可讀的資源說明。

  • id

    字串

    指定內容類型的資源 ID。

Scope

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

ContentSetting 的範圍。regular：一般設定檔的設定 (如果未在其他地方覆寫，則由無痕模式設定檔繼承)， incognito\_session\_only：無痕模式設定檔的設定，只能在無痕模式工作階段期間設定，並在無痕模式工作階段結束時刪除 (覆寫一般設定)。

列舉

"regular"

"incognito_session_only"

SoundContentSetting

Chrome 141 以上版本 Chrome 148 以上版本：browser.*

列舉

"allow"

"block"

屬性

automaticDownloads

是否允許網站自動下載多個檔案。allow：允許網站自動下載多個檔案 block：不允許網站自動下載多個檔案 ask：在網站下載第一個檔案後，詢問是否要自動下載檔案 預設為 ask。主要網址是頂層頁框的網址。系統不會使用次要網址。

類型

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 以上版本 Chrome 148 起為 browser.*

是否允許網站使用 Private State Tokens API。allow：允許網站使用 Private State Tokens API。 block：禁止網站使用 Private State Tokens API。 預設為 allow。呼叫 set() 時，主要網址模式必須是 <all_urls>。系統不會使用次要網址。

類型

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 以上版本 Chrome 148 以上版本為 browser.*

是否允許網站存取攝影機。allow：允許網站存取攝影機、block：不允許網站存取攝影機、ask：在網站要求存取攝影機時詢問。預設為 ask。主要網址是指要求攝影機存取權的文件網址。系統不會使用次要網址。注意：如果兩個模式都是「<all_urls>」，則「allow」設定無效。

類型

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 以上版本 Chrome 148 以上版本為 browser.*

是否允許網站透過 Async Clipboard API 的進階功能存取剪貼簿。「進階」功能包括在使用者手勢後寫入內建格式以外的所有功能，例如讀取、寫入自訂格式，以及在沒有使用者手勢的情況下寫入。allow：允許網站使用進階剪貼簿功能 block：不允許網站使用進階剪貼簿功能 ask：在網站要求使用進階剪貼簿功能時詢問使用者。 預設為 ask。主要網址是指要求存取剪貼簿的文件網址。系統不會使用次要網址。

類型

ContentSetting<ClipboardContentSetting>

cookies

是否允許網站設定 Cookie 和其他本機資料。allow：接受 Cookie block：封鎖 Cookie session\_only：僅接受目前工作階段的 Cookie。 預設為 allow。主要網址代表 Cookie 來源。次要網址是頂層框架的網址。

類型

ContentSetting<CookiesContentSetting>

fullscreen

已淘汰。不再有任何作用。現在所有網站都會自動取得全螢幕權限。值一律為 allow。

類型

ContentSetting<FullscreenContentSetting>

images

是否顯示圖片。allow：顯示圖片。 block：不顯示圖片。預設為 allow。主要網址是頂層頁框的網址。次要網址是圖片的網址。

類型

ContentSetting<ImagesContentSetting>

javascript

是否執行 JavaScript。allow：執行 JavaScript。 block：不執行 JavaScript。預設為 allow。主要網址是頂層頁框的網址。系統不會使用次要網址。

類型

ContentSetting<JavascriptContentSetting>

location

是否允許地理位置。allow：允許網站追蹤您的實際位置、block：不允許網站追蹤您的實際位置、ask：在允許網站追蹤您的實際位置前，先詢問您。預設為 ask。主要網址是要求位置資料的文件網址。次要網址是頂層框架的網址 (可能與要求網址不同)。

類型

ContentSetting<LocationContentSetting>

microphone

Chrome 46 以上版本 Chrome 148 以上版本為 browser.*

是否允許網站存取麥克風。allow：允許網站存取麥克風、block：不允許網站存取麥克風、ask：在網站要求存取麥克風時詢問。預設為 ask。主要網址是要求麥克風存取權的文件網址。系統不會使用次要網址。注意：如果兩個模式都是「<all_urls>」，則「allow」設定無效。

類型

ContentSetting<MicrophoneContentSetting>

mouselock

已淘汰。不再有任何作用。現在所有網站都會自動取得滑鼠鎖定權限。值一律為 allow。

類型

ContentSetting<MouselockContentSetting>

notifications

是否允許網站顯示桌面通知。可用的值如下： allow：允許網站顯示桌面通知 block：不允許網站顯示桌面通知 ask：在網站要求顯示桌面通知時詢問使用者預設為 ask。主要網址是指要顯示通知的文件網址。系統不會使用次要網址。

類型

ContentSetting<NotificationsContentSetting>

plugins

已淘汰。Chrome 88 移除 Flash 支援後，這項權限就不再有效。值一律為 block。系統會忽略對 set() 和 clear() 的呼叫。

類型

ContentSetting<PluginsContentSetting>

popups

是否允許網站顯示彈出式視窗。可用的值如下： allow：允許網站顯示彈出式視窗 block：不允許網站顯示彈出式視窗 預設為 block。主要網址是頂層頁框的網址。系統不會使用次要網址。

類型

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

已淘汰。這項政策先前可控管是否允許網站在沙箱外執行外掛程式，但 Chrome 88 移除了 Flash 代理程式程序，因此這項權限已不再有效。值一律為 block。系統會忽略對 set() 和 clear() 的呼叫。

類型

ContentSetting<PpapiBrokerContentSetting>