說明
chrome.types
API 包含 Chrome 的類型宣告。
Chrome 設定
ChromeSetting
類型提供一組常用函式 (get()
、set()
和 clear()
),以及用於 Chrome 瀏覽器的設定的事件發布者 (onChange
)。Proxy 設定範例說明瞭這些函式的使用方式。
範圍和生命週期
Chrome 會區分三種瀏覽器設定範圍:
regular
- 在
regular
範圍中設定的設定會套用至一般瀏覽器視窗,且如果未覆寫,則會由無痕式視窗沿用。這些設定會儲存至磁碟並保持不變,直到控管擴充功能清除設定,或規範擴充功能已停用或解除安裝為止。 incognito_persistent
- 在「
incognito_persistent
」範圍中設定的設定只會套用至無痕式視窗。在這些情況下,這些設定會覆寫regular
設定。這些設定會儲存至磁碟並保持不變,直到控管的擴充功能清除設定,或是規範的擴充功能已停用或解除安裝為止。 incognito_session_only
- 在「
incognito_session_only
」範圍中設定的設定只會套用至無痕式視窗。在這些情況下,這些設定會覆寫regular
和incognito_persistent
設定。這些設定不會儲存至磁碟,而且會在最後一個無痕式視窗關閉後清除。您只能在開啟至少一個無痕式視窗時設定限制。
優先順序
Chrome 會管理不同圖層的設定。以下清單以優先順序遞增,可能影響有效設定的圖層。
- 作業系統提供的系統設定
- 指令列參數
- 擴充功能提供的設定
- 政策
如清單所示,政策可能會覆寫你透過擴充功能指定的任何變更。您可以使用 get()
函式判斷擴充功能是否能提供設定,或是否要覆寫這項設定。
如先前所述,Chrome 允許對一般視窗和無痕式視窗使用不同的設定。下例說明行為。假設沒有任何政策覆寫這項設定,且擴充功能可以調整一般視窗 (R) 和無痕視窗 (I) 的設定。
- 如果只設定了 (R),這些設定對一般視窗和無痕式視窗有效。
- 如果只設定了 (I) 參數,這些設定僅適用於無痕式視窗。一般視窗會採用較低層 (指令列選項和系統設定) 決定的設定。
- 如果同時設定 (R) 和 (I),則一般視窗和無痕式視窗都會使用各自的設定。
如有兩個以上的擴充功能要將相同設定設為不同的值,則由最近安裝的擴充功能優先於其他擴充功能。如果最近安裝的擴充功能只能設定 (I),之前安裝的擴充功能就可以定義一般視窗的設定。
設定的「有效」值是指因考量優先順序規則而產生的值。供 Chrome 使用。
類型
ChromeSetting
可讓使用者存取 Chrome 瀏覽器設定的介面。如需範例,請參閱 accessibilityFeatures
。
屬性
-
onChange
事件<functionvoidvoid>
在設定變更後觸發。
onChange.addListener
函式如下所示:(callback: function) => {...}
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
incognitoSpecific
布林值 (選用)
已變更的值是否針對特定無痕模式工作階段設定。 使用者只有在無痕模式中啟用擴充功能時,系統才會顯示這個屬性。
-
levelOfControl
設定的控制層級。
-
值
T
變更後的設定值。
-
-
-
-
關閉
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)。
-
-
回呼
函式選用
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
目前有效值的詳細資料。
-
incognitoSpecific
布林值 (選用)
有效值是否專屬於無痕模式工作階段。「只有」在
get()
的details
參數中的incognito
屬性為 true 時,才會顯示這項屬性。 -
levelOfControl
設定的控制層級。
-
值
T
設定的值。
-
-
-
returns
Promise<object>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
-
-
set
void
Promise設定設定值。
set
函式如下所示:(details: object, callback?: function) => {...}
-
詳細資料
物件
要變更的設定。
-
範圍
設置設定的位置 (預設值:一般)。
-
值
T
設定的值。 請注意,每項設定都有特定的值類型,系統會隨設定一同提供該類型的值。擴充功能不得設定不同類型的值。
-
-
回呼
函式選用
callback
參數如下所示:() => void
-
returns
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
-
ChromeSettingScope
ChromeSetting 的範圍。下列其中一項權限:
regular
:一般設定檔的設定 (如未在其他地方覆寫,無痕模式設定檔就會沿用此設定):regular\_only
:僅限一般設定檔的設定 (不會由無痕模式設定檔沿用)incognito\_persistent
:無痕模式設定檔在瀏覽器重新啟動後仍然有效的設定 (覆寫一般偏好設定)。incognito\_session\_only
:僅限在無痕模式工作階段中設定的無痕模式設定檔,並在無痕工作階段結束時刪除 (覆寫一般偏好設定和 無痕/永久性偏好設定)。
列舉
"regular_only"
LevelOfControl
下列其中一項權限:
not\_controllable
:無法由任何擴充功能控管controlled\_by\_other\_extensions
:由優先順序較高的擴充功能控制controllable\_by\_this\_extension
:可由這個擴充功能控管controlled\_by\_this\_extension
:由這個擴充功能控制
列舉
"not_controllable"
"controllable_by_this_extension"