Qt Installer Framework组件脚本

Component Scripting

组件脚本

For each component, you can specify one script that prepares the operations to be performed by the installer. The script format has to be compatible with QJSEngine.

​对于每个组件，可以指定一个脚本来准备安装程序要执行的操作。脚本格式必须与QJSEngine兼容。

Construction

构造

The script has to contain a Component object that the installer creates when it loads the script. Therefore, the script must contain at least the Component() function, which performs initialization, such as putting pages in the correct places or connecting signals and slots.

脚本必须包含安装程序在加载脚本时创建的Component对象。因此，脚本必须至少包含Component（）函数，该函数执行初始化，例如将页面放在正确的位置或连接信号和插槽。

The following code snippet places the ErrorPage (which is the class name of the user interface file loaded from errorpage.ui) in front of the ready for installation page and sets its completeness to false.

以下代码片段将ErrorPage（从errorpage.ui加载的用户界面文件的类名）放置在准备安装页面之前，并将其完整性设置为false。

function Component()
{
    // Add a user interface file called ErrorPage, which should not be complete
    installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation );
    component.userInterface( "ErrorPage" ).complete = false;
}

For more information, see the documentation for installer::addWizardPage() and component::userInterface().

​有关更多信息，请参阅installer::addWizardPage（）和component::userInterface（）的文档。

Installer Hooks

安装钩

You can add the following hook methods into your script:

可以将以下钩子方法添加到脚本中：

Method	Description
Component.prototype.retranslateUi	Called when the language of the installer changes. 当安装程序的语言更改时调用。
Component.prototype.createOperations	See component::createOperations(). ​请参阅component::createOperations（）。
Component.prototype.createOperationsForArchive	See component::createOperationsForArchive(). ​请参阅component::createOperationsForArchive（）。
Component.prototype.createOperationsForPath	See component::createOperationsForPath(). ​请参阅component::createOperationsForPath（）。

Global Variables

全局变量

The installer puts the following symbols into the script space:

安装程序将以下符号放入脚本空间：

Symbol	Description
installer	Reference to the QInstaller of the component ​参考组件的QInstaller
component	Reference to the Component. of the component ​参考组件的Component

Message Boxes

消息框

You can show a QMessageBox from within the script by using the following static members:

​可以使用以下静态成员在脚本中显示QMessageBox：

• QMessageBox::critical()
• QMessageBox::information()
• QMessageBox::question()
• QMessageBox::warning()

For your convenience, the values for QMessageBox::StandardButton are made available by using QMessageBox.Ok, QMessageBox.Open, and so on.

​为了方便，QMessageBox::StandardButton的值可以通过使用QMessageBox.Ok, QMessageBox.Open来等获得。

Adding Operations to Components

向组件添加操作

You might want to add custom operations after extracting the content, when copying files or patching file content, for example. You can create and add update operations to the installation from within a script using component::addOperation(). If you need to run an operation that requires administrative rights, use component::addElevatedOperation() instead. Alternative way of adding custom operations is to use component.xml, see Package Directory

​例如，在复制文件或修补文件内容时，可能希望在提取内容后添加自定义操作。可以使用component::addOperation（）在脚本中创建更新操作并将其添加到安装中。如果需要运行需要管理权限的操作，请改用component::addElevatedOperation（）。添加自定义操作的另一种方法是使用component.xml，请参阅包目录

Operations need to be added before the actual installation step. Override component::createOperations() to register custom operations for a component.

​在实际安装步骤之前，需要添加操作。重写component::createOperations（）以注册组件的自定义操作。

Each operation has a unique key used for identification and can take up to five parameters. In the parameter values, you can use variables as set in installer::setValue(). For more information, see Predefined Variables.

​每个操作都有一个用于识别的唯一密钥，最多可以接受五个参数。在参数值中，可以使用installer::setValue（）中设置的变量。有关详细信息，请参见预定义变量。

For a summary of all available operations, see Operations.

​有关所有可用操作的摘要，请参阅操作。

Registering Custom Operations

注册自定义操作

You can register custom installation operations in the installer by deriving the KDUpdater::UpdateOperation class. The following code displays the methods that you must implement:

​可以通过派生KDUpdater::UpdateOperation类在安装程序中注册自定义安装操作。以下代码显示了必须实现的方法：

#include <UpdateOperation>

class CustomOperation : public KDUpdater::UpdateOperation
{
public:
  CustomOperation()
  {
      setName( "CustomOperation" );
      setGroup( Install );
  }

  void backup()
  {
      // do whatever is needed to restore the state in undoOperation()
  }

  bool performOperation()
  {
      const QStringList args = arguments();
      // do whatever is needed to do for the given arguments

      bool success = ...;
      return success;
  }

  void undoOperation()
  {
      // restore the previous state, as saved in backup()
  }

  bool testOperation()
  {
      // currently unused
      return true;
  }

  CustomOperation* clone() const
  {
      return new CustomOperation;
  }

  QDomDocument toXml()
  {
      // automatically adds the operation's arguments and everything set via setValue
      QDomDocument doc = KDUpdater::UpdateOperation::toXml();

      // if you need any information to undo the operation you did,
      // add them to the doc here

      return doc;
  }

  bool fromXml( const QDomDocument& doc )
  {
      // automatically loads the operation's arguments and everything set via setValue
      if( !KDUpdater::UpdateOperation::fromXml( doc ) )
          return false;

      // if you need any information to undo the operation you did,
      // read them from the doc here

      return true;
  }
};

Finally, you need to register your custom operation class, as follows:

最后，需要注册自定义操作类，如下所示：

#include <UpdateOperationFactory>

KDUpdater::UpdateOperationFactory::instance().registerUpdateOperation< CustomOperation >( "CustomOperation" );

Now you can use your operation in the installer in the same way as the predefined operations.

现在，可以在安装程序中以与预定义操作相同的方式使用操作。

Predefined Variables

预定义变量

You can use the following predefined variables in scripts to facilitate directory access:

可以在脚本中使用以下预定义变量来方便目录访问：

Symbol	Description
ProductName	Name of the product to be installed, as defined in config.xml. 要安装的产品的名称，如config.xml中所定义。
ProductVersion	Version number of the product to be installed, as defined in config.xml. 待安装产品的版本号，如config.xml中所定义。
Title	Title of the installation program, as defined in config.xml. 安装程序的标题，如config.xml中所定义。
Publisher	Publisher of the installation program, as defined in config.xml. 安装程序的发布者，如config.xml中所定义。
Url	Product URL, as defined in config.xml. 产品URL，如config.xml中定义的。
StartMenuDir	Start menu group, as defined in config.xml. Only available on Windows. 开始菜单组，如config.xml中所定义。仅在Windows上可用。
TargetDir	Target directory for installation, as selected by the user. 用户选择的安装目标目录。
DesktopDir	Name of the directory that contains the user's desktop. Only available on Windows. 包含用户桌面的目录的名称。 仅在Windows上可用。
os	Current platform: "x11", "win", or "mac". This variable is deprecated: Use systemInfo instead. ​当前平台：“x11”、“win”或“mac”。 此变量已弃用：请改用systemInfo。
FrameworkVersion	Version number of the Qt Installer Framework used to build the installation program. 用于构建安装程序的Qt安装程序框架的版本号。
RootDir	Root directory of the filesystem. 文件系统的根目录。
HomeDir	Home directory of the current user. 当前用户的主目录。
ApplicationsDir	Applications directory. 应用程序目录。 For example, C:\Program Files on Windows, /opt on Linux and /Applications on macOS. 例如，Windows上的C:\Program Files，Linux上的/opt和macOS上的/Applications。 See also the table that lists examples of applications directories on Windows. ​另请参阅列出Windows上应用程序目录示例的表。
ApplicationsDirUser	Applications directory for user-specific programs. This is useful on macOS, on other platforms it is the same as ApplicationsDir. For example, $HOME/Applications on macOS. 用户特定程序的应用程序目录。这在macOS上很有用，在其他平台上与ApplicationsDir相同。 例如，macOS上的$HOME/Applications。
ApplicationsDirX86	Applications Directory for 32 bit programs. This is useful on Windows, on other platforms it is the same as ApplicationsDir. 32位程序的应用程序目录。这在Windows上很有用，在其他平台上与ApplicationsDir相同。 For example, C:\Program Files (x86) on Windows. See also the table that lists examples of applications directories on Windows. ​例如，Windows上的C:\Program Files（x86）。 另请参阅列出Windows上应用程序目录示例的表。
ApplicationsDirX64	Applications Directory for 64 bit programs. This is useful on Windows, on other platforms it is the same as ApplicationsDir. 64位程序的应用程序目录。这在Windows上很有用，在其他平台上与ApplicationsDir相同。 For example, C:\Program Files on Windows. 例如，Windows上的C:\Program Files。 See also the table that lists examples of applications directories on Windows. ​请参阅列出Windows上应用程序目录示例的表。
InstallerDirPath	The directory that contains the installer application executable. 包含安装程序应用程序可执行文件的目录。
InstallerFilePath	The file path of the installer application executable. 安装程序应用程序可执行文件的文件路径。
UserStartMenuProgramsPath	The path to the folder containing the items in the Start menu of the user. 包含用户“开始”菜单中项目的文件夹的路径。 For example, C:\Users\USERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs Only available on Windows. 例如，C:\Users\USERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs 仅在Windows上可用。
AllUsersStartMenuProgramsPath	The path to the folder containing the items in the Start menu for all users. 包含所有用户“开始”菜单中项目的文件夹的路径。 For example, C:\ProgramData\Microsoft\Windows\Start Menu\Programs Only available on Windows. 例如，C:\ProgramData\Microsoft\Windows\Start Menu\Programs 仅在Windows上可用。
UILanguage	The language that is used in the installer. 安装程序中使用的语言。

The variables can be resolved by calls to installer::value(). If embedded in '@' they can also be part of strings passed as arguments to installation operations:

​这些变量可以通过调用installer::value（）来解析。如果嵌入在“@”中，它们也可以作为参数传递给安装操作的字符串的一部分：

if (installer.value("os") === "win") {
    component.addOperation("CreateShortcut", "@TargetDir@/MyApp.exe", "@StartMenuDir@/MyApp.lnk");
}

For example, applications directory on Windows:

例如，Windows上的应用程序目录：

OS (Windows)	Qt Installer Framework	Variable	Example Path
32bit	32bit	ApplicationsDir	C:\Program Files
		ApplicationsDirX86	C:\Program Files
		ApplicationsDirX64	C:\Program Files
64bit	32bit	ApplicationsDir	C:\Program Files (x86)
		ApplicationsDirX86	C:\Program Files (x86)
		ApplicationsDirX64	C:\Program Files
	64bit	ApplicationsDir	C:\Program Files
		ApplicationsDirX86	C:\Program Files (x86)
		ApplicationsDirX64	C:\Program Files

Using postLoad in Component Script

在组件脚本中使用postLoad

By default, component scripts are evaluated before the install tree view is shown. This can have performance cost if there is a huge amount of components with component scripts. The postLoad attribute introduces a way to evaluate the component script right before installation starts, only for the components that are selected for installation or update:

默认情况下，在显示安装树视图之前，会先评估组件脚本。如果有大量带有组件脚本的组件，这可能会带来性能成本。postLoad属性引入了一种在安装开始前评估组件脚本的方法，仅适用于选择安装或更新的组件：

<Script postLoad="true">my_install_script.qs</Script>

Whether postLoad can be set to true must be considered case by case, depending on the contents of the script. For example, if the script contents affect the install tree view, like setting <Default> to true, setting new dependencies, or adding new wizard pages, postLoad must not be used or it must be set to false. If the script contains only methods that are run during the installation, postLoad can be set to true. For example, all overridden operation functions are run during installation. For more information, see Adding Operations to Components. If you are not sure when to use postLoad, then don't use it. The performance cost is huge only when there are thousands of scripts to be evaluated.

​postLoad是否可以设置为true必须根据脚本的内容逐案考虑。例如，如果脚本内容影响安装树视图，如将<Default>设置为true、设置新的依赖关系或添加新的向导页面，则不得使用postLoad或必须将其设置为false。如果脚本仅包含在安装过程中运行的方法，则可以将postLoad设置为true。例如，所有被覆盖的operation 功能都在安装过程中运行。有关详细信息，请参见向组件添加操作。如果你不确定什么时候使用postLoad，那就不要使用它。只有当有数千个脚本需要评估时，性能成本才是巨大的。

Both <Script postLoad="true"> and <Script> tags can be used at the same time. This means that one component can have one script that is evaluated when the installation starts and another script that is evaluated before the install tree view is shown.

<Script postLoad=“true”>和<Script>标签可以同时使用。这意味着一个组件可以有一个在安装开始时评估的脚本和一个在显示安装树视图之前评估的脚本。

Controller ScriptingOperations

© 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.