說明
你可以使用 chrome.contentSettings
API 變更設定,控管網站能否使用 Cookie、JavaScript 和外掛程式等功能。一般來說,內容設定可讓您自訂個別網站 (而非全球) 的行為。
權限
contentSettings
資訊清單
您必須在擴充功能的資訊清單中宣告「contentSettings」權限,才能使用這個 API。舉例來說:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
內容設定模式
您可以使用模式,指定每項內容設定會影響的網站。舉例來說,https://*.youtube.com/*
會指定 youtube.com 及其所有子網域。內容設定模式的語法與比對模式相同,但有以下差異:
- 如果是
http
、https
和ftp
網址,路徑必須是萬用字元 (/*
)。如果是file
網址,必須完整指定路徑,且「不得」包含萬用字元。 - 相較於比對模式,內容設定模式可以指定通訊埠編號。如果指定通訊埠編號,模式只會比對具有該通訊埠的網站。如未指定通訊埠編號,則模式會比對所有通訊埠。
模式優先順序
如果特定網站適用多項內容設定規則,系統會優先採用模式較為明確的規則。
舉例來說,下列模式會按優先順序排序:
https://www.example.com/*
https://*.example.com/*
(比對 example.com 和所有子網域)<all_urls>
(比對所有網址)
有三種萬用字元會影響特定模式的運作程度:
- 通訊埠中的萬用字元 (例如
https://www.example.com:*/*
) - 配置中的萬用字元 (例如
*://www.example.com:123/*
) - 主機名稱中的萬用字元 (例如
https://*.example.com:123/*
)
如果某一模式在某部分中比另一個模式更具體,但另一個部分則較不明確,系統會按照下列順序檢查不同部分:主機名稱、配置、通訊埠。舉例來說,下列模式會按優先順序排序:
https://www.example.com:*/*
指定主機名稱和配置。*:/www.example.com:123/*
不會太高,因為雖然可以指定主機名稱,但也不會指定通訊協定。https://*.example.com:123/*
較低,因為雖然可以指定通訊埠和配置,但主機名稱包含萬用字元。
主要與次要模式
根據內容類型決定要套用的內容設定時,系統會考慮的網址。
舉例來說,contentSettings.notifications
的設定是以網址列顯示的網址為基礎。這個網址稱為「主要」網址。
部分內容類型可能會將額外網址納入考量。舉例來說,是否允許網站設定 contentSettings.cookies
,取決於 HTTP 要求的網址 (在本例中為主要網址),以及網址列中顯示的網址 (稱為「次要」網址)。
如果多項規則同時具有主要和次要模式,系統會優先採用主要模式更具體的規則。如果有多個規則具有相同的主要模式,系統會優先採用次要模式更具體的規則。舉例來說,以下主要/次要模式組合清單會依優先順序排序:
優先順序 | 主要模式 | 次要模式 |
---|---|---|
1 | https://www.moose.com/* , | https://www.wombat.com/* |
2 | https://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
列舉
CameraContentSetting
列舉
ClipboardContentSetting
列舉
ContentSetting
屬性
-
關閉
void
Promise清除這項擴充功能設定的所有內容設定規則。
clear
函式如下所示:(details: object, callback?: function) => {...}
-
詳細資料
物件
-
範圍
範圍 選用
清除設定的位置 (預設值:一般)。
-
-
回呼
函式選用
callback
參數如下所示:() => void
-
returns
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
-
-
get
void
Promise取得一組網址目前的內容設定。
get
函式如下所示:(details: object, callback?: function) => {...}
-
詳細資料
物件
-
無痕模式
布林值 (選用)
是否要檢查無痕模式工作階段的內容設定。(預設為 false)
-
primaryUrl
字串
應擷取內容設定的主要網址。請注意,主要網址的含義取決於內容類型。
-
resourceIdentifier
應擷取設定的內容類型更明確的 ID。
-
secondaryUrl
字串 選用
應擷取內容設定的次要網址。預設為主要網址。請注意,次要網址的含義取決於內容類型,且並非所有內容類型都會使用次要網址。
-
-
回呼
函式選用
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
設定
T
內容設定。如要瞭解可能的值,請參閱個別 ContentSetting 物件說明。
-
-
-
returns
Promise<object>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
-
-
getResourceIdentifiers
void
PromisegetResourceIdentifiers
函式如下所示:(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) => {...}
-
returns
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
-
CookiesContentSetting
列舉
"session_only"
FullscreenContentSetting
值
ImagesContentSetting
列舉
JavascriptContentSetting
列舉
LocationContentSetting
列舉
MicrophoneContentSetting
列舉
MouselockContentSetting
值
MultipleAutomaticDownloadsContentSetting
列舉
NotificationsContentSetting
列舉
PluginsContentSetting
值
PopupsContentSetting
列舉
PpapiBrokerContentSetting
值
ResourceIdentifier
唯一使用資源 ID 的內容類型為 contentSettings.plugins
。詳情請參閱「資源 ID」。
屬性
-
description
字串 選用
使用者可理解的資源說明。
-
id
字串
指定內容類型的資源 ID。
Scope
ContentSetting 的範圍。其中一個 regular
:適用於一般設定檔 (如未在別處覆寫,無痕模式設定檔就會沿用),incognito\_session\_only
:只有在無痕模式工作階段期間才能設定的無痕模式設定檔,並在無痕工作階段結束時刪除 (覆寫一般設定)。
列舉
屬性
automaticDownloads
是否允許網站自動下載多個檔案。其中一個 allow
:允許網站自動下載多個檔案。
block
:不允許網站自動下載多個檔案。
ask
:網站必須先詢問要自動下載檔案,再自動下載第一個檔案。
預設值為 ask
。主要網址是頂層頁框的網址。系統不會使用次要網址。
autoVerify
可指定是否允許網站使用 Private State Tokens API。allow
:允許網站使用 Private State Tokens API,block
:禁止網站使用 Private State Tokens API。預設值為 allow
。主要網址是頂層頁框的網址。系統不會使用次要網址。注意:呼叫 set()
時,主要模式必須是 。
camera
是否允許網站存取攝影機。其中一個 allow
:允許網站存取攝影機。
block
:不允許網站存取攝影機。
ask
:在網站要求存取攝影機時詢問。
預設值為 ask
。主要網址是指要求相機存取權的文件網址。系統不會使用次要網址。注意:如果兩種模式都是「」,則「allow」設定無效。
clipboard
可指定是否允許網站透過 Async Clipboard API 的進階功能存取剪貼簿。「進階」功能除了在使用者手勢後編寫內建格式之外,還具備閱讀功能、撰寫自訂格式的能力,以及無需使用者手勢即可撰寫郵件的功能。其中一個 allow
:允許網站使用進階剪貼簿功能。block
:不允許網站使用進階剪貼簿功能;ask
:在網站要使用進階剪貼簿功能時詢問。預設值為 ask
。主要網址為要求剪貼簿存取權的文件網址。系統不會使用次要網址。
cookies
是否允許網站設定 Cookie 和其他本機資料。以下其中一個 allow
:接受 Cookie、block
:封鎖 Cookie;session\_only
:僅接受目前工作階段的 Cookie。預設值為 allow
。主要網址為代表 Cookie 來源的網址。次要網址是頂層頁框的網址。
fullscreen
已淘汰。已失效。系統已自動授予所有網站的全螢幕權限。值一律為 allow
。
images
是否顯示圖片。其中一個 allow
:顯示圖片。block
:不顯示圖片。預設值為 allow
。主要網址是頂層頁框的網址。次要網址為圖片的網址。
javascript
是否執行 JavaScript。其中一個 allow
:執行 JavaScript。block
:請勿執行 JavaScript。預設值為 allow
。主要網址是頂層頁框的網址。系統不會使用次要網址。
location
是否允許使用地理位置。其中一個 allow
:允許網站追蹤你的實際位置。
block
:不允許網站追蹤你的實際位置。
ask
:必須先詢問是否允許網站追蹤你的實際位置。
預設值為 ask
。主要網址是指要求位置資料的文件網址。次要網址是頂層頁框的網址 (不一定與要求網址不同)。
microphone
是否允許網站存取麥克風。其中一個 allow
:允許網站存取麥克風。
block
:不允許網站存取麥克風。
ask
:在網站要求存取麥克風時詢問。
預設值為 ask
。主要網址是指要求麥克風存取權的文件網址。系統不會使用次要網址。注意:如果兩種模式都是「」,則「allow」設定無效。
mouselock
已淘汰。已失效。系統現在已自動授予所有網站的滑鼠鎖定權限。值一律為 allow
。
notifications
是否允許網站顯示桌面通知。其中一個 allow
:允許網站顯示桌面通知。
block
:不允許網站顯示桌面通知,
ask
:在網站要顯示桌面通知時詢問。
預設值為 ask
。主要網址是要顯示通知的文件網址。系統不會使用次要網址。
plugins
已淘汰。Chrome 第 88 版已移除 Flash 支援,這項權限已失效。值一律為 block
。系統會忽略對 set()
和 clear()
的呼叫。
popups
是否允許網站顯示彈出式視窗。其中一個 allow
:允許網站顯示彈出式視窗
block
:不允許網站顯示彈出式視窗。
預設值為 block
。主要網址是頂層頁框的網址。系統不會使用次要網址。
unsandboxedPlugins
已淘汰。先前控管是否允許網站在無沙箱防護的情況下執行外掛程式;不過,在 Chrome 第 88 版中移除 Flash 代理程式程序後,這項權限已失效。值一律為 block
。系統會忽略對 set()
和 clear()
的呼叫。