UITour 库 API¶

这是 UITour-lib.js 库提供的 Web API，供具有相应权限的 Web 内容使用。

class Mozilla.UITour()¶

该库提供了一个基于事件的 Web API，用于与桌面浏览器 Chrome 通信。它可以用于打开菜单面板和突出显示工具栏中按钮位置等任务。

出于安全/隐私原因，Mozilla.UITour 仅适用于允许的安全来源列表。允许来源的列表可以在 https://searchfox.org/mozilla-central/source/browser/app/permissions 中找到。

static Mozilla.UITour.ConfigurationName()¶

有效值

appinfo
canReset
availableTargets
search
selectedSearchEngine 已弃用，请使用“search”
sync 已弃用，请使用“fxa”
fxa
fxaConnections

static Mozilla.UITour.HighlightEffect()¶

有效值

random
wobble
zoom
color

在浏览器控制台中使用以下方法生成

[...UITour.highlightEffects].join("\n* - ")

另请参阅

Mozilla.UITour.showHighlight

static Mozilla.UITour.MenuName()¶

有效值

appMenu
bookmarks
pocket

另请参阅

Mozilla.UITour.showMenu
Mozilla.UITour.hideMenu
Mozilla.UITour.openSearchPanel

static Mozilla.UITour.Target()¶

有效值

accountStatus
addons
appMenu
backForward
bookmarks
forget
help
home
logins
pageAction-bookmark
pocket
privateWindow
quit
readerMode-urlBar
search
searchIcon
selectedTabIcon
urlbar

在浏览器控制台中使用以下方法生成

[...UITour.targets.keys()].join("\n* - ")

另请参阅

Mozilla.UITour.getConfiguration
Mozilla.UITour.showHighlight
Mozilla.UITour.showInfo

static Mozilla.UITour.addNavBarWidget(name, callback)¶

将指定的可自定义小部件添加到导航工具栏。

参数：

name (Mozilla.UITour.Target) – 可自定义小部件的标识符。
callback (function) – 在图标成功添加到工具栏后，不带任何参数调用。如果未成功，则不调用。

示例

Mozilla.UITour.addNavBarWidget('forget', function () {
  console.log('forget button added to toolbar');
});

static Mozilla.UITour.closeTab()¶: 当前窗口中的最后一个标签页永远不会关闭，在这种情况下，此调用将不起作用。调用代码预计在短时间后采取操作以处理这种情况，例如显示告别消息或重新启动游览的按钮。

static Mozilla.UITour.forceShowReaderIcon()¶: 如果您想在其上定位注释（面板/突出显示），但游览页面没有太多文本内容，这将很有用。

static Mozilla.UITour.getConfiguration(configName, callback)¶

检索有关应用程序/配置文件的一些信息。

参数：

configName (Mozilla.UITour.ConfigurationName) – 要检索的配置的名称
callback (function) – 使用一个参数调用，该参数包含配置的值。

static Mozilla.UITour.getTreatmentTag(name, callback)¶

检索一组 FHR 处理标签的值。

参数：

name (string) – 要检索的标签名称
callback (function) – 在检索到数据后调用

示例

Mozilla.UITour.getTreatmentTag('srch-chg-action', function(value) {
  console.log(value);
});

另请参阅

Mozilla.UITour.setTreatmentTag

static Mozilla.UITour.hideHighlight()¶

隐藏任何可见的 UI 突出显示。

另请参阅

Mozilla.UITour.showHighlight

static Mozilla.UITour.hideInfo()¶

隐藏任何可见的信息面板。

另请参阅

Mozilla.UITour.showInfo

static Mozilla.UITour.hideMenu(name)¶

关闭指定的应用程序菜单。

参数：

name (Mozilla.UITour.MenuName) – 菜单名称

另请参阅

Mozilla.UITour.showMenu

static Mozilla.UITour.observe(listener, callback)¶

每个游览标签页只能有一个观察者，因此第二次调用此方法将替换任何先前的 listener。要删除观察者，请使用 null 作为第一个参数调用此方法。

参数：

listener (function) – 当任何 UITour 通知发生时调用。
callback (function) – 当浏览器确认观察者时调用。

static Mozilla.UITour.openPreferences(pane)¶

参数：

pane (string) – 要打开/切换到的首选项窗格。有效值与 about:preferences 上的片段匹配，并且可能发生更改，例如：对于首选项：- general - applications - sync - privacy - advanced 要打开发送遥测、健康报告、崩溃报告的选项，即首选项中的隐私窗格>报告。请调用 Mozilla.UITour.openPreferences(“privacy-reports”)。UITour 会自动进行路由映射。

static Mozilla.UITour.openSearchPanel(callback)¶

这应该通过 showMenu(“search”, …) 实现。

参数：

callback (function) – 在面板打开后调用。

static Mozilla.UITour.ping(callback)¶

确保浏览器已准备好将此文档作为游览处理。

参数：

callback (function) – 如果 UITour 对文档有效，则调用的回调函数。

static Mozilla.UITour.registerPageID(pageID)¶

注册一个在 Telemetry 中使用的标识符。pageID 必须是页面/游览的唯一字符串。

参数：

pageID (string) – 页面/游览的唯一标识符。

示例

Mozilla.UITour.registerPageID('firstrun-page-firefox-29');

static Mozilla.UITour.resetFirefox()¶

显示一个配置文件刷新/重置对话框，允许用户选择删除附加组件和自定义设置，以及在可能的情况下恢复浏览器默认设置。getConfiguration(‘canReset’) 应首先用于确定用户构建/配置文件是否可以进行刷新/重置。

另请参阅

Mozilla.UITour.Configuration.CanReset

static Mozilla.UITour.setConfiguration(configName, configValue)¶

设置某个值或执行某个操作。

有效的配置名称

defaultBrowser: 尝试将应用程序设置为默认网页浏览器。从 Fx40 开始

参数：

configName (string) – 要设置的配置名称（例如“defaultBrowser”）
configValue (string|number|boolean) – 当前未使用

示例

Mozilla.UITour.setConfiguration('defaultBrowser');

static Mozilla.UITour.setDefaultSearchEngine(identifier)¶

将指定的搜索引擎设置为用户设置的默认搜索引擎。

参见 https://searchfox.org/mozilla-release/source/browser/locales/search/list.json

参数：

identifier (string) – 引擎的标识符（例如“yahoo”）。

另请参阅

Mozilla.UITour.Configuration.Search

static Mozilla.UITour.setSearchTerm(term)¶

在搜索框中设置搜索词。

这应该通过 setConfiguration(“searchTerm”, …) 实现。

参数：

term (string) – 搜索字符串，例如“Firefox”

static Mozilla.UITour.setTreatmentTag(name, value)¶

将键值对设置为用于在 FHR 中记录的处理标签。

参数：

name (string) – 处理的标签名称
value (string) – 处理的标签值

示例

Mozilla.UITour.setTreatmentTag('srch-chg-action', 'Switch');

另请参阅

Mozilla.UITour.getTreatmentTag

static Mozilla.UITour.showConnectAnotherDevice(extraURLParams)¶

请求浏览器打开“连接其他设备” Firefox 账户页面。

参数：

extraURLParams (object) – 一个包含浏览器打开的 URL 的其他参数的对象，用于促销活动跟踪。对象的每个属性必须具有一个字符串名称，“flow_id”、“flow_begin_time”、“device_id”或以 utm_ 开头，并且仅包含字母数字字符、连字符或下划线。值可以是任何字符串，并将自动进行编码。有关流程指标，请参阅 https://mozilla.github.io/ecosystem-platform/docs/fxa-engineering/fxa-metrics#content-server 中的详细信息

示例

// Will open https://accounts.firefox.com/connect_another_device?entrypoint=uitour
Mozilla.UITour.showConnectAnotherDevice();

// Will open:
// https://accounts.firefox.com/connect_another_device?entrypoint=uitour&utm_foo=bar&utm_bar=baz
Mozilla.UITour.showConnectAnotherDevice({
  'utm_foo': 'bar',
  'utm_bar': 'baz'
});

static Mozilla.UITour.showFirefoxAccounts(extraURLParams, entrypoint, email)¶

请求浏览器打开 Firefox 账户页面。

参数：

extraURLParams (object) – 一个包含浏览器打开的 URL 的其他参数的对象，用于促销活动跟踪。对象的每个属性必须具有一个字符串名称，“flow_id”、“flow_begin_time”、“device_id”或以 utm_ 开头，并且仅包含字母数字字符、连字符或下划线。值可以是任何字符串，并将自动进行编码。有关流程指标，请参阅 https://mozilla.github.io/ecosystem-platform/docs/fxa-engineering/fxa-metrics#content-server 中的详细信息
entrypoint (string) – 包含入口点名称的字符串。
email (string) – 包含浏览器打开的 URL 的默认电子邮件帐户的字符串。

示例

// Will open https://accounts.firefox.com/signup?entrypoint=uitour
Mozilla.UITour.showFirefoxAccounts();

// Will open:
// https://accounts.firefox.com/signup?entrypoint=uitour&utm_foo=bar&utm_bar=baz
Mozilla.UITour.showFirefoxAccounts({
  'utm_foo': 'bar',
  'utm_bar': 'baz'
});

// Will open:
// https://accounts.firefox.com/?action=email&email=foo%40bar.com&entrypoint=uitour
Mozilla.UITour.showFirefoxAccounts(null, null, "[email protected]");

// Will open:
// https://accounts.firefox.com/signup?entrypoint=sample
Mozilla.UITour.showFirefoxAccounts(null, "sample");

// Will open:
// https://accounts.firefox.com/?action=email&email=foo%40bar.com&entrypoint=uitour&flow_id=c5b5ad7c4a94462afe4b9a7fbcca263dbd6c8409fb4539449c50c4a52544b2ed&flow_begin_time=1590680755812
Mozilla.UITour.showFirefoxAccounts({
  flow_id: 'c5b5ad7c4a94462afe4b9a7fbcca263dbd6c8409fb4539449c50c4a52544b2ed',
  flow_begin_time: 1590680755812,
  device_id: '7e450f3337d3479b8582ea1c9bb5ba6c'
}, "[email protected]");

static Mozilla.UITour.showHighlight(target, effect="none")¶

视觉突出显示 UI 小部件。

参数：

target (Mozilla.UITour.Target) – 要在其上显示突出显示的 UI 小部件的标识符。
effect (Mozilla.UITour.HighlightEffect) – 高亮显示时要使用的效果的名称。

示例

Mozilla.UITour.showHighlight('appMenu', 'wobble');

另请参阅

Mozilla.UITour.hideHighlight

static Mozilla.UITour.showInfo(target, title, text, icon="null", buttons=[], buttons[], options={})¶

显示一个带可选图像和按钮的箭头面板，该面板锚定在特定的 UI 目标上。

参数：

target (Mozilla.UITour.Target) – 要在其中锚定面板的 UI 小部件的标识符。
title (string) – 要作为面板标题显示的标题文本。
text (string) – 面板的正文文本。
icon (string) – 要在面板中显示的 48x48px（96px @ 2dppx）图像的 URL（该图像将相对于选项卡的 URI 解析）。
buttons (Array.<object>) – 描述按钮的对象数组。
buttons[].label (string) – 按钮标签
buttons[].icon (string) – 按钮图标 URL
buttons[].style (string) – 按钮样式（“primary”或“link”）
buttons[].callback (function) – 单击按钮时调用
options (object) – 高级选项
options.closeButtonCallback (function) – 单击面板的关闭按钮时调用。

示例

var buttons = [
  {
    label: 'Cancel',
    style: 'link',
    callback: cancelBtnCallback
  },
  {
    label: 'Confirm',
    style: 'primary',
    callback: confirmBtnCallback
  }
];

var icon = '//mozorg.cdn.mozilla.net/media/img/firefox/australis/logo.png';

var options = {
  closeButtonCallback: closeBtnCallback
};

Mozilla.UITour.showInfo('appMenu', 'my title', 'my text', icon, buttons, options);

另请参阅

Mozilla.UITour.hideInfo

static Mozilla.UITour.showMenu(name, callback)¶

打开指定的应用程序菜单。

参数：

name (Mozilla.UITour.MenuName) – 菜单名称
callback (function) – 菜单打开时不带任何参数调用的回调函数。

示例

Mozilla.UITour.showMenu('appMenu', function() {
  console.log('menu was opened');
});

另请参阅

Mozilla.UITour.hideMenu

static Mozilla.UITour.showNewTab()¶: 在游览选项卡中加载 about:newtab。

static Mozilla.UITour.showProtectionReport()¶: 在游览选项卡中加载 about:protections。

static Mozilla.UITour.toggleReaderMode()¶: 切换到当前选项卡的阅读器模式。一旦用户进入阅读器模式，UITour 文档将不再处于活动状态，因此无法调用其他 UITour API。

class Mozilla.UITour.Configuration()¶

static Mozilla.UITour.Configuration.AccountService()¶

有关帐户服务的信息

参数：

id (string) – 服务 ID。可以在我们的遥测文档站点上找到附加服务 ID 列表。
lastAccessedWeeksAgo (number) – 此帐户上次访问服务是多少周前。

static Mozilla.UITour.Configuration.AccountServices()¶: 有关附加到帐户的客户端的信息。一个对象。键是附加服务的字符串 ID。可以在我们的遥测文档站点上找到附加服务 ID 列表。该值是一个 Mozilla.UITour.Configuration.AccountService()

static Mozilla.UITour.Configuration.AppInfo()¶

参数：

canSetDefaultBrowserInBackground (boolean) – 应用程序是否可以在后台无需用户交互即可设置为默认浏览器。
defaultBrowser (boolean) – 应用程序是否为默认浏览器。从 Fx40 开始。
defaultUpdateChannel (string) – 更新渠道，例如“release”、“beta”、“aurora”、“nightly”、“default”（自建或自动化测试构建）
distribution (string) – 包含 distributionId 属性。此值在大多数情况下为“default”，但对于重新打包或 funnelcake 构建可能会不同。从 Fx48 开始
profileCreatedWeeksAgo (number) – 自创建配置文件以来的周数，对于创建日期少于 7 天的配置文件，从 0 开始。从 Fx56 开始。
profileResetWeeksAgo (数字) – 自上次重置配置文件以来经过的周数，从 0 开始，表示配置文件在不到 7 天前重置。如果配置文件从未重置，则返回 null。自 Fx56 版本起。
version (字符串) – 版本字符串，例如“48.0a2”。

static Mozilla.UITour.Configuration.AvailableTargets()¶: 当前可用于添加注释的 UI Targets 数组。

static Mozilla.UITour.Configuration.BrowserServices()¶

有关附加到浏览器的服务的信息。所有属性都是可选的，只有在服务启用时才存在。

参数：

sync (Mozilla.UITour.Configuration.Sync) – 如果配置了同步功能。

static Mozilla.UITour.Configuration.CanReset()¶

指示用户是否可以通过 Mozilla.UITour.resetFirefox() 刷新其 Firefox 配置文件。

另请参阅

Mozilla.UITour.resetFirefox

static Mozilla.UITour.Configuration.FxA()¶

FxA 本地状态，包括 FxA 是否已连接以及帐户的总体状态。

参数：

setup (布尔值) – FxA 是否在此设备上设置。如果为 false，则不会存在其他属性。
accountStateOK (布尔值) – FxA 帐户状态是否正常。如果为 false，则可能表示帐户未经验证，或者用户已在另一台设备上更改了密码，需要在此处更新。在这种情况下，许多其他属性将不存在。
browserServices (Mozilla.UITour.Configuration.BrowserServices) – 有关附加到此浏览器的帐户服务的信息，以及此浏览器实施的特殊支持。您不应期望在此浏览器中连接的每个帐户服务在此处都有一个特殊的条目。实际上，哪些服务以及将来在什么情况下可能会出现在此处在很大程度上尚未确定。

static Mozilla.UITour.Configuration.FxAConnections()¶

FxA 连接状态 - 有关帐户的信息，这些信息通常不会存储在本地，因此需要从 FxA 服务器获取。因此，请求此信息可能会导致高延迟，如果存在网络或服务器错误，则可能会返回不完整的数据。

参数：

setup (布尔值) – FxA 是否在此设备上设置。如果为 false，则不会存在其他属性。
numOtherDevices (数字) – 连接到此帐户的设备数量，不包括此设备。
numDevicesByType (Record.<字符串, 数字>) – 按设备“类型”连接到帐户的设备数量。类型的有效值由 FxA 服务器定义，但大致对应于外形尺寸，其值如“desktop”、“mobile”、“vr”等。
accountServices (Mozilla.UITour.Configuration.AccountServices) – 有关附加到此帐户的服务的信息。这些服务可能已在此浏览器的外部设备或应用程序上启用，不应与设备混淆。例如，如果用户在一台或多台设备（包括此设备）上启用了 Monitor 或 Lockwise，则该服务将在此处有一个条目。

static Mozilla.UITour.Configuration.Search()¶

从版本 34 到 42（含），“selectedSearchEngine”配置返回的是字符串，而不是像“search”这样的对象。

参数：

searchEngineIdentifier (字符串) – 默认引擎的标识符。
engines (Array.<字符串>) – 可见引擎的标识符。

static Mozilla.UITour.Configuration.Sync()¶

同步状态和设备数量。

参数：

setup (布尔值) – 是否已设置同步功能。
desktopDevices (数字) – 台式机设备数量。
mobileDevices (数字) – 移动设备数量。
totalDevices (数字) – 已连接设备的总数。

另请参阅

Mozilla.UITour.getConfiguration
Mozilla.UITour.ConfigurationName