chrome.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 設定是以 網址列。這個網址稱為「主要」網址網址。

有些內容類型可能會將額外網址納入考量。例如，網站是否 設定 contentSettings.cookies 取決於 HTTP 要求的網址 (也就是 主要網址)，以及網址列中顯示的網址 (稱為「次要」 網址)。

如有多項規則有主要和次要模式，則會包含指定範圍最明確的主要和次要模式 模式的優先順序最高如果多項規則的主要模式相同，表示含有 且以更具體的次要模式為準。舉例來說，下列 系統會按照優先順序排列主要/次要模式組合：

優先順序主要模式次要模式
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() 方法，增加圍繞地圖邊緣的邊框間距。傳回的清單可以隨著 使用者電腦上已安裝的外掛程式組合，但 Chrome 會嘗試讓 ID 保持穩定 各項外掛程式更新

範例

如要試用這個 API，請安裝 chrome-extension-samples 提供的 contentSettings API 範例 Cloud Storage 也提供目錄同步處理功能

類型

AutoVerifyContentSetting

Chrome 113 以上版本

列舉

"allow"

「封鎖」

CameraContentSetting

Chrome 46 以上版本

列舉

"allow"

「封鎖」

"ask"

ClipboardContentSetting

Chrome 121 以上版本

列舉

"allow"

「封鎖」

"ask"

ContentSetting

屬性

  • 關閉

    void

    Promise

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

    clear 函式如下所示： 

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

    • 詳細資料

      物件

      • 範圍

        範圍 選用

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

    • 回呼

      函式 選用

      callback 參數如下所示： 

      () => void

    • returns

      承諾<void>

      Chrome 96 以上版本

      Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

  • get

    void

    Promise

    取得特定一組網址目前的內容設定。

    get 函式如下所示： 

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

    • 詳細資料

      物件

      • 無痕模式

        布林值 選填

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

      • primaryUrl

        字串

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

      • resourceIdentifier

        ResourceIdentifier 選用

        更具體的 ID，指定要擷取設定的內容類型。

      • secondaryUrl

        string optional

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

    • 回呼

      函式 選用

      callback 參數如下所示： 

      (details: object) => void

      • 詳細資料

        物件

        • 設定

          T

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

    • returns

      Promise&lt;object&gt;

      Chrome 96 以上版本

      Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

  • getResourceIdentifiers

    void

    Promise

    getResourceIdentifiers 函式如下所示： 

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

    • 回呼

      函式 選用

      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。

      • 範圍

        範圍 選用

        配置的設置位置 (預設值：一般)。

      • secondaryPattern

        string optional

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

      • 設定

        不限

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

    • 回呼

      函式 選用

      callback 參數如下所示： 

      () => void

    • returns

      承諾<void>

      Chrome 96 以上版本

      Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

CookiesContentSetting

Chrome 44 以上版本

列舉

"allow"

「封鎖」

&quot;session_only&quot;

FullscreenContentSetting

Chrome 44 以上版本

值

"allow"

ImagesContentSetting

Chrome 44 以上版本

列舉

"allow"

「封鎖」

JavascriptContentSetting

Chrome 44 以上版本

列舉

"allow"

「封鎖」

LocationContentSetting

Chrome 44 以上版本

列舉

"allow"

「封鎖」

"ask"

MicrophoneContentSetting

Chrome 46 以上版本

列舉

"allow"

「封鎖」

"ask"

MouselockContentSetting

Chrome 44 以上版本

值

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 以上版本

列舉

"allow"

「封鎖」

"ask"

NotificationsContentSetting

Chrome 44 以上版本

列舉

"allow"

「封鎖」

"ask"

PluginsContentSetting

Chrome 44 以上版本

值

「封鎖」

PopupsContentSetting

Chrome 44 以上版本

列舉

"allow"

「封鎖」

PpapiBrokerContentSetting

Chrome 44 以上版本

值

「封鎖」

ResourceIdentifier

只有 contentSettings.plugins 會使用資源 ID 的內容類型。詳情請參閱「資源 ID」。

屬性

  • 說明

    string optional

    使用者可理解的資源說明。

  • id

    字串

    特定內容類型的資源 ID。

Scope

Chrome 44 以上版本

ContentSetting 的範圍。下列其中一項 regular：一般設定檔的設定 (如果未在其他設定覆寫，就會由無痕模式設定檔沿用) incognito\_session\_only：這種設定只適用於無痕模式工作階段，且只能在無痕模式工作階段結束後刪除 (會覆寫一般設定)。

列舉

"regular"

"incognito_session_only"

屬性

automaticDownloads

是否允許網站自動下載多個檔案。下列其中一項 allow：允許網站自動下載多個檔案。 block：禁止網站自動下載多個檔案。 ask：網站要下載第一個檔案後再自動下載檔案時必須先詢問你。 預設值為 ask。 主要網址是頂層頁框的網址。請勿使用次要網址。

類型

ContentSetting&lt;MultipleAutomaticDownloadsContentSetting&gt;

autoVerify

Chrome 113 以上版本

是否允許網站使用 Private State Tokens API。下列其中一項 allow：允許網站使用 Private State Tokens API。 block：禁止網站使用 Private State Tokens API。 預設值為 allow。 主要網址是頂層頁框的網址。請勿使用次要網址。注意：呼叫 set() 時，主要模式必須為 。

類型

ContentSetting&lt;AutoVerifyContentSetting&gt;

camera

Chrome 46 以上版本

是否允許網站存取攝影機。下列其中一項 allow：允許網站使用攝影機。 block：不允許網站使用攝影機。 ask：網站要存取攝影機時詢問你。 預設值為 ask。 主要網址是要求相機存取權的文件網址。請勿使用次要網址。 注意：「允許」如果兩個模式都是 '，則設定無效。

類型

ContentSetting&lt;CameraContentSetting&gt;

clipboard

Chrome 121 以上版本

是否允許網站透過 Async Clipboard API 的進階功能存取剪貼簿。「進階」除了在使用者手勢後編寫內建格式之外，相關功能也包括讀取、寫入自訂格式，以及不需使用者手勢即可撰寫內容。下列其中一項 allow：允許網站使用進階剪貼簿功能。 block：禁止網站使用進階剪貼簿功能。 ask：網站要使用進階剪貼簿功能時，必須先詢問你。 預設值為 ask。 主要網址是要求剪貼簿存取權的文件網址。請勿使用次要網址。

類型

ContentSetting&lt;ClipboardContentSetting&gt;

cookies

是否允許網站設定 Cookie 和其他本機資料。下列其中一項 allow：接受 Cookie， block：封鎖 Cookie、 session\_only：只接受目前工作階段的 Cookie。 預設值為 allow。 主要網址是代表 Cookie 來源的網址。次要網址是頂層頁框的網址。

類型

ContentSetting&lt;CookiesContentSetting&gt;

fullscreen

已淘汰。完全不會產生任何影響。系統現在會自動向所有網站授予全螢幕權限。值一律為 allow。

類型

ContentSetting&lt;FullscreenContentSetting&gt;

images

是否顯示圖片。下列其中一項 allow：顯示圖片 block：不顯示圖片。 預設值為 allow。 主要網址是頂層頁框的網址。次要網址是圖片的網址。

類型

ContentSetting&lt;ImagesContentSetting&gt;

javascript

是否執行 JavaScript。下列其中一項 allow：執行 JavaScript。 block：請勿執行 JavaScript。 預設值為 allow。 主要網址是頂層頁框的網址。請勿使用次要網址。

類型

ContentSetting&lt;JavascriptContentSetting&gt;

location

是否允許地理位置。下列其中一項 allow：允許網站追蹤你的實際位置。 block：不允許網站追蹤你的實際位置。 ask：必須先詢問你，才能允許網站追蹤你的實際位置。 預設值為 ask。 主要網址是指要求位置資料的文件網址。次要網址是頂層頁框的網址 (不一定與要求網址不同)。

類型

ContentSetting&lt;LocationContentSetting&gt;

microphone

Chrome 46 以上版本

是否允許網站存取麥克風。下列其中一項 allow：允許網站存取麥克風。 block：不允許網站存取麥克風。 ask：網站要存取麥克風時詢問你。 預設值為 ask。 主要網址是指要求麥克風存取權的文件網址。請勿使用次要網址。 注意：「允許」如果兩個模式都是 '，則設定無效。

類型

ContentSetting&lt;MicrophoneContentSetting&gt;

mouselock

已淘汰。完全不會產生任何影響。系統現在會自動為所有網站授予滑鼠鎖定權限。值一律為 allow。

類型

ContentSetting&lt;MouselockContentSetting&gt;

notifications

是否允許網站顯示桌面通知。下列其中一項 allow：允許網站顯示桌面通知。 block：不允許網站顯示桌面通知。 ask：網站要顯示桌面通知時，必須先詢問你。 預設值為 ask。 主要網址是指要顯示通知的文件網址。請勿使用次要網址。

類型

ContentSetting&lt;NotificationsContentSetting&gt;

plugins

已淘汰。在 Chrome 第 88 版中移除 Flash 後，這項權限就無法再產生。值一律為 block。系統會忽略對 set() 和 clear() 的呼叫。

類型

ContentSetting&lt;PluginsContentSetting&gt;

popups

是否允許網站顯示彈出式視窗。下列其中一項 allow：允許網站顯示彈出式視窗。 block：不允許網站顯示彈出式視窗。 預設值為 block。 主要網址是頂層頁框的網址。請勿使用次要網址。

類型

ContentSetting&lt;PopupsContentSetting&gt;

unsandboxedPlugins

已淘汰。過去，控制是否允許網站在無沙箱防護的情況下執行外掛程式，但在 Chrome 第 88 版中移除 Flash 代理程式程序後，這項權限就會失效。值一律為 block。系統會忽略對 set() 和 clear() 的呼叫。

類型

ContentSetting&lt;PpapiBrokerContentSetting&gt;