Qt Installer Framework控制器脚本

Controller Scripting

控制器脚本

For each installer, you can specify a control script that interacts with certain parts of the installer's UI or functionality. To add the script to the installer, use the Configuration File element ControlScript, or from the command line enter --script <script_file>. The control script can add and remove pages to the wizard, change existing pages, do additional checks, and interact with the UI by simulating user clicks. This allows for example unattended installations.

​对于每个安装程序，可以指定一个与安装程序UI或功能的某些部分交互的控制脚本。要将脚本添加到安装程序中，请使用配置文件元素ControlScript，或从命令行输入--script<script_File>。控制脚本可以向向导添加和删除页面，更改现有页面，执行其他检查，并通过模拟用户单击与UI交互。例如，这允许无人值守的安装。

The script format has to be compatible with QJSEngine.

​脚本格式必须与QJSEngine兼容。

This section describes the functions that are called to implement such a control script. It also gives an overview of installer pages and the widgets that are available on each page, such as push buttons, radio buttons, and line edits.

本节介绍为实现此类控制脚本而调用的函数。它还概述了安装程序页面和每个页面上可用的widget，如按钮、单选按钮和行编辑。

Writing Control Scripts

编写控制脚本

A minimal valid script needs to contain at least a constructor, which can look like this:

一个最小有效脚本需要至少包含一个构造函数，它可以看起来像这样：

function Controller()
{
}

The following example presents a more advanced script that uses the gui JavaScript global object methods to set a new page title and welcome message on the introduction page and to automatically click the Next button on the target directory page:

​以下示例展示了一个更高级的脚本，该脚本使用gui JavaScript全局对象方法在介绍页面上设置新的页面标题和欢迎消息，并自动单击目标目录页面上的“下一步”按钮：

function Controller()
{
}

Controller.prototype.IntroductionPageCallback = function()
{
    var widget = gui.currentPageWidget(); // get the current wizard page
    if (widget != null) {
        widget.title = "New title."; // set the page title
        widget.MessageLabel.setText("New Message."); // set the welcome text
    }
}

Controller.prototype.TargetDirectoryPageCallback = function()
{
    gui.clickButton(buttons.NextButton); // automatically click the Next button
}

For more information about the JavaScript global objects that you can use in control scripts, see Scripting API.

​有关可以在控制脚本中使用的JavaScript全局对象的更多信息，请参阅编写API脚本。

In addition to the predefined global objects, the scripting API supports working with other objects derived from QObject. In the above code example the gui.currentPageWidget() method returns a widget of type QWidget.

除了预定义的全局对象之外，脚本API还支持使用从QObject派生的其他对象。在上面的代码示例中，gui.currentPageWidget（）方法返回一个QWidget类型的小部件。

The scripting API makes use of Qt's object trees. Widgets derived from QObject export their named child objects as properties for the JavaScript object, where the name of the property is the same as the child object's QObject::objectName. The default properties and their access functions of objects derived from QObject can also be used in the scripts.

脚本API利用了Qt的对象树。从QObject派生的Widget将其命名的子对象导出为JavaScript对象的属性，其中属性的名称与子对象的QObject::objectName相同。从QObject派生的对象的默认属性及其访问函数也可以在脚本中使用。

For example, in the above code the MessageLabel object from class QLabel is a child of the widget. The setText() is the setter access function for its QLabel::text property.

例如，在上面的代码中，QLabel类中的MessageLabel对象是widget的子对象。setText（）是QLabel::text属性的setter访问函数。

In addition to properties, the signals and public slots of objects derived from QObject can be used in both controller and component scripts.

除了属性之外，从QObject派生的对象的信号和公共槽也可以在控制器和组件脚本中使用。

Predefined Installer Pages

预定义安装程序页面

The QInstaller JavaScript object provides access to the following predefined installer pages:

​QInstaller JavaScript对象提供对以下预定义安装程序页面的访问：

• Introduction
• TargetDirectory
• ComponentSelection
• LicenseCheck
• StartMenuSelection
• ReadyForInstallation
• PerformInstallation
• InstallationFinished

The buttons JavaScript object provides a set of buttons that can be used on installer pages.

​buttons JavaScript对象提供了一组可在安装程序页面上使用的按钮。

The following sections describe the functions that you can implement to interact with installer pages and the widgets that are available on each page.

以下部分描述了可以实现的与安装程序页面和每个页面上可用的widget交互的功能。

Introduction Page

介绍页面

Implement the Controller.prototype.IntroductionPageCallback() function to interact with widgets on the introduction page.

实现Controller.prototype.IntroductionPageCallback()函数用于与介绍页面上的widget进行交互。

Wizard buttons:

向导按钮：

• NextButton
• CancelButton

Widgets	Brief Description
ErrorLabel	Displays an error message. 显示错误消息。
MessageLabel	Displays a message. By default, it displays the "Welcome to the <Name> Setup" message. ​显示一条消息。默认情况下，它显示“欢迎使用<Name>安装程序”消息。
InformationLabel	Displays progress information. 显示进度信息。

Radio Buttons	Brief Description
PackageManagerRadioButton	The package manager radio button shown on the page while running as maintenance tool. 作为维护工具运行时，页面上显示的包管理器单选按钮。
UpdaterRadioButton	The updater radio button shown on the page while running as maintenance tool. 作为维护工具运行时，页面上显示的更新器单选按钮。
UninstallerRadioButton	The uninstaller radio button shown on the page while running as maintenance tool. Selected by default. 作为维护工具运行时，页面上显示的卸载程序单选按钮。默认情况下已选择。

Progress Bar	Brief Description
InformationProgressBar	The progress bar shown while fetching remote packages. 获取远程包时显示的进度条。

Qt Core Feature	Brief Description
packageManagerCoreTypeChanged()	Connect to this signal if you want to be notified when the type of maintenance tool changes. 如果想在维护工具类型更改时收到通知，请连接到此信号。 Note: The signal is only emitted when the user has started the binary as so called maintenance tool (after the installation) and switches between the radio buttons. 注意：只有当用户启动所谓的维护工具（安装后）并在单选按钮之间切换时，才会发出信号。

Example code:

示例代码：

function Controller()
{
    var widget = gui.pageById(QInstaller.Introduction); // get the introduction wizard page
    if (widget != null)
        widget.packageManagerCoreTypeChanged.connect(onPackageManagerCoreTypeChanged);
}

onPackageManagerCoreTypeChanged = function()
{
    console.log("Is Updater: " + installer.isUpdater());
    console.log("Is Uninstaller: " + installer.isUninstaller());
    console.log("Is Package Manager: " + installer.isPackageManager());
}

License Agreement Page

许可协议页面

Implement the Controller.prototype.LicenseAgreementPageCallback() function to interact with widgets on the license agreement page.

实现Controller.prototype.LicenseAgreementPageCallback()函数用于与许可协议页面上的widget进行交互。

Wizard buttons:

向导按钮：

• NextButton
• CancelButton
• BackButton

Widgets	Brief Description
LicenseListWidget	Lists the available licenses. 列出可用的许可证。
LicenseTextBrowser	Shows the content of the selected license file. 显示所选许可证文件的内容。
AcceptLicenseLabel	Shows the text next to the accept license check box. 显示接受许可证复选框旁边的文本。
AcceptLicenseCheckBox	Accepts the license agreement. 接受许可协议。

Target Directory Page

目标目录页面

Implement the Controller.prototype.TargetDirectoryPageCallback() function to interact with widgets on the target directory selection page.

实现Controller.prototype.TargetDirectoryPageCallback() 函数用于与目标目录选择页面上的widget进行交互。

Wizard buttons:

向导按钮：

• NextButton
• CancelButton
• BackButton

Widgets	Brief Description
MessageLabel	Displays a message. 显示一条消息。
TargetDirectoryLineEdit	Displays the value of the installation's target directory. 显示安装的目标目录的值。
WarningLabel	Displays a warning. 显示警告。

Component Selection Page

组件选择页面

Implement the Controller.prototype.ComponentSelectionPageCallback() function to interact with widgets on the component selection page.

实现Controller.prototype.ComponentSelectionPageCallback()函数用于与组件选择页面上的widget进行交互。

Wizard buttons:

向导按钮：

• NextButton
• CancelButton
• BackButton

Methods	Brief Description
selectAll()	Selects all available packages if possible. 如果可能，选择所有可用的软件包。
deselectAll()	Deselects all available packages if possible. 如果可能，取消选择所有可用包。
selectDefault()	Resets the checked state of available packages to their initial state. 将可用包的已检查状态重置为其初始状态。
selectComponent(id)	Selects the package with id (string). 选择id为（字符串）的包。
deselectComponent(id)	Deselects the package with id (string). 取消选择id为（字符串）的包。

Push Buttons	Brief Description
SelectAllComponentsButton	Selects all available packages if possible. 如果可能，选择所有可用的软件包。
DeselectAllComponentsButton	Deselects all available packages if possible. 如果可能，取消选择所有可用包。
SelectDefaultComponentsButton	Resets the checked state of available packages to their initial state. 将可用包的已检查状态重置为其初始状态。
ResetComponentsButton	Resets to already installed components. 重置为已安装的组件。
FetchCategoryButton	Fetch components from a category. 从类别中获取组件。

Widgets	Brief Description
CategoryGroupBox	Contains checkboxes for selecting repository categories. 包含用于选择存储库类别的复选框。

Installer Framework 3.1 introduces repository categories as a new feature. When you use an installer that contains repository categories, you can select a category by its display name, fetch its contents, and then select the included components for installation.

Installer Framework 3.1引入了存储库类别作为一项新功能。当使用包含存储库类别的安装程序时，可以通过显示名称选择类别，获取其内容，然后选择包含的组件进行安装。

You can fetch the components from a category as follows:

可以按如下方式从类别中获取组件：

Controller.prototype.ComponentSelectionPageCallback = function()
{
    var page = gui.pageWidgetByObjectName("ComponentSelectionPage");

    // if CategoryGroupBox is visible, check one of the checkboxes
    // and click fetch button before selecting any components
    var groupBox = gui.findChild(page, "CategoryGroupBox");
    if (groupBox) {
        console.log("groupBox found");
        // findChild second argument is the display name of the checkbox
        var checkBox = gui.findChild(page, "Archive");
        if (checkBox) {
            console.log("checkBox found");
            console.log("checkBox name: " + checkBox.text);
            if (checkBox.checked == false) {
                checkBox.click();
                var fetchButton = gui.findChild(page, "FetchCategoryButton");
                if (fetchButton) {
                    console.log("fetchButton found");
                    fetchButton.click();
                } else {
                    console.log("fetchButton NOT found");
                }
            }
        } else {
            console.log("checkBox NOT found");
        }
    } else {
        console.log("groupBox NOT found");
    }
    // you can now select components from the fetched category
}

Start Menu Directory Page

开始菜单目录页面

Implement the Controller.prototype.StartMenuDirectoryPageCallback() function to interact with widgets on the ready for installation page.

实现Controller.prototype.StartMenuDirectoryPageCallback()函数用于与准备安装页面上的widget进行交互。

Wizard buttons:

向导按钮：

• NextButton
• CancelButton
• BackButton

Widgets	Brief Description
StartMenuPathLineEdit	Shows the directory where to create the program's shortcut. 显示创建程序快捷方式的目录。

Ready for Installation Page

准备安装页面

Implement the Controller.prototype.ReadyForInstallationPageCallback() function to interact with widgets on the ready for installation page.

实现Controller.prototype.ReadyForInstallationPageCallback()函数用于与安装就绪页面上的widget进行交互。

Wizard buttons:

向导按钮：

• CommitButton
• CancelButton
• BackButton

Widgets	Brief Description
MessageLabel	Displays a message. 显示一条消息。
TaskDetailsBrowser	Displays some more detailed information about the installation. 显示有关安装的一些更详细的信息。

Perform Installation Page

执行安装页面

Implement the Controller.prototype.PerformInstallationPageCallback() function to interact with widgets on the perform installation page.

实现Controller.prototype.PerformInstallationPageCallback() 函数用于与执行安装页面上的widget进行交互。

Wizard buttons:

向导按钮：

• CommitButton
• CancelButton

Finished Page

结束页面

Implement the Controller.prototype.FinishedPageCallback() function to interact with widgets on the installation finished page.

实现Controller.prototype.FinishedPageCallback()函数用于与安装完成页面上的小部件进行交互。

Wizard buttons:

向导按钮：

• CommitButton
• CancelButton
• FinishButton

Widgets	Brief Description
MessageLabel	Displays a message. 显示一条消息。
RunItCheckBox	Text field that informs users that they can start an application after the installation process has finished. 文本字段，通知用户可以在安装过程完成后启动应用程序。

Custom Pages

自定义页面

Custom pages are registered as Dynamic${ObjectName}, where ${ObjectName} is the object name set in the UI file. Thus, the Dynamic${ObjectName}Callback() function is called. Widgets can be addressed using their object names (from the UI file).

自定义页面注册为Dynamic${ObjectName}，其中${ObjectName}是UI文件中设置的对象名。因此，Dynamic${ObjectName}Callback()函数被调用。Widget可以使用其对象名称（来自UI文件）进行寻址。

Example code:

示例代码：

function Component()
{
    // add page with widget \c SomePageWidget before the target directory page
    installer.addWizardPage(component, "SomePageWidget", QInstaller.TargetDirectory)
}

Component.prototype.DynamicSomePageWidgetCallback = function()
{
    var page = gui.pageWidgetByObjectName("DynamicSomePageWidget");
    page.myButton.click, //direct child of the UI file's widget
    page.someFancyWidget.subWidget.setText("foobar") // nested widget
}

Message Boxes

消息框

While executing the installer application, for example, the application might show some message boxes about an error that occurred. This is fine while running the application on the end user's system, but it might break automated test suites. To overcome this issue, all message boxes shown by the Qt Installer Framework are addressable by a specific identifier.

例如，在执行安装程序应用程序时，应用程序可能会显示一些关于发生的错误的消息框。在最终用户的系统上运行应用程序时，这很好，但可能会破坏自动化测试套件。为了解决这个问题，Qt安装程序框架显示的所有消息框都可以通过特定的标识符进行寻址。

Identifier	Possible Answers	Description
OverwriteTargetDirectory	Yes, No	Confirmation for using an already existing directory as the target directory for installation. 确认使用现有目录作为安装目标目录。
installationError	OK, Retry, Ignore	A fatal error occurred while performing the installation. 执行安装时发生致命错误。
installationErrorWithRetry	Retry, Ignore, Cancel	An error occurred while performing the installation. End users can select Retry to try again. 执行安装时出错。最终用户可以选择“重试”以重试。
AuthorizationError	Abort, OK	Elevated permissions could not be acquired. 无法获取提升的权限。
OperationDoesNotExistError	Abort, Ignore	An error occurred while trying to perform an operation, but the operation did not exist. 尝试执行操作时出错，但该操作不存在。
isAutoDependOnError	OK	An error occurred while calling a package script. It was not possible to evaluate if the package has a auto dependency on other packages. 调用包脚本时出错。无法评估该包是否自动依赖于其他包。
isDefaultError	OK	An error occurred while calling a package script. It was not possible to evaluate if the package will be installed by default. 调用包脚本时出错。无法评估默认情况下是否会安装该包。
DownloadError	Retry, Cancel	An error occurred while downloading an archive hash from a remote repository. End users can select Retry to try again. 从远程存储库下载存档哈希时出错。最终用户可以选择“重试”以重试。
archiveDownloadError	Retry, Cancel	An error occurred while downloading a archive from a remote repository. End users can select Retry to try again. 从远程存储库下载存档时出错。最终用户可以选择“重试”以重试。
WriteError	OK	An error occurred while writing the maintenance tool. 写入维护工具时出错。
ElevationError	OK	Elevated permissions could not be acquired. 无法获取提升的权限。
unknown	OK	An unknown error occurred while removing a certain package. 删除某个包时发生未知错误。
Error	OK	Generic error. 一般错误。
stopProcessesForUpdates	Retry, Ignore, Cancel	An error occurred while updating a package. Some running application or process needs to be quit before the update can be performed. End users can select Retry to try again once they have been stopped. 更新包时出错。在执行更新之前，需要退出某些正在运行的应用程序或进程。最终用户可以选择“重试”，在停止后重试。
Installer_Needs_To_Be_Local_Error	OK	The installer binary was started from a network location, but the installation over network is not supported. 安装程序二进制文件是从网络位置启动的，但不支持通过网络进行安装。
TargetDirectoryInUse	No	The installation's target directory already contains an installation. 安装的目标目录已包含安装。
WrongTargetDirectory	OK	The installation's target directory is a file or symlink. 安装的目标目录是一个文件或符号链接。
AlreadyRunning	OK	Another application instance is already running. 另一个应用程序实例已在运行。

Example code:

示例代码：

function Controller()
{
    installer.autoRejectMessageBoxes;
    installer.setMessageBoxAutomaticAnswer("OverwriteTargetDirectory", QMessageBox.Yes);
    installer.setMessageBoxAutomaticAnswer("stopProcessesForUpdates", QMessageBox.Ignore);
}

Package DirectoryComponent Scripting

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. The Qt Company, Qt and their respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.