chrome.types

說明

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 以上版本

      只有資訊清單 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 以上版本

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

  • set

    void

    Promise

    設定設定的值。

    set 函式如下所示： 

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

    • 詳細資料

      物件

      要變更的設定。

      • 範圍

        ChromeSettingScope 選用

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

      • 值

        T

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

    • callback

      函式 選用

      callback 參數如下： 

      () => void

    • returns

      Promise<void>

      Chrome 96 以上版本

      只有資訊清單 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"