chrome.contentSettings

說明

你可以使用 chrome.contentSettings API 變更設定，控管網站能否使用 Cookie、JavaScript 和外掛程式等功能。一般來說，內容設定可讓您自訂個別網站 (而非全球) 的行為。

權限

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() 方法，取得內容類型的資源 ID 清單。傳回的清單可能會隨使用者電腦上已安裝的外掛程式而變動，但 Chrome 會在所有外掛程式更新時，嘗試讓 ID 保持穩定。

示例

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

類型

AutoVerifyContentSetting

Chrome 113 以上版本

列舉

CameraContentSetting

Chrome 46 以上版本

列舉

ClipboardContentSetting

Chrome 121 以上版本

列舉

ContentSetting

屬性

  • 關閉

    void

    Promise

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

    clear 函式如下所示：

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

    • 詳細資料

      物件

      • 範圍

        範圍 選用

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

    • 回呼

      函式選用

      callback 參數如下所示： 

      ()=>void

    • returns

      Promise<void>

      Chrome 96 以上版本

      Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

  • get

    void

    Promise

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

    get 函式如下所示：

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

    • 詳細資料

      物件

      • 無痕模式

        布林值 (選用)

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

      • primaryUrl

        字串

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

      • resourceIdentifier

        ResourceIdentifier 選用

        應擷取設定的內容類型更明確的 ID。

      • secondaryUrl

        字串 選用

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

    • 回呼

      函式選用

      callback 參數如下所示： 

      (details: object)=>void

      • 詳細資料

        物件

        • 設定

          T

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

    • returns

      Promise<object>

      Chrome 96 以上版本

      Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

  • getResourceIdentifiers

    void

    Promise

    getResourceIdentifiers 函式如下所示：

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

    • 回呼

      函式選用

      callback 參數如下所示： 

      (resourceIdentifiers?: ResourceIdentifier[])=>void

      • resourceIdentifiers

        ResourceIdentifier[] 選用

        此內容類型的資源 ID 清單；如果此內容類型不使用資源 ID，則為 undefined。

    • returns

      Promise<ResourceIdentifier[]>

      Chrome 96 以上版本

      Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

  • set

    void

    Promise

    套用新的內容設定規則。

    set 函式如下所示：

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

    • 詳細資料

      物件

      • primaryPattern

        字串

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

      • resourceIdentifier

        ResourceIdentifier 選用

        內容類型的資源 ID。

      • 範圍

        範圍 選用

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

      • secondaryPattern

        字串 選用

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

      • 設定

        不限

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

    • 回呼

      函式選用

      callback 參數如下所示： 

      ()=>void

    • returns

      Promise<void>

      Chrome 96 以上版本

      Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

CookiesContentSetting

Chrome 44 以上版本

列舉

"session_only"

FullscreenContentSetting

Chrome 44 以上版本

值

ImagesContentSetting

Chrome 44 以上版本

列舉

JavascriptContentSetting

Chrome 44 以上版本

列舉

LocationContentSetting

Chrome 44 以上版本

列舉

MicrophoneContentSetting

Chrome 46 以上版本

列舉

MouselockContentSetting

Chrome 44 以上版本

值

MultipleAutomaticDownloadsContentSetting

Chrome 44 以上版本

列舉

NotificationsContentSetting

Chrome 44 以上版本

列舉

PluginsContentSetting

Chrome 44 以上版本

值

PopupsContentSetting

Chrome 44 以上版本

列舉

PpapiBrokerContentSetting

Chrome 44 以上版本

值

ResourceIdentifier

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

屬性

  • description

    字串 選用

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

  • id

    字串

    指定內容類型的資源 ID。

Scope

Chrome 44 以上版本

ContentSetting 的範圍。其中一個 regular：適用於一般設定檔 (如未在別處覆寫，無痕模式設定檔就會沿用)，incognito\_session\_only：只有在無痕模式工作階段期間才能設定的無痕模式設定檔，並在無痕工作階段結束時刪除 (覆寫一般設定)。

列舉

屬性

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() 時，主要模式必須是 。

類型

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 以上版本

是否允許網站存取攝影機。其中一個 allow：允許網站存取攝影機。 block：不允許網站存取攝影機。 ask：在網站要求存取攝影機時詢問。 預設值為 ask。主要網址是指要求相機存取權的文件網址。系統不會使用次要網址。注意：如果兩種模式都是「」，則「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。主要網址是指要求麥克風存取權的文件網址。系統不會使用次要網址。注意：如果兩種模式都是「」，則「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>