自定义Qt Assistant

要将Qt Assistant 用作自定义帮助查看器，不仅需要能够显示自定义文档，同样重要的是能够自定义Qt Assistant 的外观，使其看起来像是应用程序专用的帮助查看器，而不是Qt Assistant 。这可以通过更改窗口标题或图标，以及一些应用程序专用的菜单文本和操作来实现。有关可自定义项的完整列表，请参阅《创建自定义帮助集合文件》。

自定义帮助查看器的另一项要求是能够接收其所提供帮助的应用程序发出的操作或命令。当应用程序提供上下文相关帮助时，这一点尤为重要。以这种方式使用时，帮助查看器可能需要根据应用程序的当前状态来更改其内容。这意味着应用程序必须将当前状态传达给帮助查看器。有关详细信息，请参阅《远程使用Qt Assistant 》。

“简单文本查看器”示例采用了本文档中描述的技术，演示了如何将Qt Assistant 用作应用程序的自定义帮助查看器。

警告：若要在 应用程序中分发Qt Assistant ，必须包含sqlite插件。有关如何在应用程序中包含插件的更多信息，请参阅部署文档。

Qt Help 集合文件

关于Qt Assistant ，首先需要了解的一点是：它将所有与外观相关的设置以及已安装文档列表存储在一个帮助集合文件中。这意味着，当使用不同的集合文件启动Qt Assistant 时，Qt Assistant 的外观可能会截然不同。这种设置的完全分离使得可以将Qt Assistant 作为自定义帮助查看器部署在一台机器上的多个应用程序中，而无需担心不同Qt Assistant 实例之间会相互干扰。

要将特定的帮助集合应用于Qt Assistant ，请在启动时通过命令行指定相应的集合文件。例如：

assistant -collectionFile mycollection.qhc

然而，将所有设置存储在一个集合文件中会引发一些问题。该集合文件通常安装在应用程序本身所在的目录中，或其某个子目录中。根据目录和操作系统的不同，用户可能没有修改该文件的权限，而当用户设置被存储时，这种情况就会发生。此外，有时甚至无法授予用户写入权限，例如当文件位于 CD-ROM 等只读介质上时。

即使能够授予所有人将设置存储在全局可用集合文件中的权限，当退出Qt Assistant 时，一个用户的设置仍会被另一个用户的设置覆盖。

为了解决这一难题，Qt Assistant 会创建用户专属的集合文件，这些文件基本上是从原始集合文件中复制而来的。用户专属的集合文件将保存在 QDesktopServices::AppDataLocation 返回的路径下的一个子目录中。该子目录（即此用户专用位置内的缓存目录）可在帮助集合项目文件中进行定义。例如：

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        ...
    </assistant>
</QHelpCollectionProject>

因此，在调用

assistant -collectionFile mycollection.qhc

Qt Assistant 实际上会使用该集合文件：

%QDesktopServices::AppDataLocation%/mycompany/myapplication/mycollection.qhc

绝无需使用用户专属集合文件来启动Qt Assistant 。相反，应始终使用应用程序随附的集合文件。此外，在向集合文件添加或移除文档时（参见下一节），也应始终使用常规集合文件。当已安装文档列表发生变化时，Qt Assistant 会自动处理用户集合文件的同步工作。

显示自定义文档

在Qt Assistant 能够显示文档之前，它必须知道在哪里可以找到实际的文档文件，这意味着它必须知道 Qt 压缩帮助文件 (*.qch) 的位置。如前所述，Qt Assistant 会将压缩帮助文件的引用存储在当前使用的集合文件中。因此，在创建新的集合文件时，您可以列出所有需要由Qt Assistant 显示的压缩帮助文件。

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    ...
    <docFiles>
        <register>
            <file>myapplication-manual.qch</file>
            <file>another-manual.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

有时，根据Qt Assistant 作为帮助查看器所服务的应用程序不同，随着时间的推移可能需要添加更多文档；例如，在安装更多应用程序组件或插件时。这可以通过在Qt Assistant 中选择“编辑”>“首选项 ”>“文档”来手动完成。但是，这种方法的缺点是每个用户都必须手动操作才能访问新文档。

向现有集合文件添加文档的首选方法是使用-register 的命令行参数Qt Assistant 。使用此参数启动Qt Assistant 时，文档将被添加，Qt Assistant 会立即退出，并显示一条消息，说明注册是否成功。

注意： Qt 压缩 Help 文件（.qch）应仅从可信来源加载。

搜索索引仅会对您的自定义 *.html、*.htm 和 *.txt 文件进行索引。

assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

可以将-quiet 标志传递给Qt Assistant ，以防止它写出状态消息。

注意： Qt Assistant 会在“目录”视图中按注册时的顺序显示文档。

更改xml-ph-0000@deepl.internal的外观Qt Assistant

通过在启动时传递不同的命令行选项，可以更改Qt Assistant 的外观。但是，这些命令行选项仅允许显示或隐藏特定的控件，例如“目录”或“索引”视图。其他自定义操作，例如更改应用程序标题或图标，或者禁用过滤功能，可以通过创建自定义帮助集合文件来实现。

创建自定义帮助集合文件

Qt Assistant 使用的帮助集合文件（*.qhc）是在对帮助集合项目文件（*.qhcp）运行qhelpgenerator 工具时生成的。该项目文件采用XML格式，并支持以下标签：

标签	简要说明
`<title>`	指定Qt Assistant 的窗口标题。
`<homePage>`	指定在Qt Assistant 主窗口中选择“主页”时要显示的页面。
`<startPage>`	指定使用帮助集合时初始显示的页面。
`<currentFilter>`	指定初始使用的过滤器。如果未指定此过滤器，则不会对文档进行过滤。如果仅安装了一套文档集，则此设置不会产生任何影响。
`<applicationIcon>`	描述将替代常规Qt Assistant 应用程序图标的图标。该图标以包含集合文件的目录为基准，以相对路径形式指定。
`<enableFilterFunctionality>`	启用或禁用用户可访问的筛选功能，从而防止用户在运行Qt Assistant 时更改任何筛选条件。这并不意味着内部筛选功能被完全禁用。若要禁用筛选功能，请将该值设置为`false` 。如果需要默认显示筛选工具栏，请将`visible` 属性设置为`true` 。
`<enableDocumentationManager>`	在“首选项”对话框中显示或隐藏“文档”选项卡。禁用“文档”选项卡可限制Qt Assistant 仅显示特定的文档集，或防止最终用户意外删除或安装文档。要隐藏“文档”选项卡，请将该标签值设置为`false` 。
`<enableAddressBar>`	启用或禁用地址栏功能。默认情况下该功能处于启用状态。若要禁用，请将标签值设置为`false` 。如果启用了地址栏功能，可通过将标签属性`visible` 设置为`true` 来显示地址栏。
`<aboutMenuText>, <text>`	列出“帮助”菜单中“关于”菜单项的本地化版本。例如，“关于应用程序”。文本在`text` 标签内指定。`language` 属性采用两位字母的语言名称。如果未指定语言属性，则该文本将作为默认文本使用。
`<aboutDialog>, <file>, <icon>`	指定可从“帮助”菜单打开的“关于”对话框中的文本。该文本取自`file` 标签中的文件。可以指定不同的文件或任何语言。由`icon` 标签定义的图标将应用于所有语言。
`<cacheDirectory>, <cacheDirectory base="collection">`	指定用于存储全文搜索所需索引文件以及集合文件副本的缓存目录。需要该副本是因为Qt Assistant 将所有设置都存储在集合文件中，因此该文件必须对用户可写。该目录以相对路径形式指定。如果`base` 属性设置为“collection”，则该路径相对于集合文件所在的目录；如果该属性设置为“default”或未指定，则该路径相对于 QDesktopServices::AppDataLocation 指定的目录。第一种形式适用于移动方式使用的集合，例如存储在 USB 闪存盘中随身携带的集合。
`<enableFullTextSearchFallback>`	启用或禁用当索引中找不到关键词时，回退并使用全文搜索的功能。此功能可在远程控制Qt Assistant 时使用。若要使其在远程控制中可用，请将标签值设置为`true` 。

除了这些Qt Assistant 专属标签外，还可以使用用于生成和注册文档的标签。有关更多信息，请参阅Qt Help 收藏集文件文档。

下面是一个使用所有可用标签的帮助集合文件示例：

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
        <currentFilter>myfilter</currentFilter>
        <applicationIcon>application.png</applicationIcon>
        <enableFilterFunctionality>false</enableFilterFunctionality>
        <enableDocumentationManager>false</enableDocumentationManager>
        <enableAddressBar visible="true">true</enableAddressBar>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        <aboutMenuText>
            <text>About My Application</text>
            <text language="de">Über meine Applikation...</text>
        </aboutMenuText>
        <aboutDialog>
            <file>about.txt</file>
            <file language="de">ueber.txt</file>
            <icon>about.png</icon>
        </aboutDialog>
    </assistant>
    <docFiles>
        <generate>
            <file>
                <input>myapplication-manual.qhp</input>
                <output>myapplication-manual.qch</output>
            </file>
        </generate>
        <register>
            <file>myapplication-manual.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

要创建二进制集合文件，请运行qhelpgenerator 工具：

qhelpgenerator mycollection.qhcp -o mycollection.qhc

要测试生成的集合文件，请按以下方式启动Qt Assistant ：

assistant -collectionFile mycollection.qhc

远程使用Qt Assistant

尽管帮助查看器是一个独立应用程序，但它通常会由其所提供帮助的应用程序启动。这种方法使应用程序能够在帮助查看器启动时立即请求显示特定的帮助内容。这种方法的另一个优势在于，应用程序可以与帮助查看器进程进行通信，从而根据应用程序的当前状态请求显示其他帮助内容。

因此，若要将Qt Assistant 作为您应用程序的自定义帮助查看器，只需创建一个 QProcess 并指定Qt Assistant 可执行文件的路径即可。为了让Qt Assistant 监听您的应用程序，请通过传递-enableRemoteControl 命令行选项来启用其远程控制功能。

以下示例展示了具体实现方法：

QProcess *process = new QProcess;
QStringList args;
args << QLatin1String("-collectionFile")
    << QLatin1String("mycollection.qhc")
    << QLatin1String("-enableRemoteControl");
process->start(QLatin1String("assistant"), args);
if (!process->waitForStarted())
    return;

一旦Qt Assistant 运行起来，您就可以通过该进程的标准输入（stdin）通道发送命令。下面的代码片段演示了如何指示Qt Assistant 显示文档中的特定页面。

QByteArray ba;
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

注意： 末尾的换行符是必需的，用于标记输入的结束。

可使用以下命令来控制Qt Assistant ：

命令	简要说明
`show <Widget>`	显示由 <Widget> 指定的侧边栏窗口（停靠控件）。如果该控件已显示且再次发送此命令，则该控件将被激活，即被提升至前台并获得输入焦点。 <Widget> 的有效值为“contents”、“index”、“bookmarks”或“search”。
`hide <Widget>`	隐藏由 <Widget> 指定的停靠小部件。<Widget> 的可能取值为 "contents"、"index"、"bookmarks" 和 "search"。
`setSource <Url>`	显示给定的 <URL>。该 URL 可以是绝对路径，也可以是相对于当前显示页面的相对路径。如果 URL 是绝对路径，则必须是有效的 Qt Help 系统 URL，即以 "qthelp://" 开头。
`activateKeyword <Keyword>`	将指定的 <Keyword> 插入索引停靠控件的行编辑框中，并激活索引列表中的相应条目。如果该条目关联了多个链接，则会显示主题选择器。
`activateIdentifier <Id>`	显示给定 <Id> 的帮助内容。每个命名空间中的 ID 都是唯一的，且仅与一个链接相关联，因此不会弹出主题选择器。
`syncContents`	在内容控件中选择与当前显示页面相对应的项目。
`setCurrentFilter <filter>`	选择指定的过滤器，并据此更新可视化显示。
`expandToc <Depth>`	将目录树展开至给定的深度。若深度为 0，则树将完全折叠；若深度为 -1，则树将完全展开。
`register <help file>`	将给定的 Qt 压缩 Help 文件添加到集合中。
`unregister <help file>`	从集合中移除给定的 Qt 压缩 Help 文件。

如果您想在短时间内发送多个命令，建议您仅向进程的标准输入（stdin）写入一行，而不是为每个命令分别写入一行。命令之间必须用分号分隔，如下例所示：

QByteArray ba;
ba.append("hide bookmarks;");
ba.append("hide index;");
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

使用Qt Assistant 许可与归属声明

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.