[译]:WiX Toolset入门——内置的WixUI界面使用配置

博客分类: 官方教程

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

原文链接:

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

使用内置WixUI对话框

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

变量名 描述 尺寸
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中显示勾选框的示例见: 原文: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源码中拷贝 <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中翻译了以下语言版本:

语言-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来为不同语言创建一系列不同安装语言的安装包,示例如下:

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错误问题,即语言匹配问题。

译: 奇葩史

我来评几句
登录后评论

已发表评论数()

相关站点

热门文章