WiX Toolset入门——内置的WixUI界面使用配置

admin

本文内容包含三部分内容：使用内置对话框、自定义内置对话框，以及本地化版本处理。

使用内置WixUI对话框
WixUI对话框库主要包含以下几种对话框集合，它们提供了我们常见的向导式设置的用户界面。

怎样为产品安装程序添加内置WixUI对话框
假设你已经有一个可用的安装程序，仅仅缺少安装用户界面，参照以下步骤为其添加内置的WixUI对话框：

1、添加UIRef元素到安装程序代码中，并将其Id设置为与上述对话框设置类型列表中的一个相同的名称。示例如下：

1. <Product ...>
   
2.     <UIRef Id="WixUI_InstallDir" />
   
3. </Product>

复制代码

2、在链接器（ light.exe ）中，使用 -ext 和 -cultures 设置来引用WixUIExtension，示例如下：

1. light -ext WixUIExtension -cultures:en-us Product.wixobj -out Product.msi

复制代码

注：如果你在Visual Studio中使用Wix，你可以通过添加引用的方式处理以上步骤。其步骤如下：
* 在Visual Studio中打开WiX项目 * 在解决方案管理器中右击项目下的 References ，然后选择 添加引用 * 在列表中选择 WixUIExtension.dll ，然后点击 添加 * 点击 确定 ，关闭添加引用对话框

提示
个人经验：如果仅仅按照上面步骤处理，在安装过程中会提示错误，错误代码为2819；

具体处理方案见： 关于使用WiXUI后遇到错误2819问题解决
内置的WixUI对话框配置亦是可以自定的——从UI界面图片到添加和删除 用户对话框。更多内容见下节。
自定义内置WixUI对话框

内置WixUI对话框自定义设置包括以下内容：
指定特定产品的使用许可协议文件
定制产品独有的安装UI界面
向ExitDlg对话框中添加可选的复选框和可选文本
自定义内置对话框中的显示文本
修改内置对话框集合的UI序列
向内置对话框集合中添加自定义对话框
指定许可文件

WixUIExtension.dll包含一个默认的使用许可协议。要指定自己产品的许可协议，则通过指定VixVariable内容来覆盖默认协议。要指定的内容包括将WixVariable的Id设置为WixUILicenseRtf，然后在Value属性中指定你自己的RTF文件格式的许可文件。示例如下：

1. <WixVariable Id="WixUILicenseRtf" Value="bobpl.rtf" />

复制代码

或者，你可以在使用 light 时通过 -d 参数指定变量：

1. light -ext WixUIExtension -cultures:en-us -dWixUILicenseRtf=bobpl.rtf Product.wixobj -out Product.msi

复制代码

指定的文件必须包含在目录中，light会查询此文件。

现有一个已知的问题：富文本控件在显示许可文件时，可能会显示空白，只有用户在控件内向下滚动后才能显示文本。此问题通常是由复杂的RTF内容导致（如在Microsoft Word保存生成的RTF文件）。如果在自己的安装界面中遇到此问题，如下的解决方案可以解决大多数的情况：

用写字板打开RTF文件，然后保存，与此去除复杂的RTF内容。保存之后，重新生成安装包。 —— 注：最好是另存为，如果单纯的保存，可能无法保证格式真正转化，本人使用文本转rtf时就纠结了好久。
使用非WixUI_Minimal集合的对话框。此问题通常是因为，在安装启动后的第一个界面为许可协议，而它使用WixUI_Minimal对话框集合。 —— 此处处理方式，在学到此处时，可能还不知道怎么处理，需要进一步学习
替换默认安装图片

WixUI对话框库中含有欢迎界面和完成界面的背景图片，以及其他界面顶部的横幅图片。你用你自己的图片替换以此推广自己产品的品牌。要替换默认图片，在WiX变量中指定图片文件名称即可，类似于指定许可文件一样：
[td]

变量名	描述	尺寸
WixUIBannerBmp	顶部横幅	493*58
WixUIDialogBmp	欢迎和完成窗体的背景图片	493*312
WixUIExclamationIco	WaitForCostingDlg界面中的感叹号图标	32*32
WixUIInfoIco	取消和错误提示框中的提示信息图标	32*32
WixUINewIco	BrowseDlg界面中的按钮图像	16*16
WixUIUpIco	BrowseDlg界面中的按钮图像	16*16

自定义ExitDlg窗体ExitDlg是一个内置窗体，它在安装成功结束后显示。ExitDlg窗体支持显示可选的自定义文本和一个可选的勾选框。

要在ExitDlg中显示可选文本，则为 WIXUI_EXITDIALOGOPTIONALTEXT 属性设置字符串值。示例如下：

1. <Property Id="WIXUI_EXITDIALOGOPTIONALTEXT" Value="Thank you for installing this product." />

复制代码

可选文本有如下性能：
可选文本按原样显示设置文本，不会解析方括号等包含的属性，如[ProductName]。如果你需要在可选文本里包括属性，你必须设置一个自定义操作来设置属性。示例如下：

1. <CustomAction Id="CA_Set_WIXUI_EXITDIALOGOPTIONALTEXT" Property="WIXUI_EXITDIALOGOPTIONALTEXT" Value="Thank you for installing [ProductName]."/>
   
2. <InstallUISequence>
   
3.     <Custom Action="CA_Set_WIXUI_EXITDIALOGOPTIONALTEXT" After="FindRelatedProducts">NOT Installed</Custom>
   
4. </InstallUISequence>

复制代码

长字符串会自动换行显示
可选文本只在初始安装时显示，不会在修复模式或卸载时显示。
自定义内置对话框文本
所有WixUI内置对话框中的文本都可以在需要的时候重写。为此，您需要向WiX本地化(.wxl)文件中添加具有相同Id值的字符串来进行覆盖。你可以在WixUI_en-us.wxl中看到在WiX源码中WixUI字符串的Id值。

例如，重新WelcomeDlg上的描述，你可以添加如下内容到项目的.wxl文件中：

1. <String Id="WelcomeDlgDescription">This is a custom welcome message. Click Next to continue or Cancel to exit.</String>

复制代码

修改内置对话框集合中的UI序列
每一个WixUI对话框集合中都预定义了对话框的显示顺序。关于WixUI对话框集合中包含哪些对话框见： 原文：WixUI Dialog Library Reference 。
内置对话框集合中的默认顺序是可以修改的。为此，你必须从相应对话框集合定义的WiX源码中拷贝 <Fragment /> 内容到项目中。然后，你需要修改 <ublish /> 元素来定义在你的安装过程中对话框的显示顺序。
例如，把许可协议对话框从WixUI_InstallDir对话框集合中移除，你可以进行如下设置：
从WiX源码中拷贝WixUI_InstallDir.wxs文件里 <Fragment> 的所有内容到你的项目中。
移除用于添加上一步下一步事件的 <ublish /> 元素
修改用于指定WelcomeDlg的下一步的 <ublish /> 元素 —— 将指向从LicenseAgreementDlg改为InstallDirDlg，示例如下：

1. <Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="InstallDirDlg">1</Publish>

复制代码

修改用于指定InstallDirDlg上一步的 <ublish /> 元素 —— 将指向从LicenseAgreementDlg改为WelcomeDlg，示例如下：

1. <Publish Dialog="InstallDirDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg">1</Publish>

复制代码

注：以上内容，需要将拷贝过来的UI元素的Id修改，然后让之前添加的UIRef的Id对应上，以此避免Id与系统原有WixUI_InstallDir里的Id冲突。示例如下：
首先将：
    <UI Id="WixUI_InstallDir">
    改为：
    <UI Id="WixUI_InstallDir_Custom">

    然后将Product元素下的：
    <UIRef Id="WixUI_InstallDir"/>
    改为：
    <UIRef Id="WixUI_InstallDir_Custom"/>
为内置对话框集合插入自定义对话框

你可以向内置对话框序列中添加自定义的对话框。为此，你需要为新的对话框定义一个新的 <UI /> 元素。然后，从WiX源码中拷贝你想自定义的对话框的所有 <Fragment /> 内容。然后，修改 <ublish /> 元素来定义对话框序列显示。

例如，需要在WelcomeDlg和LicenseAgreementDlg中插入一个名为SpecialDlg的对话框—— 此处使用WixUI_InstallDir对话框集合。我们需要进行如下步骤：

在你项目中的 <UI /> 元素下定义SpecialDlg的外观。
从WiX源码中拷贝WixUI_InstallDir.wxs文件里 <Fragment> 的所有内容到你的项目中。
为SpecialDlg添加上一步下一步操作，即添加 <ublish /> 元素定义，示例如下：

1. <Publish Dialog="SpecialDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg">1</Publish>
   
2. <Publish Dialog="SpecialDlg" Control="Next" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>

复制代码

修改用于指定WelcomeDlg的下一步的 <ublish /> 元素 —— 将指向从LicenseAgreementDlg改为SpecialDlg，示例如下：

1. <Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="SpecialDlg">1</Publish>

复制代码

修改用于指定LicenseAgreementDlg上一步的 <ublish /> 元素 —— 将指向从WelcomeDlg改为SpecialDlg，示例如下：

1. <Publish Dialog="LicenseAgreementDlg" Control="Back" Event="NewDialog" Value="SpecialDlg">1</Publish>

复制代码

关于在UI元素下添加SpecialDlg，由于官网未给出此操作示例，故下面添加一个简单的示例代码：

1. <Dialog Id="SpecialDlg" Width="300" Height="300" Title="aa" >
   
2.         <Control Id="aaaa" Type="Text" X="10" Y="10" Width="50" TabSkip="no" Height="50" Text="aaa"></Control>
   
3.         <Control Id="aaaaqq" Type="Text" X="110" Y="110" Width="50" TabSkip="no" Height="50" Text="aaaqq"></Control>
   
4.         <Control Id="Next" Type="PushButton" Text="xiayibu" X="200" Y="200" TabSkip="yes" Width="50" Height="50" ></Control>
   
5.         <Control Id="Back" Type="PushButton" Text="shangyibu" X="100" Y="200" TabSkip="yes" Width="50" Height="50" ></Control>
   
6.     </Dialog>

复制代码

析：其中Dialog相关内容见： 原文：Dialog Element 。另需要添加Next和Back两个按钮是因为我们在上面需要上一步下一步操作。

WixUI本地化处理
注：官网内容为利用命令行处理本地化，但在此文末会添加利用Visual Studio处理。

使用已翻译的UI字符串

1. 
   
2. WixUIExtension包含一系列的WiX本地化文件（.wxl）—— 为多种语言翻译了UI文本、错误提示以及进度提示字符串。要指定安装包的UI语言，可以在链接命令时传入语言参数，示例如下：
   
3. [code]light -ext WixUIExtension -cultures:fr-FR Product.wixobj -out Product.msi

复制代码

WixUIExtension中翻译了以下语言版本：

语言-Language	国家或地区-Location	语言代码-Culture code	WXL的对应文件名-WXL file
Arabic	Saudi Arabia	ar-SA	WixUI_ar-SA.wxl
Bulgarian	Bulgaria	bg-BG	WixUI_bg-BG.wxl
Catalan	Spain	ca-ES	WixUI_ca-ES.wxl
Croatian	Croatia	hr-HR	WixUI_hr-HR.wxl
Czech	Czech Republic	cs-CZ	WixUI_cs-CZ.wxl
Danish	Denmark	da-DK	WixUI_da-DK.wxl
Dutch	Netherlands	nl-NL	WixUI_nl-NL.wxl
English	United States	en-US	WixUI_en-US.wxl
Estonian	Estonia	et-EE	WixUI_et-EE.wxl
Finnish	Finland	fi-FI	WixUI_fi-FI.wxl
French	France	fr-FR	WixUI_fr-FR.wxl
German	Germany	de-DE	WixUI_de-DE.wxl
Greek	Greece	el-GR	WixUI_el-GR.wxl
Hebrew	Israel	he-IL	WixUI_he-IL.wxl
Hindi	India	hi-IN	WixUI_hi-IN.wxl
Hungarian	Hungary	hu-HU	WixUI_hu-HU.wxl
Italian	Italy	it-IT	WixUI_it-IT.wxl
Japanese	Japan	ja-JP	WixUI_ja-JP.wxl
Kazakh	Kazakhstan	kk-KZ	WixUI_kk-KZ.wxl
Korean	Korea	ko-KR	WixUI_ko-KR.wxl
Latvian	Latvia	lv-LV	WixUI_lv-LV.wxl
Lithuanian	Lithuania	lt-LT	WixUI_lt-LT.wxl
Norwegian (Bokmål)	Norway	nb-NO	WixUI_nb-NO.wxl
Polish	Poland	pl-PL	WixUI_pl-PL.wxl
Portuguese	Brazil	pt-BR	WixUI_pt-BR.wxl
Portuguese	Portugal	pt-PT	WixUI_pt-PT.wxl
Romanian	Romania	ro-RO	WixUI_ro-RO.wxl
Russian	Russia	ru-RU	WixUI_ru-RU.wxl
Serbian (Latin)	Serbia and Montenegro	sr-Latn-CS	WixUI_sr-Latn-CS.wxl
简体中文 -Simplified Chinese	China	zh-CN	WixUI_zh-CN.wxl
Slovak	Slovak Republic	sk-SK	WixUI_sk-SK.wxl
Slovenian	Solvenia	sl-SI	WixUI_sl_SI.wxl
Spanish	Spain	es-ES	WixUI_es-ES.wxl
Swedish	Sweden	sv-SE	WixUI_sv-SE.wxl
Thai	Thailand	th-TH	WixUI_th-TH.wxl
Traditional Chinese	Hong Kong SAR	zh-HK	WixUI_zh-HK.wxl
Traditional Chinese	Taiwan	zh-TW	WixUI_zh-TW.wxl
Turkish	Turkey	tr-TR	WixUI_tr-TR.wxl
Ukrainian	Ukraine	uk-UA	WixUI_uk-UA.wxl

使用不同语言设置创建多个安装包你可以通过调用一次cancle然后多次调用light来为不同语言创建一系列不同安装语言的安装包，示例如下：

1. candle Product.wxs
   
2. light -ext WixUIExtension -cultures:en-us Product.wixobj -out Product_en-us.msi
   
3. light -ext WixUIExtension -cultures:fr-fr Product.wixobj -out Product_fr-fr.msi
   
4. light -ext WixUIExtension -cultures:de-de Product.wixobj -out Product_de-de.msi
   
5. light -ext WixUIExtension -cultures:it-it Product.wixobj -out Product_it-it.msi
   
6. light -ext WixUIExtension -cultures:ja-jp Product.wixobj -out Product_ja-jp.msi
   
7. light -ext WixUIExtension -cultures:pl-pl Product.wixobj -out Product_pl-pl.msi
   
8. light -ext WixUIExtension -cultures:ru-ru Product.wixobj -out Product_ru-ru.msi
   
9. light -ext WixUIExtension -cultures:es-es Product.wixobj -out Product_es-es.msi

复制代码

使用已翻译的错误和进度提示文本默认情况下，WixUI不会包含任何翻译的错误或进度提示元素。你可以通过添加 WixUI_ErrorProgressText 元素来进行引用:

1. <UIRef Id="WixUI_ErrorProgressText" />

复制代码

利用Visual Studio来处理以上步骤
内容为处理中文安装包
将 WixUI_zh-CN.wxl 文件添加到安装包项目里，如果要添加其他语言，将其他语言的wxl文件加入到项目中即可重新生成安装包即可
注意：在此处：
* 如果你需要同时生成多个语言的安装时，Product.wxs中不可以出现中文，即公用的wxs文件中需要全部为英文； * 但是如果你只需要一个中文的安装包，你可以在Product.wxs中使用中文，但需要注意的是，你需要把所有其他语言的wxl文件删除，以此避免出现CodePage错误问题，即语言匹配问题。