chrome.types

refresh date: 2026-09-25 robots: noindex

說明

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 會管理不同層級的設定。以下清單說明可能會影響有效設定的圖層，並依優先順序遞增排列。

  1. 作業系統提供的系統設定
  2. 指令列參數
  3. 擴充功能提供的設定
  4. 政策

如清單所示，政策可能會覆寫您透過擴充功能指定的任何變更。您可以使用 get() 函式，判斷擴充功能是否能夠提供設定，或這項設定是否會遭到覆寫。

如上所述，Chrome 允許為一般視窗和無痕視窗使用不同設定。以下範例說明這項行為。假設沒有任何政策會覆寫設定，且擴充功能可以設定一般視窗 (R) 和無痕視窗 (I) 的設定。

  • 如果只設定 (R)，這些設定會同時套用至一般和無痕視窗。
  • 如果只設定 (I)，這些設定只會對無痕視窗生效。一般視窗 會使用下層 (指令列選項和系統設定) 決定的設定。
  • 如果同時設定 (R) 和 (I)，系統會將對應設定用於一般和無痕視窗。

如果有兩個以上的擴充功能想將同一項設定設為不同值，系統會優先採用最近安裝的擴充功能。如果最近安裝的擴充功能只設定 (I)，一般視窗的設定可由先前安裝的擴充功能定義。

設定的「有效」值是考量優先順序規則後得出的結果。Chrome 會使用這項服務。

類型

ChromeSetting

可存取 Chrome 瀏覽器設定的介面。如需範例，請參閱 accessibilityFeatures。

屬性

  • onChange

    Event<functionvoidvoid>

    設定變更後觸發。

    onChange.addListener 函式如下所示： 

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

    • callback

      函式

      callback 參數如下： 

      (details: object) => void

      • 詳細資料

        物件

        • incognitoSpecific

          布林值 選填

          變更的值是否專屬於無痕工作階段。如果使用者已在無痕模式中啟用擴充功能，系統只會顯示這項屬性。

        • levelOfControl

          LevelOfControl

          設定的控管程度。

        • 值

          T

          變更後的設定值。

  • 關閉

    void

    Promise

    清除設定，並還原任何預設值。

    clear 函式如下所示： 

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

    • 詳細資料

      物件

      要清除的設定。

    • callback

      函式 選填

      callback 參數如下： 

      () => void

    • returns

      Promise<void>

      Chrome 96 以上版本

      清除作業完成時呼叫。

      只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

  • get

    void

    Promise

    取得設定的值。

    get 函式如下所示： 

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

    • 詳細資料

      物件

      要考慮的設定。

      • 無痕模式

        布林值 選填

        是否要傳回適用於無痕工作階段的值 (預設為 false)。

    • callback

      函式 選填

      callback 參數如下： 

      (details: object) => void

      • 詳細資料

        物件

        目前有效值的詳細資料。

        • incognitoSpecific

          布林值 選填

          有效值是否專屬於無痕工作階段。 只有在 get() 的 details 參數中，incognito 屬性為 true 時，才會出現這個屬性。

        • levelOfControl

          LevelOfControl

          設定的控管程度。

        • 值

          T

          設定的值。

    • returns

      Promise<object>

      Chrome 96 以上版本

      只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

  • set

    void

    Promise

    設定設定的值。

    set 函式如下所示： 

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

    • 詳細資料

      物件

      要變更的設定。

      • 範圍

        ChromeSettingScope 選用

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

      • 值

        T

        設定的值。 請注意，每項設定都有特定值類型，這會與設定一併說明。擴充功能不得設定不同類型的值。

    • callback

      函式 選填

      callback 參數如下： 

      () => void

    • returns

      Promise<void>

      Chrome 96 以上版本

      設定作業完成時呼叫。

      只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

ChromeSettingScope

Chrome 44 以上版本

ChromeSetting 的範圍。下列其中一項權限：

  • regular：一般設定檔的設定 (如果未在其他位置覆寫，無痕設定檔會沿用此設定)，
  • regular\_only：僅適用於一般設定檔 (無痕設定檔不會沿用)，
  • incognito\_persistent：無痕模式設定，在瀏覽器重新啟動後仍會保留 (會覆寫一般偏好設定)，
  • incognito\_session\_only：無痕模式設定，只能在無痕模式工作階段期間設定，並在無痕模式工作階段結束時刪除 (會覆寫一般和 incognito_persistent 偏好設定)。

列舉

「regular」

「regular_only」

「incognito_persistent」

「incognito_session_only」

LevelOfControl

Chrome 44 以上版本

下列其中一項權限：

  • not\_controllable：無法由任何擴充功能控制
  • controlled\_by\_other\_extensions：由優先順序較高的擴充功能控管
  • controllable\_by\_this\_extension：可由這個擴充功能控管
  • controlled\_by\_this\_extension：由這項擴充功能控管

列舉

「not_controllable」

"controlled_by_other_extensions"

"controllable_by_this_extension"

"controlled_by_this_extension"