牛牛安装包界面控件使用说明

Question

本说明文档旨在对 nsNiuniuSkin.dll 控件的使用进行说明，指导调用者顺利的将牛捉安装包界面控件控件集成进安装包中，使第三方产品也能拥有完美的安装包的 UI 体验功能。

官方网址： http://www.ggniu.cn/

牛牛安装包界面控件是一个可集成于 NSIS 的插件，采用 Duilib 开发，在使用时，安装包制作者只需要做如下两件事情：

• 通过配置 Duilib 的资源，设计好界面显示的元素
• 在 NSIS 的脚本中，通过 NSIS 脚本调用 nsNiuniuSkin.dll 的相关接口，集成 UI 及安装包的业务功能

在控件的资源中，采用的是通过 TAB 控件来实现不同阶段的安装界面，比如：选择路径、许可协议、安装进度、完成、卸载等，在实际使用中，通过 NSIS 脚本来设置当前需要显示的 TAB 页，即可完美的呈现出需要的界面 UI 了。

在我们的示例中，提供了两份安装的界面如下：

注意，最新版本的控件已经将可用的 NSIS 及 7z 的相关文件包含在示例包中，可以通过一键打包批处理脚本进行打包了，具体如下：

1. 将要打包的文件复制到 FilesToInstall 目录下，可以包含文件及若干层的目录
2. 修改相关项目下的 skin 目录下的资源文件及 xml 脚本来配置 UI
3. 添加相关（或者在我原来的示例上修改，这样更快）的 NSIS 脚本文件，并与 UI 相匹配
4. 指定好相关的 ICO、licence 等信息
5. 执行 build.bat 脚本，一键打包，build 脚本会做三件事：将 FilesToInstall 目录下的文件打包成 app.7z；将 skin 目录下的文件打包成 skin.zip；调用 nsis 编译程序，编译 nsi 文件，输出安装包。

以上描述的 build 脚本为全自动执行，可以轻松集成进您现有的软件发布流程中，实现自动化打包发布。

牛牛安装包界面控件包含的接口较多，以下逐一进行介绍[以下接口调用及参数说明按在 NSIS 脚本中的调用示例来说明]：

1. 接口初始化接口

InitSkinPage

此接口函数用于初始化 nsNiuniuSkin.dll 控件的配置信息.

调用示例：

nsNiuniuSkin::InitSkinPage "$PLUGINSDIR\" "${INSTALL_LICENCE_FILENAME}"

参数说明：

参数序号	参数类型	参数说明	备注
1	字符串	用于指定 NSIS 安装包的插件释放路径	此路径的指定非常重要，在脚本中指定的插件以及 UI 资源包将会释放至此目录下，只有正确指定后，界面控件才能调用资源显示窗口
2	字符串	许可协议的文件名	这是一个 txt 文档，在界面控件加载时，将会加载此文件来显示许可协议

2. 重新设置许可协议的文件名

nsNiuniuSkin::ResetLicenseFile $hInstallDlg "newlicensename.rtf"

设置后，许可协议显示控件将会重新加载许可协议文件，这个比较适合用于多语言版本的不同许可协议加载显示。

3. 设置安装包标题

SetWindowTile

此接口函数用于指定安装包的标题。

调用示例：

nsNiuniuSkin::SetWindowTile $hInstallDlg "${PRODUCT_NAME}安装程序"

参数说明：

参数序号	参数类型	参数说明	备注
1	整型	用于指定要设置标题的窗口句柄	调用 init 时返回 （可传递子窗口弹窗口的句柄）
2	字符串	用于指定安装包的标题

4. 设置当前显示的 TAB 页

nsNiuniuSkin::ShowPageItem $hInstallDlg "wizardTab" ${INSTALL_PAGE_CONFIG}

参数序号	参数类型	参数说明	备注
1	整型	用于指定要设置标题的窗口句柄	调用 init 时返回 （可传递子窗口弹窗口的句柄）
2	字符串	指定的 TAB 控件的 name
3	int	需要显示的 tab 页序号	以 0 为初始值

5. 路径选择相关接口

4.1 通知接口来浏览安装路径

nsNiuniuSkin::SelectInstallDir
Pop $0

通知界面控件来浏览安装路径，并且将路径获取到变量中。再调用此接口后，应该再调用 SetControlAttribute 接口来将安装的路径设置到控件界面上。

4.2 通知接口来浏览安装路径扩展接口

nsNiuniuSkin::SelectInstallDirEx $hInstallDlg "请选择安装路径"
Pop $0

此接口是 SelectInstallDir 的扩展接口，在 SelectInstallDir 的基础上，支持设置文件选择框的标题。

6. 显示界面控件

nsNiuniuSkin::ShowPage 0

当界面绑定事件完成后，通过此接口来调用显示控件，此接口将会阻塞运行。

参数序号	参数类型	参数说明	备注
1	整型	用于指定显示前要回调的 NSIS 函数	如果为 0，则表示不回调

7. 弹出提示框接口

1) 以下代码用于初始化子窗口弹窗，同时返回其句柄：

nsNiuniuSkin::InitSkinSubPage "msgBox.xml" "btnOK" "btnCancel,btnClose"
pop $hInstallSubDlg

参数序号	参数类型	参数说明	备注
1	字符串	指定弹窗要用到的 UI 配置 xml 文件
2	字符串	指定点击后弹窗退出时返回 IDOK 的按钮 ID 号	如果使用 BindCallBack 绑定了此按钮回调的 NSIS 函数，则此设置失效
3	字符串	指定点击后弹窗退出时返回 IDCANCEL 的按钮 ID 号	如果使用 BindCallBack 绑定了此按钮回调的 NSIS 函数，则此设置失效

2) 以下代码用于根据弹窗窗口的句柄设置其 UI 控件的属性，控制显示变化：

nsNiuniuSkin::SetControlAttribute $hInstallSubDlg "lblTitle" "text" "提示"

3) 以下代码将弹窗显示出来：

nsNiuniuSkin::ShowSkinSubPage 0

参数说明：

参数序号	参数类型	参数说明	备注
1	整型	指定显示弹窗前要回调的 NSIS 函数地址	如果为 0 表示不回调；

8. 指定界面上指定控件的属性

nsNiuniuSkin::SetControlAttribute $hInstallDlg "btnClose" "enabled" "false"
nsNiuniuSkin::SetControlAttribute $hInstallDlg "lblInstalling" "text" "正在卸载..."

此接口用于指定界面的指定元素的指定属性，比如：是否可用、是否可见、是否选中、文字、背景图等等

参数说明：

参数序号	参数类型	参数说明	备注
1	整型	用于指定要设置标题的窗口句柄	调用 init 时返回 （可传递子窗口弹窗口的句柄）
2	字符串	控件的 name
3	字符串	控件的属性名
4	字符串	控件的属性值

注：可以通过此接口设置所有的通用属性；一般可以利用此接口来设置指定控件的文本、是否可用、是否可见、位置、大小 、背景图、文本颜色等；比如可以用于设置复选框是否选中等等。

通用的属性列表项可以参照下图：

设置示例如下：

9. 获取控件的通用属性

nsNiuniuSkin::GetControlAttribute $hInstallDlg "editDir" "text"
Pop $2

此接口用于获取界面的指定元素的指定属性，比如：是否可用、是否可见，文本等等

参数说明：

参数序号	参数类型	参数说明	备注
1	整型	用于指定要设置标题的窗口句柄	调用 init 时返回 （可传递子窗口弹窗口的句柄）
2	字符串	控件的 name
3	字符串	控件的属性名

注：

通用的属性列表项可以参照下图：

10. 绑定 UI 上控件的相关事件

GetFunctionAddress $0 OnExitDUISetup
nsNiuniuSkin::BindCallBack $hInstallDlg "btnClose" $0

此接口用于绑定一个按钮点击的回调函数或一个 RichEdit 控件的文字变化时的回调函数。

参数说明：

参数序号	参数类型	参数说明	备注
1	整型	用于指定要设置标题的窗口句柄	调用 init 时返回 （可传递子窗口弹窗口的句柄）
2	字符串	UI 界面中按钮或 richedit 控件的 name
3	LONG	要绑定的 NSIS 函数的地址	当指定名称的按钮被点击或者指定的 richedit 的内容变化时，绑定的函数将会被触发

注：

1). 当绑定的控件是一个 RichEdit 控件时，其中的文本内容变化时就会触发绑定的函数；可以通过绑定路径的控件，同时在绑定的函数中获取路径，做否合法的判断。

2). 为了能够将通过 Ctrl+F4 关闭窗口，以及通过在任务栏关闭窗口的事件通知到 NSIS 中，此处需要绑定一个特殊的名称，这个特殊的名称是：syscommandclose，如下：

11. 结束安装

nsNiuniuSkin::ExitDUISetup

此接口被调用时，将会退出安装进程

12. 字符串处理辅助接口

nsNiuniuSkin::StringHelper "c:\test\test\" "\" "" "trimright"; 如果源字符串的最后一个字符是\，则将其去掉
pop $0
nsNiuniuSkin::StringHelper "c:\AAA\dst" "AAA" "bbb" "replace" ;将源码中的 AAA 替换成 bbb
pop $0
nsNiuniuSkin::StringHelper "c:\AAA\dst" "\" "" " getrightbychar " ;将源码中的以\分隔的最后一段返回，此例中返回 dst
pop $0

这是一个为了简化在 NSIS 脚本中的字符串处理而提供的辅助函数，有需要者可以使用。

参数序号	参数类型	参数说明	备注
1	字符串	等待处理的字符串
2	字符串	指定在源码处理时，需要用来进行辅助查询的参数值
3	字符串	要被替换成的目标字符串	仅当指令为 replace 时有效
4	字符串	用于指定要对字符串处理的操作类型	replace： 在源串中将第二个参数的值替换成第三个参数的值，再返回 trimright： 将源串中的最后一个字符去掉（如果等于第二个参数） getrightbychar: 从源串中，取根据第二个参数分割的最后一段值

13. 其他信息

具体的 NSIS 脚本及 DUILIB 的配置文件可以参看 DEMO，有如下几个注意事项：

1). DUILIB 资源必需打包成 zip 压缩包，且名称必需是 skin.zip

2). 在 NSIS 脚本中，安装与卸载界面中按如下方式指定：

此处将插件释放目录指定为 duilib 资源包及许可协议文件的释放路径。

3). 在实际的安装过程中，为了让进度信息尽可能准确，采用的是 7z 解压的方式

这就要求在制作安装包之前，需要将要安装的文件打包成一个 7z 的压缩包，再在 NSIS 中指定安装：

在 NSIS 中，有相关的 7z 插件来解压，这里需要在线程中调用，以免界面卡住：

4). 目前提供的示例仅包含了常见的与 UI 界面相关的 NSIS 脚本；需要进一步的处理特定的注册表写入、文件备份等操作，需要自行另外再写 NSIS 脚本。

5). 界面的安装过程中的图片支持轮播，并且可以设置间隔时间，在 XML 中的写法如下：