AMRemoteSettings 概述¶

AMRemoteSettings 是一个单例，负责从名为 "main/addons-manager-settings" 的 RemoteSettings 集合中获取数据，以远程控制一组与附加组件相关的首选项（硬编码在给定 Firefox 版本的 AMRemoteSettings 定义部分）。

AMRemoteSettings 将在 RemoteSettings "sync" 事件触发时处理集合数据，并在浏览器后期启动时处理集合中已存在的一些本地存储的数据（因此，如果手动更改 pref 值，则它将在下次浏览器启动或下次 "sync" 事件再次触发时，重置为 RemoteSettings 集合数据中存储的值）。

警告

AMRemoteSettings 单例在处理 RemoteSettings 集合数据时设置的任何 about:config 首选项 **不会自动清除**（例如，如果在未来的 Firefox 版本中 AMRemoteSettings 不再处理特定设置，或者如果 RemoteSettings 服务端从集合中删除了 RemoteSettings 条目）。

在实践中，这使得此功能成为一个不错的选择，当远程控制的 about:config 首选项与以下情况相关时：

正在弃用的 Firefox 附加组件功能，并在未来的 Firefox 版本中完全移除
或从 "main/addons-manager-settings" 集合中永远不会移除的受控设置。

一般来说，在更改 "main/addons-manager-settings" 集合中的受控设置之前，建议：

确保首先在 mozilla-central 中更改了相关 about:config 首选项的默认值，并让它搭乘发布列车并在发布版上运行一段时间；
只有在那之后，才考虑更改由 "main/addons-manager-settings" 集合控制的值，以便在设置了先前默认值的旧版 Firefox 版本中设置相同的值。

AMRemoteSettings 单例查询 RemoteSettings 并处理从 "main/addons-manager-settings" 集合中获取的所有条目，除了可能根据 "filter_expression" 属性由 RemoteSettings 过滤掉的条目（请参阅 https://remote-settings.readthedocs.io/en/latest/target-filters.html#how）。

在 "main/addons-manager-settings" 集合中创建的每个条目都应与下面 JSON 架构部分中描述的 JSON 架构匹配。

对于在集合中找到的每个条目，只有明确包含在 AMRemoteSettings.RS_ENTRIES_MAP 对象中的属性才会被处理（例如，新版 Firefox 可能引入了旧版 Firefox 只是忽略的新属性）。

AMRemoteSettings.RS_ENTRIES_MAP 的每个属性：
- 表示一组设置（例如，名为 "installTriggerDeprecation" 的属性负责控制与 InstallTrigger 弃用相关的 about:config 首选项）。
- 设置为字符串数组，其中列出了实际上可以由相关设置组控制的 about:config 首选项名称（例如，"installTriggerDeprecation" 只能控制两个首选项，"extensions.InstallTrigger.enabled" 和 "extensions.InstallTriggerImpl.enabled"，它们控制着 InstallTrigger 和 InstallTrigger 方法的可用性）。

警告

未在 AMRemoteSettings.RS_ENTRIES_MAP 配置中明确列出的任何其他 about:config 首选项名称都将被忽略，即使新版本的集合的 JSON 架构允许（这是预期的行为，可以防止在旧版 Firefox 版本上引入意外的行为，这些版本可能不期望在新版本 Firefox 中引入的新设置组）。

任何具有意外值类型的 about:config 首选项也将被忽略（查看 AMRemoteSettings.processEntries 以确认哪些首选项值类型已预期并相应处理）。

AMRemoteSettings - 受控设置组¶

installTriggerDeprecation¶

控制 InstallTrigger 弃用的一组设置（Bug 1754441）

extensions.InstallTrigger.enabled (布尔值)，控制 InstallTrigger 全局变量的可用性
- 将其设置为 false 将完全隐藏它
  
  注意
  
  关闭此功能可能会影响网站上的 UA 检测，这些网站使用它来检测 Firefox。在通过 "addons-manager-settings" RemoteSettings 集合在 Nightly 或所有 Firefox >= 100 版本中默认将其设置为 false 之前，应咨询 WebCompat 团队。
extensions.InstallTriggerImpl.enabled (布尔值)：控制 InstallTrigger 方法的可用性
- 将其设置为 false 将隐藏所有 InstallTrigger 实现，阻止使用它来触发附加组件安装流程，而 InstallTrigger 全局变量仍将存在但设置为 null。

quarantinedDomains¶

控制隔离域列表的一组设置（Bug 1832791）

extensions.quarantinedDomains.list (字符串)，控制要隔离的域列表

注意

在对隔离域列表进行更改之前，应咨询 WebExtensions 和附加组件操作团队。

如何定义新的远程控制设置¶

注意

当 RemoteSettings 服务端使用的设置发生更改时，请更新此文档页面中的 AMRemoteSettings - JSON 架构和 UI 架构，并在 AMRemoteSettings - 受控设置组部分记录新的受控设置。

确认此页面中包含的 AMRemoteSettings - JSON 架构和 UI 架构与 RemoteSettings 服务端实际使用的架构保持同步，并将其作为更新的起点，以包含新的远程控制设置类型。
- 为要在 definitions 和 properties 对象中使用的设置组选择一个新的唯一字符串（任何尚未在现有 JSON 架构 definitions 中使用的字符串），可以选择一个有助于理解条目目的的名称。
- 在 definitions 属性中为新的设置组添加一个新的 JSON 架构。
  - 新定义中包含的每个属性都应以被控制的 about:config pref 的名称命名，它们的类型应与 pref 预期的类型匹配（例如，布尔值首选项的 "boolean"）。
  - 确保为定义和每个受控首选项添加一个 description 属性，该属性应描述设置组控制的内容以及允许的值的预期行为。
在 "AMRemoteSettings.RS_ENTRIES_MAP" 中添加一个新条目，使用选择的 "id" 作为其键，以及 about:config 首选项名称的数组作为其值。
如果受控首选项的值类型尚未得到支持，则必须更新 AMRemoteSettings.processEntries 方法以处理新的值类型（否则首选项值将被忽略）。
添加一个新的测试来涵盖对新远程控制设置的预期行为，以下 RemoteSettings 文档页面提供了一些有用的提示：* https://firefox-source-docs.mozilla.ac.cn/services/settings/index.html#unit-tests
有关管理 "main/addons-manager-settings" 集合的 JSON 架构以及如何在 Firefox 实例中交互式测试它的更多详细信息，请参阅 RemoteSettings 文档：* https://remote-settings.readthedocs.io/en/latest/getting-started.html * https://firefox-source-docs.mozilla.ac.cn/services/settings/index.html#create-new-remote-settings * https://firefox-source-docs.mozilla.ac.cn/services/settings/index.html#remote-settings-dev-tools

AMRemoteSettings - JSON 架构¶

"addons-manager-settings" 集合的条目部分使用如下结构的 JSON 架构进行验证。

必需的 "id" 属性：* 默认值为 “AddonManagerSettings”（强制集合中只有一个条目作为首选用例）* **除非有创建针对或排除特定 Firefox 版本的单独集合条目的特定需求，否则不应更改。** * 当更改并在此集合中创建多个条目时，建议：
- 将 id 设置为简短的字符串值，以便更容易理解集合中附加条目的目的（例如，针对 Firefox 98 和 99 创建的条目的 AddonManagerSettings-fx98-99）。
- 确保每个目标 Firefox 版本范围内只应用一个，或者至少每个条目控制不同的设置组。
每个受支持的受控设置组都由其自己的属性描述（例如，"installTriggerDeprecation"）。
- 每个设置组的 JSON 架构都在 "definitions" 属性的条目中定义。
- 架构中定义的每个组的定义应定义为一个 "oneOf" 数组，其中包含一个 "type": "null" 和 "default"` set to ``null 的条目，以便在新的记录中默认省略设置组。
- 除了 "type": "null" 模式之外，每个设置组都应该在 "oneOf" 数组中包含第二个条目，该条目为 "type": "object"，以及在 "properties" 中列出的该组对应的受控 about:config 偏好设置部分。

{
  "type": "object",
  "required": ["id"],
  "properties": {
    "id": {
      "type": "string",
      "default": "AddonManagerSettings",
      "description": "The default id should NOT be changed, unless there is a specific need to create separate collection entries which target or exclude specific Firefox versions."
    },
    "filter_expression": {
      "type": "string",
      "optional": true,
      "description": "This is NOT directly used by AMRemoteSettings, but has special functionality in Remote Settings.\nSee https://remote-settings.readthedocs.io/en/latest/target-filters.html#how"
    },
    "quarantinedDomains": {
      "$ref": "#/definitions/quarantinedDomains",
      "optional": true
    },
    "installTriggerDeprecation": {
      "$ref": "#/definitions/installTriggerDeprecation",
      "optional": true
    }
  },
  "definitions": {
    "quarantinedDomains": {
      "oneOf": [
        {
          "type": "null",
          "title": "Omit quarantinedDomains settings"
        },
        {
          "type": "object",
          "title": "Include quarantinedDomains settings",
          "required": ["extensions.quarantinedDomains.list"],
          "properties": {
            "extensions.quarantinedDomains.list": {
              "type": "string",
              "default": "",
              "maxLength": 1048576,
              "description": "Set of domains to be quarantined separated by a comma (e.g. 'domain1.org,domain2.com'). NOTE: this pref value should be set to a ASCII encoded string and its size smaller than 1MB"
            }
          },
          "additionalProperties": false
        }
      ],
      "default": null,
      "description": "These settings provide a set of domain names to be quarantined (restricted by default to unverified extensions, which only the app or the user may grant back). IMPORTANT: The add-ons team should be consulted before introducing any new entry of this type."
    },
    "installTriggerDeprecation": {
      "oneOf": [
        {
          "type": "null",
          "title": "Omit installTriggerDeprecation settings"
        },
        {
          "type": "object",
          "title": "Include installTriggerDeprecation settings",
          "required": [
            "extensions.InstallTrigger.enabled",
            "extensions.InstallTriggerImpl.enabled"
          ],
          "properties": {
            "extensions.InstallTrigger.enabled": {
              "type": "boolean",
              "default": true,
              "optional": true,
              "description": "Show/Hide the InstallTrigger global completely (both the global and its methods will not be accessible anymore). IMPORTANT: The webcompat team should be consulted before turning this to false, because it may also potentially impact UA detection for some websites."
            },
            "extensions.InstallTriggerImpl.enabled": {
              "type": "boolean",
              "default": false,
              "optional": true,
              "description": "Show/Hide the InstallTrigger methods. The InstallTrigger global will remain visible but set to null."
            }
          },
          "additionalProperties": false
        }
      ],
      "default": null,
      "description": "These settings control the visibility of the InstallTrigger global and its methods."
    }
  }
}

UI 模式¶

除了 JSON 模式之外，还有一个名为 "UI schema" 的单独 json 文件与 "addons-manager-settings" 集合相关联，它可以用来根据 JSONSchema 数据自定义自动生成的表单。

注意

仅当扩展此模式有助于使 RemoteSettings 集合更易于管理和减少错误时，才需要扩展它。

{
  "installTriggerDeprecation": {
    "extensions.InstallTrigger.enabled": {
      "ui:widget": "radio"
    },
    "extensions.InstallTriggerImpl.enabled": {
      "ui:widget": "radio"
    }
  }
}