Qt Installer Framework操作

Operations

操作

The operations are prepared by component and controller scripts or component.xml and performed by the installer.

这些操作由组件和控制器脚本或component.xml准备，并由安装程序执行。

Note: Operations are performed threaded.

注意：操作是线程化的。

Internally, each operation has a DO step that contains instructions for the installer and an UNDO step that contains instructions for the uninstaller.

在内部，每个操作都有一个DO步骤和一个UNDO步骤，DO步骤包含安装程序的说明，UNDO步骤包含卸载程序的说明。

Some operations especially in Windows might need native separators. Use installer.toNativeSeparators() to convert separators to ones that are appropriate for the underlying operating system.

某些操作（尤其是在Windows中）可能需要本机分隔符。使用installer.toNativeSeparators（）将分隔符转换为适合底层操作系统的分隔符。

Summary of Operations

操作概况

The following table summarizes the available operations and their syntax in component and controller scripts. Syntax for operations in component.xml is:

下表总结了组件和控制器脚本中的可用操作及其语法。component.xml中操作的语法为：

<Operations>
  <Operation name="operation">
    <Argument>argument1</Argument>
    <Argument>argument2</Argument>
  </Operation>
</Operations>

Note: The argument order in component.xml is the same as in scripting, except for Extract operation where the argument archive is optional, and must be defined as the last argument.

注意：component.xml中的参数顺序与脚本中的相同，除了Extract操作，其中参数archive 是可选的，并且必须定义为最后一个参数。

Operation	Syntax	Use
Copy	"Copy" source target	Copies a file from source to target. 将文件从源复制到目标。 Note: The file will be restored during unistallation. If you want to skip the copying, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：文件将在卸载过程中恢复。如果要跳过复制，可以通过将UNDOOPERATION和“”传递到参数列表末尾来覆盖UNDO。
Move	"Move" source target	Moves a file from source to target. 将文件从源移动到目标。 Note: Files restored during uninstallation. If you want to move the files persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：卸载过程中还原的文件。如果要持久移动文件，可以通过将UNDOOPERATION和“”传递到参数列表末尾来覆盖UNDO。
SimpleMoveFile	"SimpleMoveFile" source target	Moves a file from source to target. 将文件从源移动到目标。 Note: Files will be moved from target to source during uninstallation. If you want to move the files persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：在卸载过程中，文件将从目标移动到源。如果要持久移动文件，可以通过将UNDOOPERATION和“”传递到参数列表末尾来覆盖UNDO。
Delete	"Delete" filename	Deletes the file specified by filename. 删除由filename指定的文件。 Note: File will be restored during uninstallation. If you want to delete the files persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：文件将在卸载过程中还原。如果要持久删除文件，可以通过在参数列表末尾传递UNDOOPERATION和“”来覆盖UNDO。
Mkdir	"Mkdir" path	Creates the directory path path. 创建目录路径。 Note: Directory will be deleted during uninstallation. If you want to create the directory persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. Note that during full uninstall, directory will be deleted if it was created to target directory and RemoveTargetDir is false. 注意：卸载过程中将删除目录。如果你想持久地创建目录，你可以通过将UNDOOPERATION和“”传递到参数列表的末尾来覆盖UNDO。请注意，在完全卸载期间，如果目录是创建到目标目录的，并且RemoveTargetDir为false，则该目录将被删除。
Rmdir	"Rmdir" path	Removes the directory path path. 删除目录路径。 Note: Directory will be recreated during uninstallation. If you want to remove the directory persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：卸载过程中将重新创建目录。如果要持久删除目录，可以通过在参数列表末尾传递UNDOOPERATION和“”来覆盖UNDO。
CopyDirectory	"CopyDirectory" sourcePath targetPath	Copies a directory from sourcePath to targetPath. 将目录从sourcePath复制到targetPath。 Note: Directories will be reset during uninstallation. If you want to copy the directory persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：卸载过程中将重置目录。如果要持久复制目录，可以通过在参数列表末尾传递UNDOOPERATION和“”来覆盖UNDO。
AppendFile	"AppendFile" filename text	Appends text to the file specified by filename. text is treated as ASCII text. 将text 附加到文件名指定的filename. text中，被视为ASCII文本。 Note: Text will be removed from file during unistallation. If you want to append the text persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：在取消列表期间，文本将从文件中删除。如果要持久地附加文本，可以通过在参数列表末尾传递UNDOOPERATION和“”来覆盖UNDO。
PrependFile	"PrependFile" filename text	Prepends text to the file specified by filename. text is treated as ASCII text. 将text 置于文件名指定的filename. text之前，文本被视为ASCII文本。 Note: Text will be removed from file during unistallation. If you want to append the text persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：在取消列表期间，文本将从文件中删除。如果要持久地附加文本，可以通过在参数列表末尾传递UNDOOPERATION和“”来覆盖UNDO。
Replace	"Replace" file search replace mode	Opens file to find search string and replaces that with the replace string, using mode that can be either string or regex. For regular expressions containing capturing groups, occurrences of \1, \2, ..., in replace are replaced with the string captured by the corresponding capturing group. 打开file 以查找search 字符串，并使用字符串或正则表达式mode 将其替换为replace 字符串。对于包含捕获组的正则表达式，出现\1、\2、…、。。。，替换为相应捕获组捕获的字符串。 Note that testing the operation using devtool does not support commas inside the search pattern as they are used as argument separators. When using regex mode you should also ensure the search pattern adheres to QRegularExpression class documentation, particularly to the escaping rules for characters. 请注意，使用devtool测试操作不支持search 模式中的逗号，因为它们被用作参数分隔符。使用正则表达式模式时，您还应该确保regex 模式符合QRegularExpression类文档，特别是字符的转义规则。
LineReplace	"LineReplace" file search replace	Opens file to find lines that start with search string and replaces that with the replace string. Lines are trimmed before the search. 打开file 以查找以search 字符串开头的行，并将其替换为replace 字符串。在搜索之前，行会被修剪。
Execute	"Execute" [{exitcodes}] command [parameter1 [parameter... [parameter10]]]	Executes the command specified by command. Up to 10 parameters can be passed. If that is not enough, you can use a JavaScript string array. 执行命令指定的命令。最多可以传递10个参数。如果这还不够，可以使用JavaScript字符串数组。 Optionally, you can pass a comma-separated list of exit codes within curly brackets ({}) as the first argument to specify the exit codes for successful execution. This defaults to "{0}". Other optional named arguments are: "workingdirectory=<your_working_dir>"; "errormessage=<your_custom_errormessage>" 可以选择在花括号（｛｝）内传递一个逗号分隔的退出代码列表作为第一个参数，以指定成功执行的退出代码。默认为“｛0｝”。 其他可选的命名参数有：“workingdirectory=<your_working_dir>”；“errormessage=<your_custom_errormessage>” In addition, a special argument, UNDOEXECUTE, separates the DO step of the operation from the UNDO step. 此外，一个特殊的参数UNDOEXECUTE将操作的DO步骤与UNDO步骤分开。 Example: component.addOperation("Execute", "touch", "test.txt", "UNDOEXECUTE", "rm", "test.txt") 示例：component.addOperation("Execute", "touch", "test.txt", "UNDOEXECUTE", "rm", "test.txt")
CreateShortcut	"CreateShortcut" filename linkname [arguments]	Creates a shortcut from the file specified by filename to linkname. On Windows, this creates a .lnk file which can have arguments. 从文件名指定的文件到链接名创建快捷方式。在Windows上，这会创建一个可以有参数的.lnk文件。 Furthermore, filename can be an HTTP, HTTPS or FTP URL in which case a URL shortcut is created. 此外，filename 可以是HTTP、HTTPS或FTP URL，在这种情况下会创建URL快捷方式。 Note: If the @AllUsersStartMenuProgramsPath@ is used for placing the shortcut, then due to a problem on Windows, it will drop any arguments to the target and any description set. In this case, you should place the shortcut elsewhere and copy it to the location desired. 注意：如果使用@AllUsersStartMenuProgramsPath@来放置快捷方式，则由于Windows上的问题，它将删除目标的任何参数和任何描述集。在这种情况下，应该将快捷方式放置在其他位置并将其复制到所需的位置。 Note: Creating a shortcut to a network share is not supported. The operation is currently not implemented on other platforms. 注意：不支持创建网络共享的快捷方式。该操作目前尚未在其他平台上实现。
CreateDesktopEntry	"CreateDesktopEntry" filename "key=value[ key2=value2[ key3=value3]]]"	Creates a .desktop initialization file, as specified by freedesktop.org. This operation is useful only on X11 or Wayland based Linux distributions. 按照freedesktop.org的指定创建.desktop初始化文件。此操作仅在基于X11或Wayland的Linux发行版上有用。 If filename is absolute, the desktop entry is stored there. Otherwise, it is stored in the location specified in $XDG_DATA_HOME/applications, including the default path, as defined by freedesktop.org. For system-wide installations, it is stored in /usr/local/share/applications instead. 如果filename是绝对的，则桌面条目存储在那里。否则，它将存储在$XDG_DATA_HOME/applications中指定的位置，包括freedesktop.org定义的默认路径。对于系统范围的安装，它存储在/usr/local/share/applications中。 The key-value pairs are written to the file. 键值对被写入文件。 The file is set to use UTF-8 encoding. 设置编码
InstallIcons	"InstallIcons" directory [Vendorprefix]	Installs the contents of directory into a location, as specified by freedesktop.org. That is, into $XDG_DATA_HOME/icons, $HOME/.local/share/icons or /usr/local/share/icons. The files are removed from their initial location. Make sure to add this operation after the operation that extracts the files from the archive. If you provide a Vendorprefix it replaces all characters up to the first dash (-) in the filename of the icon with this prefix. 将directory 的内容安装到freedesktop.org指定的位置。也就是说，安装到$XDG_DATA_HOME/icons、$HOME/.local/share/icons或/usr/local/share-icons中。文件将从其初始位置删除。请确保在从存档中提取文件的操作之后添加此操作。如果提供Vendorprefix ，它将用此前缀替换图标文件名中直到第一个破折号（-）的所有字符。
Extract	"Extract" archive targetdirectory	Extracts archive to targetdirectory. Extract operations are called before other operations. Note that in component.xml argument archive is optional and thus must be defined as the last parameter. 将archive 提取到targetdirectory目录。提取操作在其他操作之前调用。请注意，在component.xml中，参数archive是可选的，因此必须定义为最后一个参数。
GlobalConfig	"GlobalConfig" company application key value or "GlobalConfig" scope company application key value or "GlobalConfig" filename key value	Stores value for key in a configuration file. The configuration file is specified either by filename (using QSettings::NativeFormat, which might be the Windows registry) or by application and company name. Set scope to "SystemScope" to create an entry in the system scope. 将key 的value 存储在配置文件中。配置文件由filename （使用QSettings::NativeFormat，可能是Windows注册表）或application 和company 名称指定。将作用scope 设置为“SystemScope”以在系统作用域中创建条目。 Note: GlobalConfig will be reset during uninstallation. If you want to make the config persistent, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：卸载过程中将重置GlobalConfig。如果想使配置持久化，可以通过将UNDOOPERATION和“”传递到参数列表的末尾来覆盖UNDO。 Note: The operation is using QSettings to store the key value pair. QSettings always treats backslash as a special character and provides no API for reading or writing such entries. Do not use slashes ('/' and '\') in section or key names; the backslash character is used to separate sub keys. On windows, '\' are converted by QSettings to '/', which makes them identical. Because the backslash character is used by QSettings to separate sub keys, you cannot read or write windows registry entries that contain slashes or backslashes. You should use a native windows API if you need to do so. ​ 注意：该操作使用QSettings存储键值对。QSettings总是将反斜杠视为一个特殊字符，并且不提供用于读取或写入此类条目的API。不要在节或键名中使用斜线（“/”和“\”）；反斜杠字符用于分隔子键。在windows上，QSettings将“\”转换为“/”，使它们完全相同。因为反斜杠字符被QSettings用来分隔子键，所以无法读取或写入包含斜线或反斜杠的windows注册表项。如果需要，应该使用本机windows API。
EnvironmentVariable	"EnvironmentVariable" key value [persistent [system]]	Sets the environment variable key to value. If persistent is set to true, the variable is set persistently. This is currently only supported on Windows. If system is set to true, the persistent variable is set system-wide, not only for the current user. Note, if you set path to environment variable, use '\' as separator, for example: @Targetdir@\lib\system. 将环境变量key 设置为value。如果persistent设置为true，则变量将被持久设置。目前仅在Windows上支持此功能。如果system设置为true，则持久变量将在系统范围内设置，而不仅仅是针对当前用户。注意，如果将路径设置为环境变量，请使用“\”作为分隔符，例如：@Targetdir@\lib\system。
RegisterFileType	"RegisterFileType" extension command [description [contentType [icon]]].	Registers the file type with extension to be opened via command. Optionally, you can specify description, contentType, and icon. This is currently only supported on Windows. 注册要通过command打开的extension 为的文件类型。可以选择指定description、contentType和icon。目前仅在Windows上支持此功能。 Note: File type will be unregistered during uninstallation. If you want keep the type registered, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：卸载过程中将取消注册文件类型。如果要保持类型注册，可以通过将UNDOOPERATION和“”传递到参数列表末尾来覆盖UNDO。
ConsumeOutput	"ConsumeOutput" installerKeyName executablePath processArguments	Saves the output from running the executable located at executablePath with the arguments processArguments to the installer key specified by installerKeyName. Additional arguments can be passed. 将运行位于可执行文件路径的executablePath 的输出（参数为processArguments）保存到installerKeyName指定的安装程序密钥中。可以传递其他参数。
CreateLink	"CreateLink" linkPath targetPath	Creates a link in the location specified by linkPath that points to the location specified by targetPath. 在linkPath指定的位置创建指向targetPath指定位置的链接。
CreateLocalRepository	"CreateLocalRepository" binaryPath repoPath	Creates a local repository in the directory specified by repoPath. For offline installers, stores binary data in the directory specified by binaryPath. 在repoPath指定的目录中创建本地存储库。对于脱机安装程序，将二进制数据存储在binaryPath指定的目录中。 Note: The repository will be deleted during uninstallation. If you want keep the repository, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. 注意：卸载过程中将删除存储库。如果要保留存储库，可以通过将UNDOOPERATION和“”传递到参数列表末尾来覆盖UNDO。
FakeStopProcessForUpdate	"FakeStopProcessForUpdate" processlist	Matches running processes against the comma-separated entries in processlist during uninstallation. If matches are found, shows a messagebox asking the user to stop those processes before continuing. 在卸载过程中，将正在运行的进程与processlist 中以逗号分隔的条目进行匹配。如果找到匹配项，将显示一个消息框，要求用户在继续之前停止这些进程。
License	"License" licenses	Copies the license files specified by licenses to a subfolder called Licenses in the target directory. This operation is automatically added for packages declaring <Licenses> in their package description file. 将licenses 指定的许可证文件复制到目标目录中名为“licenses ”的子文件夹中。对于在包描述文件中声明<Licenses>的包，会自动添加此操作。
MinimumProgress	"MinimumProgress"	Increases the progress value by one. 将进度值增加1。
SelfRestart	"SelfRestart" core	Restarts the updater or package manager specified by core. 重新启动core指定的更新程序或包管理器。
Settings	"Settings" path method key value	Sets or removes the value of key in the settings file located at path, depending on the value of method: set, remove, add_array_value, and remove_array_value. Example: component.addOperation("Settings", "path=settings.ini", "method=add", "key=myKey", "value=myValue") 根据方法set、remove、add_array_value和remove_array_value的值，设置或删除位于路径的设置文件中的key 的value 。 示例：component.addOperation("Settings", "path=settings.ini", "method=add", "key=myKey", "value=myValue")

The Extract, License, and MinimumProgress operations are automatically added for matching components that do not overwrite the component::createOperations() method. See also component::autoCreateOperations.

​对于不覆盖 component::createOperations()方法的匹配组件，会自动添加Extract、License和MinimumProgress操作。另请参见component::autoCreateOperations。

If errors occur, you can test operations manually using the devtool. However, variables are not resolved, so you need to use absolute values.

如果发生错误，可以使用devtool手动测试操作。但是，变量不会被解析，因此需要使用绝对值。

For example, to test copying a file:

例如，要测试复制文件：

devtool operation <binary> DO,Copy,<source>,<target>

Execution Groups

执行组

The operations owned by a component belong to either of two groups: Unpack or Install. The Extract operations are performed as part of the Unpack group before all other operations and executed concurrently between all components that are going to be installed. The rest of the operations are performed in the Install group and executed sequentially for each component at a time.

组件所拥有的操作属于以下两组之一：Unpack 或Install。Extract 操作在所有其他操作之前作为Unpack 组的一部分执行，并在将要安装的所有组件之间同时执行。其余操作在Install组中执行，并一次对每个组件按顺序执行。

Custom operations can define their execution group by calling the setGroup() method in their constructor. For more information about custom operations, see Registering Custom Operations.

​自定义操作可以通过在构造函数中调用setGroup（）方法来定义其执行组。有关自定义操作的更多信息，请参阅注册自定义操作。

Component ScriptingTools

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