chrome.contentSettings

refresh date: 2026-09-25 robots: noindex

說明

使用 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 以上版本

列舉

"allow"

"block"

CameraContentSetting

Chrome 46 以上版本

列舉

"allow"

"block"

「ask」

ClipboardContentSetting

Chrome 121 以上版本

列舉

"allow"

"block"

「ask」

ContentSetting

屬性

  • 關閉

    void

    Promise

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

    clear 函式如下所示： 

    (details: object, callback?: function) => {...}

    • 詳細資料

      物件

      • 範圍

        Scope 選填

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

    • callback

      函式 選填

      callback 參數如下： 

      () => void

    • returns

      承諾<void>

      Chrome 96 以上版本

      Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

  • get

    void

    Promise

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

    get 函式如下所示： 

    (details: object, callback?: function) => {...}

    • 詳細資料

      物件

      • incognito

        布林值 選填

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

      • primaryUrl

        字串

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

      • resourceIdentifier

        ResourceIdentifier 選用

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

      • secondaryUrl

        字串 選填

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

    • callback

      函式 選填

      callback 參數如下： 

      (details: object) => void

      • 詳細資料

        物件

        • 設定

          T

          內容設定。如要查看可能的值，請參閱個別 ContentSetting 物件的說明。

    • returns

      Promise<object>

      Chrome 96 以上版本

      Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

  • getResourceIdentifiers

    void

    Promise

    getResourceIdentifiers 函式如下所示： 

    (callback?: function) => {...}

    • callback

      函式 選填

      callback 參數如下： 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] 選用

        這個內容類型的資源 ID 清單，如果這個內容類型未使用資源 ID，則為 undefined。

    • returns

      Promise<ResourceIdentifier[]>

      Chrome 96 以上版本

      Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

  • set

    void

    Promise

    套用新的內容設定規則。

    set 函式如下所示： 

    (details: object, callback?: function) => {...}

    • 詳細資料

      物件

      • primaryPattern

        字串

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

      • resourceIdentifier

        ResourceIdentifier 選用

        內容類型的資源 ID。

      • 範圍

        Scope 選填

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

      • secondaryPattern

        字串 選填

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

      • 設定

        任何

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

    • callback

      函式 選填

      callback 參數如下： 

      () => void

    • returns

      承諾<void>

      Chrome 96 以上版本

      Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

CookiesContentSetting

Chrome 44 以上版本

列舉

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 以上版本

值

"allow"

ImagesContentSetting

Chrome 44 以上版本

列舉

"allow"

"block"

JavascriptContentSetting

Chrome 44 以上版本

列舉

"allow"

"block"

LocationContentSetting

Chrome 44 以上版本

列舉

"allow"

"block"

「ask」

MicrophoneContentSetting

Chrome 46 以上版本

列舉

"allow"

"block"

「ask」

MouselockContentSetting

Chrome 44 以上版本

值

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 以上版本

列舉

"allow"

"block"

「ask」

NotificationsContentSetting

Chrome 44 以上版本

列舉

"allow"

"block"

「ask」

PluginsContentSetting

Chrome 44 以上版本

值

"block"

PopupsContentSetting

Chrome 44 以上版本

列舉

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 以上版本

值

"block"

ResourceIdentifier

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

屬性

  • 說明

    字串 選填

    人類可讀的資源說明。

  • id

    字串

    指定內容類型的資源 ID。

Scope

Chrome 44 以上版本

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

列舉

"regular"

"incognito_session_only"

SoundContentSetting

Chrome 141 以上版本

列舉

"allow"

"block"

屬性

automaticDownloads

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

類型

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 以上版本

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

類型

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 以上版本

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

類型

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 以上版本

是否允許網站透過 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 以上版本

是否允許網站存取麥克風。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>