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

    事件<functionvoidvoid>

    在設定變更後觸發。

    onChange.addListener 函式如下所示：

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

    • 回呼

      功能

      callback 參數如下所示： 

      (details: object)=>void

      • 詳細資料

        物件

        • incognitoSpecific

          布林值 (選用)

          已變更的值是否針對特定無痕模式工作階段設定。 使用者只有在無痕模式中啟用擴充功能時，系統才會顯示這個屬性。

        • levelOfControl

          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

          LevelOfControl

          設定的控制層級。

        • 值

          T

          設定的值。

    • returns

      Promise<object>

      Chrome 96 以上版本

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

  • set

    void

    Promise

    設定設定值。

    set 函式如下所示：

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

    • 詳細資料

      物件

      要變更的設定。

      • 範圍

        ChromeSettingScope 選用

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

      • 值

        T

        設定的值。 請注意，每項設定都有特定的值類型，系統會隨設定一同提供該類型的值。擴充功能不得設定不同類型的值。

    • 回呼

      函式選用

      callback 參數如下所示： 

      ()=>void

    • returns

      Promise<void>

      Chrome 96 以上版本

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

ChromeSettingScope

Chrome 44 以上版本

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

  • regular：一般設定檔的設定 (如未在其他地方覆寫，無痕模式設定檔就會沿用此設定)：
  • regular\_only：僅限一般設定檔的設定 (不會由無痕模式設定檔沿用)
  • incognito\_persistent：無痕模式設定檔在瀏覽器重新啟動後仍然有效的設定 (覆寫一般偏好設定)。
  • incognito\_session\_only：僅限在無痕模式工作階段中設定的無痕模式設定檔，並在無痕工作階段結束時刪除 (覆寫一般偏好設定和 無痕/永久性偏好設定)。

列舉

"regular_only"

LevelOfControl

Chrome 44 以上版本

下列其中一項權限：

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

列舉

"not_controllable"

"controllable_by_this_extension"