Qt Installer Framework 使用說明（三）

目錄

• 6、Qt Installer Framework 示例
• 7、參考 Reference
  • 配置文件 Configuration File
    • 配置文件元素的簡要說明 Summary of Configuration File Elements
  • 包目錄 Package Directory
    • 包目錄結構 Package Directory Structure
    • 元信息目錄 Meta Directory
      • 包信息文件語法 Package Information File Syntax
      • 軟件包信息文件元素簡介 Summary of Package Information File Elements
      • 組件依賴關系 Component Dependencies
    • 數據目錄 Data Directory
  • 控制腳本 Controller Scripting
    • 編寫控制腳本 Writing Control Scripts
    • 預定義安裝頁 Predefined Installer Pages
      • 介紹頁 Introduction Page
      • 許可協議頁 License Agreement Page
      • 目標目錄選擇頁 Target Directory Page
      • 組件選擇頁 Component Selection Page
      • 開始菜單目錄頁 Start Menu Directory Page
      • 准備安裝頁 Ready for Installation Page
      • 執行安裝頁 Perform Installation Page
      • 介紹頁 Finished Page
      • 介紹頁 Custom Pages
      • 消息框 Message Boxes
  • 組件腳本 Component Scripting
    • Construction
    • 安裝鈎子 Installer Hooks
    • 全局變量 Global Variables
    • 消息框 Message Boxes
    • 添加操作到組件 Adding Operations to Components
    • 注冊自定義組件 Registering Custom Operations
    • 預定義變量 Predefined Variables
  • 操作 Operations
    • 操作概要 Summary of Operations
  • 工具 Tools
  • 腳本API Scripting API
  • C++ API

6、Qt Installer Framework 示例

這些示例說明如何使用組件腳本來定制安裝程序。

示例	說明
更改安裝程序UI示例 Change Installer UI Example	使用組件腳本修改安裝程序UI
組件錯誤示例 Component Error Example	如果無法安裝組件，請使用組件腳本停止安裝
依賴性解決示例 Dependency Solving Example	使用組件的package.xml文件來定義組件之間的依賴性和自動依賴性
動態頁面安裝程序示例 Dynamic Page Installer Example	使用組件腳本和動態頁來構建安裝程序
修改提取安裝程序示例 Modify Extract Installer Example	在組件腳本中使用歸檔提取鈎子來修改目標路徑
在線安裝程序示例 Online Installer Example	使用repogen工具和配置文件設置在線安裝程序
打開ReadMe示例 Open ReadMe Example	使用組件腳本添加用於打開自述文件到最終安裝程序頁面的復選框
退出安裝程序示例 Quit Installer Example	使用組件腳本退出安裝程序
注冊文件擴展示例 Register File Extension Example	使用組件腳本在Windows上注冊文件擴展名
開始菜單快捷方式示例 Start Menu Shortcut Example	使用組件腳本將條目添加到Windows“開始”菜單
系統信息示例 System Information Example	在組件腳本中使用systemInfo API來檢查操作系統版本和位數
翻譯示例 Translation Example	使用翻譯本地化安裝程序頁面和許可證

7、參考 Reference

以下部分包含有關Qt Installer Framework的詳細信息：

配置文件 Configuration File

配置文件定制安裝程序的用戶界面和行為。 該文件通常名為config.xml並位於config目錄中。

最小配置文件由<Installer>根元素和<Name>和<Version>元素組成。 其他元素都是可選的，且無順序要求。

以下是典型的配置文件示例：

<?xml version="1.0"?>
<Installer>
    <Name>Some Application</Name>
    <Version>1.0.0</Version>
    <Title>Some Application Setup</Title>
    <Publisher>發行公司</Publisher>
    <ProductUrl>http://www.your-fantastic-company.com</ProductUrl>
    <InstallerWindowIcon>installericon</InstallerWindowIcon>
    <InstallerApplicationIcon>installericon</InstallerApplicationIcon>
    <Logo>logo.png</Logo>
    <Watermark>watermark.png</Watermark>
    <RunProgram>@TargetDir@/YourAppToRun</RunProgram>
    <RunProgramArguments>
        <Argument>Argument 1</Argument>
        <Argument>Argument 2</Argument>
    </RunProgramArguments>
    <RunProgramDescription>程序描述文本</RunProgramDescription>
    <StartMenuDir>Some Application Entry Dir</StartMenuDir>
    <MaintenanceToolName>SDKMaintenanceTool</MaintenanceToolName>
    <AllowNonAsciiCharacters>true</AllowNonAsciiCharacters>
    <Background>background.png</Background>

    <TargetDir>@HomeDir@/testinstall</TargetDir>
    <AdminTargetDir>@RootDir@/testinstall</AdminTargetDir>
    <RemoteRepositories>
        <Repository>
            <Url>http://www.your-repo-location/packages/</Url>
        </Repository>
    </RemoteRepositories>
</Installer>

配置文件元素的簡要說明 Summary of Configuration File Elements

下表總結了配置文件中的元素。

注意： 我們建議您將配置文件中引用的所有文件放在config目錄中。 但是，您也可以使用相對路徑，工具相對於config.xml文件的位置進行解析。

您可以使用預定義變量 (嵌入@字符) 作為元素的值。 有關詳細信息，請參閱預定義變量 Predefined Variables。

元素	是否必需	描述
Name	必需	正在安裝的產品名稱
Version	必需	安裝軟件的版本，格式要求:[0-9]+((\.|-)[0-9]+)*例如:1-1;1.2-2;3.4.7.
Title	可選	標題欄上顯示的安裝程序的名稱
Publisher	可選	軟件發行商(如Windows控制面板中所示)
ProductUrl	可選	指向包含您網站上產品信息的網頁的網址
Icon	可選	自定義安裝程序圖標的文件名。通過附加'.icns'(OS X)，'.ico'(Windows)或'.png'(Unix)后綴來查找實際文件。 已棄用 ，請改用<InstallerApplicationIcon>或<InstallerWindowIcon>
InstallerApplicationIcon	可選	自定義安裝程序圖標的文件名。 通過附加'.icns'(OS X)，'.ico'(Windows)后綴來查找實際文件。 在Unix上沒有此功能
InstallerWindowIcon	可選	安裝程序應用程序的自定義窗口圖標的文件名(PNG格式)
Logo	可選	用作QWizard::LogoPixmap的徽標的文件名
Watermark	可選	用作QWizard::WatermarkPixmap的水印的文件名
Banner	可選	用作QWizard::BannerPixmap(橫幅)的文件名(僅由ModernStyle使用)
Background	可選	用作QWizard::BackgroundPixmap的圖像的文件名(僅由MacStyle使用)
WizardStyle	可選	設置要使用的向導樣式 ("Modern"(現代), "Mac", "Aero"或"Classic"(經典))
WizardDefaultWidth	可選	像素單位的默認向導(Wizard)寬度，設置的橫幅圖像(Banner Image)將覆蓋在此
WizardDefaultHeight	可選	以像素為單位設置向導的默認高度,設置水印圖像將覆蓋在此
TitleColor	可選	設置標題和字幕的顏色(采用HTML顏色代碼，例如“＃88FF33”)
RunProgram	可選	如果用戶接受操作，則在安裝程序完成后執行命令。要提供應用程序的完整路徑
RunProgramArguments	可選	傳遞給<RunProgram>中指定的程序的參數。您可以添加多個<Argument>子元素，每個子元素為<RunProgram>指定一個參數
RunProgramDescription	可選	安裝后運行程序的復選框旁邊顯示的文本。如果<RunProgram>設置，但沒有提供說明，用戶界面將顯示運行程序<Name>替代
StartMenuDir	可選	Windows開始菜單中產品的默認程序組名稱
TargetDir	可選	安裝的默認目標目錄。在Linux上，這通常是用戶的主目錄(/home/username/)
AdminTargetDir	可選	具有管理員權限的安裝的默認目標目錄。僅在Linux上可用，通常不建議在管理員用戶的主目錄中安裝
RemoteRepositories	可選	遠程存儲庫列表。此元素可以包含多個<Repository>子元素，每個子元素包含指定用於訪問存儲庫的URL的<Url>子元素。有關更多信息，請參閱配置存儲庫
MaintenanceToolName	可選	生成的維護工具的文件名。默認為maintenancetool。將附加平台特定的可執行文件擴展名
MaintenanceToolIniFile	可選	用於生成維護工具配置的文件名。默認為MaintenanceToolName.ini
RemoveTargetDir	可選	如果卸載時不刪除目標目錄(TargetDir)，請設置為false
AllowNonAsciiCharacters	可選	如果安裝路徑可以包含 非ASCII字符 ，請設置為true
RepositorySettingsPageVisible	可選	設置為false來 隱藏 設置對話框中的 存儲庫設置頁面
AllowSpaceInPath	可選	如果安裝路徑 不能包含空格字符 ，請設置為false
DependsOnLocalInstallerBinary	可選	如果要禁止從外部資源(如網絡驅動器)安裝，請設置為true。 這可能有意義，例如，安裝程序非常大。該選項僅在Windows上使用
TargetConfigurationFile	可選	目標的配置文件名。默認是components.xml
Translations	可選	用於翻譯用戶界面的語言代碼列表。要添加多個語言變體，請指定多個<Translation>子元素，每個元素指定語言變體的名稱。該項可選。有關詳細信息，請參閱翻譯頁
UrlQueryString	可選	此字符串必須采用key = value形式，並且將附加到存檔下載請求。這可以用於向托管存儲庫的web服務器傳輸信息
ControlScript	可選	自定義安裝程序控制腳本的文件名。請參閱控制腳本
CreateLocalRepository	可選	如果要在安裝目錄中 創建本地存儲庫 ，請設置為true。此選項對在線安裝程序沒有影響。存儲庫將自動添加到默認存儲庫列表

包目錄 Package Directory

安裝程序包含嵌入到安裝程序或從遠程存儲庫加載的組件。在這兩種情況下，你需要提供組件使用的文件格式和結構，以便安裝程序讀取。

包目錄結構 Package Directory Structure

將所有組件放在同一根目錄中，這稱為包目錄。目錄名稱用作 域標識符 ，其標識所有組件。例如 com.vendor.root。

在根目錄中，創建稱data和meta子目錄。

一個包目錄可以如下所示：

-packages
    - com.vendor.root
        - data
        - meta
    - com.vendor.root.component1
        - data
        - meta
    - com.vendor.root.component1.subcomponent1
        - data
        - meta
    - com.vendor.root.component2
        - data
        - meta

元信息目錄 Meta Directory

meta目錄包含指定部署和安裝過程設置的文件。安裝程序不會提取文件(這些文件不會嵌入到安裝程序中)。該目錄必須至少包含程序 包信息文件 和您在程序包信息文件中所有 引用的文件 ，例如腳本，用戶界面文件和翻譯。

包信息文件語法 Package Information File Syntax

package.xml文件是關於組件信息的主要來源。 以下是package文件的示例：

<?xml version="1.0"?>
<Package>
    <DisplayName>QtGui</DisplayName>
    <Description>Qt gui libraries</Description>
    <Description xml:lang="de_de">Qt GUI Bibliotheken</Description>
    <Version>1.2.3</Version>
    <ReleaseDate>2009-04-23</ReleaseDate>
    <Name>com.vendor.root.component2</Name>
    <Dependencies>com.vendor.root.component1</Dependencies>
    <Virtual>false</Virtual>
    <Licenses>
        <License name="License Agreement" file="license.txt" />
    </Licenses>
    <Script>installscript.qs</Script>
    <UserInterfaces>
        <UserInterface>specialpage.ui</UserInterface>
        <UserInterface>errorpage.ui</UserInterface>
    </UserInterfaces>
    <Translations>
        <Translation>sv_se.qm</Translation>
        <Translation>de_de.qm</Translation>
    </Translations>
    <DownloadableArchives>component2.7z, component2a.7z</DownloadableArchives>
    <AutoDependOn>com.vendor.root.component3</AutoDependOn>
    <SortingPriority>123</SortingPriority>
    <UpdateText>This changed compared to the last release</UpdateText>
    <Default>false</Default>
    <ForcedInstallation>false</ForcedInstallation>
    <Essential>false</Essential>
    <Replaces>com.vendor.root.component2old</Replaces>
</Package>

軟件包信息文件元素簡介 Summary of Package Information File Elements

元素	是否必需	描述
DisplayName	必需	組件的可讀名稱
Description	必需	組件的可讀描述。 將描述的翻譯指定為附加說明標記的值，並將xml:lang屬性設置為正確的語言環境。如果找不到與語言環境匹配的翻譯文件，且存在未翻譯的版本，則使用未翻譯版本。否則，將不顯示該描述
Version	必需	組件的版本號格式為：[0-9]+((\.|-)[0-9]+)* 如1-1; 1.2-2; 3.4.7。 如果包需要顯示來自子進程的版本號，而不是它自己的版本號（由於子包的分組），可以指定屬性inheritVersionFrom，包含版本需要繼承的包名
ReleaseDate	必需	此組件版本發布的日期
Name	必需	此組件的域標識
Dependencies	可選	此組件依賴的組件的標識符列表(使用逗號分割)。 您可以指定版本號，以破折號(-)分隔。您可以使用比較運算符(=, >, <, >= or <=)為版本號添加前綴。 請記住，您必須使用字符引用＆lt;來避開左尖括號(使用&lt;來插入<，使用＆lt; =來插入<=)。更多相關信息，請參閱組件依賴關系
AutoDependOn	可選	此組件具有自動依賴性的組件的標識符列表(逗號分隔)。 當且僅當 滿足所有指定的依賴關系 時，才安裝組件。如果組件對其他組件有自動依賴性，則組件樹中組件旁的復選框將隱藏，並自動進行選擇。如果組件以前未安裝，則只有當選擇此列表中的所有組件進行安裝時，才會選擇安裝組件。如果組件已安裝，則當選擇此列表中的 至少一個組件 進行卸載時，將選擇卸載組件。有關更多信息，請參閱組件依賴關系
Virtual	可選	設置為true可從安裝程序中隱藏組件。 請注意，在根組件上設置此選項不起作用
SortingPriority	可選	組件在組件樹中的優先級。 樹從最高優先級到最低優先級排序，在頂部具有最高優先級
Licenses	可選	安裝用戶接受的許可協議列表。 要添加幾個許可證，請添加幾個<License>子元素，每個子元素指定許可證名稱和文件。 如果有針對此組件列出的翻譯，安裝程序還將查找翻譯的許可證。 它們需要具有與原始許可證文件相同的名稱，但是具有添加的區域設置標識符。 例如，如果許可證文件被稱為license.txt並且指定了德語翻譯，且安裝程序還包含一個license_de_de.txt文件（將在德語系統上安裝時顯示）
Script	可選	被加載的腳本文件名。 有關詳細信息，請參閱添加操作
UserInterfaces	可選	要加載的頁面列表。 要添加多個頁面，請添加多個<UserInterface>子元素，每個子元素指定頁面的文件名。有關詳細信息，請參閱添加頁面
Translations	可選	要加載的翻譯文件的列表。 要添加多個語言變體，請指定多個<Translation>子元素，每個子元素指定語言變體的文件名。有關詳細信息，請參閱翻譯頁
UpdateText	可選	如果這是一個更新組件，則將說明添加到組件描述中
Default	可選	可以設置為true、false、腳本名。 true：在安裝程序中預先選中組件。此操作僅適用於沒有可見子組件的組件。 腳本名：在運行時解析執行腳本，計算出布爾值(boolean)。將腳本文件名稱添加為此文件中<Script>元素的值。有關腳本示例，請參閱Selecting Default Contents
Essential	可選	將包標記為必須去強制重啟MaintenanceTool程序的。 如果有 可用的必要組件更新 ，則程序包管理器保持禁用狀態直到該組件更新。當運行updater時，新引入的必要組件將自動安裝
ForcedInstallation	可選	確定必須安裝的包。 最終用戶無法在安裝程序中取消選擇它
Replaces	可選	要替換的組件列表(逗號分隔)
DownloadableArchives	可選	列出數據文件(逗號分隔)，供在線安裝程序下載。 如果組件中有一些數據，並且package.xml和(或)腳本沒有DownloadableArchives值，repogen工具將自動注冊找到的數據
RequiresAdminRights	可選	如果程序包需要提升權限進行安裝，請設置為true

組件依賴關系 Component Dependencies

組件可以依賴於一個或多個 真實 或 虛擬 組件。 通過使用 組件標識符 和可選的 組件版本 來定義依賴性。 使用破折號-將版本號與標識符分隔開。

您可以使用比較運算符 (=, >, &lt; (<), >= 或 &lt;= (<=)) 為版本號添加前綴，以指示包的版本號與所需版本進行比較，並且必須 等於，大於，小於，大於等於 或 小於等於 依賴關系中指定的版本號。如果未給出比較運算符，它將默認為=。

數據目錄 Data Directory

數據(data)目錄包含安裝程序在安裝期間提取的內容。您必須將數據打包為7zip存檔(.7z)。 您可以使用隨Qt Installer Framework提供的archivegen工具或其它生成7zip存檔的工具。
譯注：實際上並不直接打包成7z壓縮包也可以，可以使用binarycreator工具直接創建安裝程序。

控制腳本 Controller Scripting

對於每個安裝程序，您可以指定一個控制腳本與安裝程序的用戶界面或功能進行某些交互。控制腳本可以對向導(Wizard)添加和刪除頁面，更改現有頁面，做額外的檢查，並通過模擬用戶點擊UI交互。 這允許例如 無人值守的安裝 。

腳本格式必須兼容QJSEngine。

本節介紹為實現此類控制腳本而調用的函數。 它還概述了安裝程序頁面和每個頁面上可用的小部件，例如按鈕，單選按鈕和行編輯。

編寫控制腳本 Writing Control Scripts

最小有效腳本需要至少包含一個構造函數，它可能如下所示：

function Controller()
{
}

以下示例介紹了一個更高級的腳本，它使用gui JavaScript全局對象的方法在介紹頁面上設置新的頁面標題和歡迎消息，並自動單擊 目標目錄選擇頁面 上的 下一步(Next) 按鈕：

function Controller()
{
}

// 介紹頁面回調函數
Controller.prototype.IntroductionPageCallback = function()
{
    var widget = gui.currentPageWidget(); // 獲取當前向導頁面 wizard page
    if (widget != null) {
        widget.title = "New title."; // 設置頁面標題
        widget.MessageLabel.setText("New Message."); // 設置歡迎信息 welcome text
    }
}

// 目標目錄選擇頁面回調函數
Controller.prototype.TargetDirectoryPageCallback = function()
{
    gui.clickButton(buttons.NextButton); // 自動單擊 Next 按鈕(下一步)
}

有關可以在控制腳本中使用的JavaScript全局對象的更多信息，請參閱Scripting API。

預定義安裝頁 Predefined Installer Pages

QInstaller JavaScript對象提供對以下預定義安裝程序頁面的訪問：

• Introduction 介紹
• TargetDirectory 目標目錄
• ComponentSelection 組件選擇
• LicenseCheck 許可證檢查
• StartMenuSelection 開始菜單選擇
• ReadyForInstallation 准備安裝
• PerformInstallation 執行安裝
• InstallationFinished 安裝完成

button JavaScript對象提供了一組可在安裝程序頁面上使用的按鈕。

以下部分描述可用於與安裝程序頁面和 每個頁面 上 可用的窗口小部件 交互的功能。(就是每個頁面上具有的控件)

介紹頁 Introduction Page

實現Controller.prototype.IntroductionPageCallback()函數與介紹頁上的小部件交互。

向導按鈕 Wizard Button:

• NextButton 下一步按鈕
• CanceButton 取消按鈕

Widgets	簡介
ErrorLabel	顯示錯誤消息
MessageLabel	顯示消息。默認情況下，它顯示Welcome to the <Name> Setup Wizard消息。(可能會是翻譯后的版本)
InformationLabel	顯示進度信息

Radio Buttons	簡介
PackageManagerRadioButton	維護工具運行時，顯示在頁面上的包管理器(Package manager)單選按鈕
UpdaterRadioButton	維護工具運行時，頁面上顯示更新程序(Update components)單選按鈕
UninstallerRadioButton	維護工具運行時，頁面上顯示的卸載程序(Remove all Components)單選按鈕。 默認選擇

Progress Bar	簡介
InformationProgressBar	獲取遠程包時顯示的進度條

Qt Core Feature	簡介
packageManagerCoreTypeChanged()	如果希望在維護工具類型更改時收到通知，請連接到此信號。 注意： 該信號僅在用戶已經啟動二進制文件時發出(就是啟動的maintenancetool)，且僅在單選按鈕之間切換時

示例代碼:

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

實現Controller.prototype.LicenseAgreementPageCallback()函數與許可協議頁面上的窗口小部件交互。

向導按鈕 Wizard Button:

• NextButton 下一步按鈕
• CanceButton 取消按鈕
• BackButton 后退按鈕

Widgets	簡介
LicenseListWidget	列出可用的許可證
LicenseTextBrowser	顯示所選許可證文件的內容
AcceptLicenseLabel	顯示接受許可證單選按鈕旁的文本
RejectLicenseLabel	顯示拒絕許可證單選按鈕旁的文本

Radio Buttons	簡介
AcceptLicenseRadioButton	接受許可協議單選按鈕
RejectLicenseRadioButton	拒絕許可協議單選按鈕。默認選擇

目標目錄選擇頁 Target Directory Page

實現Controller.prototype.TargetDirectoryPageCallback()函數與目標目錄選擇頁面上的窗口小部件交互。

向導按鈕 Wizard Button:

• NextButton 下一步按鈕
• CanceButton 取消按鈕
• BackButton 后退按鈕

Widgets	簡介
MessageLabel	顯示消息
TargetDirectoryLineEdit	顯示安裝的目標目錄路徑
WarningLabel	顯示警告

組件選擇頁 Component Selection Page

實現Controller.prototype.ComponentS actionPage Callback()函數與組件選擇頁面上的窗口小部件交互。

向導按鈕 Wizard Button:

• NextButton 下一步按鈕
• CanceButton 取消按鈕
• BackButton 后退按鈕

Methods	簡介
selectAll()	如果可以，選擇所有可用的軟件包
deselectAll()	如果可以，取消選擇所有可用的軟件包
selectDefault()	檢查可用軟件包狀態，重置為其初始狀態
selectComponent(id)	選擇帶有ID(string)的包
deselectComponent(id)	取消選擇帶有ID(string)的包

Push Buttons	簡介
SelectAllComponentsButton	如果可以，選擇所有可用的軟件包
DeselectAllComponentsButton	如果可以，取消選擇所有可用的軟件包
SelectDefaultComponentsButton	檢查可用軟件包狀態，重置為其初始狀態
ResetComponentsButton	重置為已安裝的組件

開始菜單目錄頁 Start Menu Directory Page

實現Controller.prototype.StartMenuDirectoryPageCallback()函數與准備安裝頁面上的小部件交互。

向導按鈕 Wizard Button:

• NextButton 下一步按鈕
• CanceButton 取消按鈕
• BackButton 后退按鈕

Widgets	簡介
StartMenuPathLineEdit	顯示創建程序快捷方式的目錄

准備安裝頁 Ready for Installation Page

實現Controller.prototype.StartMenuDirectoryPageCallback()函數與准備安裝頁面上的小部件交互。

向導按鈕 Wizard Button:

• NextButton 下一步按鈕
• CanceButton 取消按鈕
• BackButton 后退按鈕

Widgets	簡介
MessageLabel	顯示消息
TaskDetailsBrowser	顯示有關安裝的一些更詳細的信息

執行安裝頁 Perform Installation Page

實現Controller.prototype.PerformInstallationPageCallback()函數來與執行安裝頁面上的窗口小部件交互。

向導按鈕 Wizard Button:

• CommitButton 提交按鈕
• CancelButton 取消按鈕

介紹頁 Finished Page

實現Controller.prototype.Finished Page Callback()函數與安裝完成頁面上的小部件進行交互。

向導按鈕 Wizard Button:

• CommitButton 提交按鈕
• CancelButton 取消按鈕
• FinishButton 完成按鈕

Widgets	簡介
MessageLabel	顯示消息
RunItCheckBox	文本字段，通知用戶他們可以在安裝過程完成后啟動應用程序

介紹頁 Custom Pages

自定義頁面注冊為Dynamic${ObjectName}，其中${ObjectName}是在UI文件中設置的對象名。因此Dynamic${ObjectName}Callback()的調用，可以使用對象名(從UI文件)來尋址小部件。

示例代碼：

function Controller()
{
    // add page with widget \c SomePageWidget before the target directory page
    // 在目標目錄頁之前添加具有部件\ C SomePageWidget的頁
    installer.addWizardPage(component, "SomePageWidget", QInstaller.TargetDirectory)
}

Controller.prototype.DynamicSomePageWidgetCallback()
{
    var page = gui.pageWidgetByObjectName("DynamicSomePageWidget");
    page.myButton.click, //指向子對象或UI文件中的小部件 direct child of the UI file's widget
    page.someFancyWidget.subWidget.setText("foobar") // 嵌套小部件 nested widget
}

消息框 Message Boxes

在執行安裝程序應用程序時，例如，應用程序可能會(彈出)顯示一些關於發生的錯誤的消息框。 這在最終用戶的系統上運行應用程序是很棒的，但它可能會破壞自動測試套件。為了克服這個問題，Qt安裝程序框架顯示的所有消息框，都可以通過特定的標識符尋址。

Identifier標識符	可能的Answers	描述
OverwriteTargetDirectory	Yes, No	確認將已存在的目錄用作安裝的目標目錄
installationError	OK, Retry, Ignore	執行安裝時出現致命錯誤
installationErrorWithRetry	Retry, Ignore, Cancel	執行安裝時出錯。最終用戶可以選擇重試來再次安裝
AuthorizationError	Abort, OK	無法提升權限
OperationDoesNotExistError	Abort, Ignore	嘗試執行操作時發生錯誤，但操作並不存在
isAutoDependOnError	OK	調用軟件包腳本時出錯。 無法評估程序包是否具有對其他程序包的自動依賴性
isDefaultError	OK	調用軟件包腳本時出錯。 無法評估默認情況下是否安裝軟件包
DownloadError	Retry, Cancel	而從遠程倉庫下載的存檔散列(hash)時發生錯誤。最終用戶可以選擇重試來重試
archiveDownloadError	Retry, Cancel	從遠程存儲庫下載歸檔時出錯。最終用戶可以選擇重試來重試
WriteError	OK	寫入維護工具(maintenance tool)時出錯
ElevationError	OK	無法提升權限
unknown	OK	刪除某個包時發生未知錯誤
Error	OK	一般錯誤
stopProcessesForUpdates	Retry, Ignore, Cancel	更新軟件包時出錯。 某些正在運行的應用程序或進程需要退出才能執行更新。 最終用戶可以選擇重試，來在停止這些程序后重試
Installer_Needs_To_Be_Local_Error	OK	安裝程序二進制文件是從網絡位置啟動的，但不支持通過網絡安裝
TargetDirectoryInUse	No	安裝的目標目錄已包含安裝的文件
WrongTargetDirectory	OK	安裝的目標目錄是一個文件或符號鏈接。
AlreadyRunning	OK	另一個應用程序實例已在運行

示例代碼：

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

組件腳本 Component Scripting

對於每個組件，您可以准備一個腳本來指定由安裝程序執行的操作。 腳本格式必須兼容QJSEngine

Construction

腳本必須包含安裝程序在 加載腳本時 創建的Component對象。 因此，腳本必須至少包含Component()函數，該函數執行初始化，例如將頁面放在正確的位置或連接信號和槽。

以下代碼片段將ErrorPage（它是從errorpage.ui加載的用戶界面文件的類名）放在 准備安裝頁面 的前面，並將其完整性設置為false。

function Component()
{
    // Add a user interface file called ErrorPage, which should not be complete
    // 添加UI文件調用ErrorPage，這應該是不完整的
    installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation );
    component.userInterface( "ErrorPage" ).complete = false;
}

有關更多信息，請參閱installer::addWizardPage()和component::userInterface()的文檔

安裝鈎子 Installer Hooks

您可以在腳本中添加以下鈎子方法：

Method	描述
Component.prototype.retranslateUi	當安裝程序的語言更改時調用
Component.prototype.createOperations	參見component::createOperations()
Component.prototype.createOperationsForArchive	參見component::createOperationsForArchive()
Component.prototype.createOperationsForPath	S參見component::createOperationsForPath()

全局變量 Global Variables

安裝程序將以下符號放入腳本空間：

Symbol	描述
installer	引用組件的QInstaller
component	引用組件的Component

消息框 Message Boxes

您可以通過使用以下靜態成員從腳本中顯示QMessageBox：

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

為了方便起見，QMessageBox::StandardButton的值通過使用QMessageBox.Ok，QMessageBox.Open等提供。

添加操作到組件 Adding Operations to Components

例如，您可能需要在解壓縮內容后，在復制文件或修補文件內容時添加自定義操作。 您可以使用component::addOperation()從腳本中創建和添加更新操作到安裝。 如果需要運行需要管理權限的操作，請改用component::addElevatedOperation()。

操作需要在實際安裝步驟之前添加。 重寫component::createOperations()來注冊組件的自定義操作。

每個操作都有一個用於識別的唯一鍵，最多可以占用五個參數。在參數值中，可以使用在installer::setValue()中設置的變量。 有關詳細信息，請參閱預定義變量。

有關所有可用操作的摘要信息，請參閱操作。

注冊自定義組件 Registering Custom Operations

您可以通過繼承KDUpdater::UpdateOperation類在安裝程序中注冊自定義安裝操作。
下面的代碼顯示您必須實現的方法：

#include <KDUpdater/UpdateOperation>

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

  void backup()
  {
      // do whatever is needed to restore the state in undoOperation()
      // 恢復所有需要在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()
      // 恢復以前的狀態，保存在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
      // 自動添加操作的參數，並通過setValue設置所有
      QDomDocument doc = KDUpdater::UpdateOperation::toXml();

      // if you need any information to undo the operation you did,
      // add them to the doc here
      // 如果您需要任何信息來撤消您所做的操作，請在此處將其添加到doc

      return doc;
  }

  bool fromXml( const QDomDocument& doc )
  {
      // automatically loads the operation's arguments and everything set via setValue
      // 自動加載操作參數並通過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
      // 如果您需要任何信息來撤消您所做的操作，請在此處將其添加到doc

      return true;
  }
};

最后，需要注冊您的自定義操作類，如下所示：

#include <KDupdater/UpdateOperationFactory>

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

現在，您可以用與預定義操作相同的方式在安裝程序中使用您自定義的操作。

預定義變量 Predefined Variables

您可以在腳本中使用以下預定義變量，以便直接訪問：

Symbol	描述
ProductName	要安裝的產品的名稱，在config.xml中定義的
ProductVersion	要安裝的產品的版本號，在config.xml中所定義
Title	安裝程序的標題，在config.xml中定義
Publisher	安裝程序的發布者，如config.xml中所定義
Url	產品URL，如config.xml中所定義
StartMenuDir	開始菜單組，如config.xml中所定義。 僅在Windows上可用
TargetDir	目標安裝目錄，由用戶選擇
DesktopDir	用戶桌面目錄名(路徑)。 僅在Windows上可用
os	當前平台:"X11","Win"或"Mac"。 不建議使用此變量：請改用systemInfo
RootDir	文件系統根目錄
HomeDir	當前用戶的home目錄
ApplicationsDir	應用程序目錄。 例如,Windows上的C:\Program Files,Linux上/opt以及OS X上/Applications
InstallerDirPath	包含安裝程序可執行文件的目錄
InstallerFilePath	安裝程序可執行文件的文件路徑
UserStartMenuProgramsPath	包含在(當前)用戶的開始菜單中的項目文件夾的路徑。 例如：C:\Users\USERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs。僅在Windows上可用
AllUsersStartMenuProgramsPath	包含在所有用戶的開始菜單中的項目文件夾的路徑。 例如：C:\ProgramData\Microsoft\Windows\Start Menu\Programs。僅在Windows上可用

變量可以通過調用installer::value(string key, string defaultValue = "")來解析。如果嵌入在'@'中，它們也可以作為安裝操作的參數傳遞字符串的一部分：

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

操作 Operations

操作由組件和控制器腳本提供並由安裝程序執行。

注意：操作是線性執行的。

在內部，每個操作具有包含用於安裝程序的指令的DO步驟和包含用於卸載程序的指令的UNDO步驟。

操作概要 Summary of Operations

下表總結了可用的操作及其語法。

Operation	語法	用法
Copy	"Copy" source target	從source復制一個文件到target
Move	"Move" source target	從source移動一個文件到target
SimpleMoveFile	"SimpleMoveFile" source target	從source移動一個文件到target
Delete	"Delete" filename	刪除filename.指定的文件
Mkdir	"Mkdir" path	創建path目錄
Rmdir	"Rmdir" path	刪除path目錄
CopyDirectory	"CopyDirectory" sourcePath targetPath	復制sourcePath目錄到targetPath
AppendFile	"AppendFile" filename text	將text追加到filename指定的文件。text被視為ASCII文本
PrependFile	"PrependFile" filename text	將text添加到filename指定的文件。text被視為ASCII文本
Replace	"Replace" file search replace	打開文件去查找search字符串，並替換為replace字符串
LineReplace	"LineReplace" file search replace	打開文件以查找以search字符串開頭的行，並用replace字符串替換它。Lines are trimmed before the search.
Execute	"Execute" [{exitcodes}] command [parameter1 [parameter... [parameter10]]]	執行命令指定的命令。 最多可以傳遞10個參數。 如果這還不夠，可以使用JavaScript字符串數組。 可選，您可以在大括號{}中傳遞以逗號分隔的退出代碼列表作為第一個參數，以指定成功執行的退出代碼。 默認為{0}。 其它可選的命名參數是："workingdirectory=<your_working_dir>"; "errormessage=<your_custom_errormessage>" 此外，一個特殊的參數UNDOEXECUTE將操作的DO步驟與UNDO步驟分開。 示例:component.addOperation("Execute", "touch", "test.txt", "UNDOEXECUTE", "rm", "test.txt")
CreateShortcut	"CreateShortcut" filename linkname [arguments]	為filename指定的文件創建一個名為linkname的快捷方式。 在Windows上，將創建一個可帶參數的 .lik 文件。 在Unix上，將創建一個符號鏈接
CreateDesktopEntry	"CreateDesktopEntry" filename "key=value[ key2=value2[ key3=value3]]]"	創建一個.desktop初始化文件，如freedesktop.org指定的。 如果filename是絕對路徑，則桌面條目存儲在那里。 否則，它存儲在$XDG_DATA_DIRS/applications或$XDG_DATA_HOME/applications中指定的位置，包括由freedesktop.org定義的兩者的默認路徑。 鍵值對將寫入文件。 該文件設置為使用UTF-8編碼
InstallIcons	"InstallIcons" directory [Vendorprefix]	將目錄的內容安裝到由freedesktop.org指定的位置。 也就是$XDG_DATA_DIRS/icons，/usr/share/icons或$HOME/.icons。 文件將從其初始位置刪除。請確保在從歸檔中提取文件的操作之后添加此操作。 如果您提供Vendorprefix，它會替換所有字符，直到遇到 帶有此前綴 的圖標文件名中的第一個破折號-
Extract	"Extract" archive targetdirectory	提前archive內容到targetdirectory
GlobalConfig	"GlobalConfig" company application key value 或 "GlobalConfig" scope company application key value 或 "GlobalConfig" filename key value	在配置文件中存儲鍵的值。 配置文件由文件名(使用QSettings::NativeFormat，可能是Windows注冊表)或應用程序和公司名稱指定。將范圍設置為SystemScope以在系統范圍中創建條目。 注意： 該操作當前使用QSettings來存儲鍵值對。QSettings始終將反斜杠視為特殊字符，並且不提供用於讀取或寫入此類條目的API。 不要在段落或鍵名稱中使用斜杠（/和''）; 反斜杠字符用於分隔子鍵。 在Windows中，''被QSettings轉換為/，這使它們相同。 因為QSettings使用反斜杠字符來分隔子鍵，所以 無法讀取或寫入包含斜杠或反斜杠的Windows注冊表項 。 如果需要，您應該使用本機Windows API。
EnvironmentVariable	"EnvironmentVariable" key value [persistent [system]]	設置環境變量key為value 如果persistent設置為true，那么將永久設置該變量。目前僅支持Windows。 如果system設置為true，則該變量設置在系統范圍內有效，而不是僅對當前用戶
RegisterFileType	"RegisterFileType" extension command [description [contentType [icon]]]	注冊要通過命令打開的擴展名的文件類型。 可選，你可以指定描述(description)、內容類型(contentType)和圖標(icon)。當前僅支持Windows
ConsumeOutput	"ConsumeOutput" installerKeyName executablePath processArguments	保存運行帶有參數processArguments的executablePath的可執行文件的輸出到installerKeyName指定的安裝程序鍵。 可以傳遞其他參數
CreateLink	"CreateLink" linkPath targetPath	創建從linkPath指定的位置到由targetPath指定的位置的鏈接
CreateLocalRepository	"CreateLocalRepository" binaryPath repoPath	創建一個本地存儲庫在repoPath指定的目錄。 對於離線安裝程序，將二進制數據存儲在binaryPath指定的目錄
FakeStopProcessForUpdate	"FakeStopProcessForUpdate" processlist	在卸載期間匹配運行進程與processlist中的條目(逗號分隔)。 如果找到匹配，則顯示一個消息框，要求用戶在繼續之前停止這些進程
License	"License" licenses	將licenses指定的許可證文件復制到目標目錄中名為Licenses的子文件夾。 對於在包描述文件中聲明 的包，將自動添加此操作
MinimumProgress	"MinimumProgress"	將進度值增加1
SelfRestart	"SelfRestart" core	重新啟動由core指定的updater或軟件包管理器
Settings	"Settings" path method key aValue	根據method的值：set、remove、add_array_value和remove_array_value，來設置或刪除位於path的settings文件或注冊表中key的值aValue

對於匹配的組建，Extract、License和MinimumProgress操作是自動添加非重寫的component::createOperations()方法。另請參見component::autoCreateOperations

如果發生錯誤，您可以使用devtool手動測試操作。 但是，變量不會解析，因此您需要使用絕對值。

例如，要測試復制文件：

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

工具 Tools

腳本API Scripting API

C++ API

Known Issues