博客分类: 官方教程

返回目录索引
本文内容包含三部分内容：使用内置对话框、自定义内置对话框，以及本地化版本处理。
原文链接：

• Using Built-in WixUI Dialog Sets
• Customizing Built-in WixUI Dialog Sets
• Using Localized Versions of WixUI

使用内置WixUI对话框

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

• 原文：WixUI_Advanced
• 原文：WixUI_FeatureTree
• 原文：WixUI_InstallDir
• 原文：WixUI_Minimal

• 原文：WixUI_Mondo

• 译文：WiX Toolset入门——WixUI界面库参考

怎样为产品安装程序添加内置WixUI对话框

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

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

   <Product ...>
       <UIRef Id="WixUI_InstallDir" />
   </Product>
   

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

   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文件格式的许可文件。示例如下：

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

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

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变量中指定图片文件名称即可，类似于指定许可文件一样：

自定义ExitDlg窗体

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

关于在ExitDlg中显示勾选框的示例见：原文：How To: Run the Installed Application After Setup

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

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

可选文本有如下性能：

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

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

• 长字符串会自动换行显示

• 可选文本只在初始安装时显示，不会在修复模式或卸载时显示。

自定义内置对话框文本

所有WixUI内置对话框中的文本都可以在需要的时候重写。为此，您需要向WiX本地化(.wxl)文件中添加具有相同Id值的字符串来进行覆盖。你可以在WixUI_en-us.wxl中看到在WiX源码中WixUI字符串的Id值。

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

<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 Toolset入门——WixUI界面库参考。

内置对话框集合中的默认顺序是可以修改的。为此，你必须从相应对话框集合定义的WiX源码中拷贝<Fragment />内容到项目中。然后，你需要修改<Publish />元素来定义在你的安装过程中对话框的显示顺序。

例如，把许可协议对话框从WixUI_InstallDir对话框集合中移除，你可以进行如下设置：

1. 从WiX源码中拷贝WixUI_InstallDir.wxs文件里<Fragment>的所有内容到你的项目中。
2. 移除用于添加上一步下一步事件的<Publish />元素

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

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

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

   <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 />内容。然后，修改<Publish />元素来定义对话框序列显示。

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

1. 在你项目中的<UI />元素下定义SpecialDlg的外观。
2. 从WiX源码中拷贝WixUI_InstallDir.wxs文件里<Fragment>的所有内容到你的项目中。

3. 为SpecialDlg添加上一步下一步操作，即添加<Publish />元素定义，示例如下：

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

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

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

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

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

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

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

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

WixUI本地化处理

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

使用已翻译的UI字符串

WixUIExtension包含一系列的WiX本地化文件（.wxl）—— 为多种语言翻译了UI文本、错误提示以及进度提示字符串。要指定安装包的UI语言，可以在链接命令时传入语言参数，示例如下：

light -ext WixUIExtension -cultures:fr-FR Product.wixobj -out Product.msi

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

使用不同语言设置创建多个安装包

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

candle Product.wxs
light -ext WixUIExtension -cultures:en-us Product.wixobj -out Product_en-us.msi
light -ext WixUIExtension -cultures:fr-fr Product.wixobj -out Product_fr-fr.msi
light -ext WixUIExtension -cultures:de-de Product.wixobj -out Product_de-de.msi
light -ext WixUIExtension -cultures:it-it Product.wixobj -out Product_it-it.msi
light -ext WixUIExtension -cultures:ja-jp Product.wixobj -out Product_ja-jp.msi
light -ext WixUIExtension -cultures:pl-pl Product.wixobj -out Product_pl-pl.msi
light -ext WixUIExtension -cultures:ru-ru Product.wixobj -out Product_ru-ru.msi
light -ext WixUIExtension -cultures:es-es Product.wixobj -out Product_es-es.msi

使用已翻译的错误和进度提示文本

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

<UIRef Id="WixUI_ErrorProgressText" />

利用Visual Studio来处理以上步骤

内容为处理中文安装包

• 将WixUI_zh-CN.wxl文件添加到安装包项目里，如果要添加其他语言，将其他语言的wxl文件加入到项目中即可
• 重新生成安装包即可

注意：在此处：

• 如果你需要同时生成多个语言的安装时，Product.wxs中不可以出现中文，即公用的wxs文件中需要全部为英文；
• 但是如果你只需要一个中文的安装包，你可以在Product.wxs中使用中文，但需要注意的是，你需要把所有其他语言的wxl文件删除，以此避免出现CodePage错误问题，即语言匹配问题。

译：奇葩史

没有评论