自定义Qt Assistant

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

自定义帮助查看器的另一个要求是能够从提供帮助的应用程序接收操作或命令。当应用程序提供上下文相关帮助时，这一点尤为重要。以这种方式使用时，帮助查看器可能需要根据应用程序当前所处的状态更改其内容。这意味着应用程序必须将当前状态告知帮助查看器。更多信息，请参阅 Qt Assistant Remotely。

简单文本查看器示例使用本文档中描述的技术展示了如何将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 中手动完成，方法是选择 "编辑">"首选项">"文档"。但这种方法的缺点是，每个用户都必须手动操作才能访问新文档。

向已有的收藏文件添加文档的首选方法是使用Qt Assistant 的-register 命令行标志。使用该标志启动Qt Assistant 时，文档将被添加，而Qt Assistant 将立即退出，并显示注册是否成功的信息。

搜索索引只会索引您自定义的 *.html、*.htm 和 *.txt 文件。

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

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

注意： Qt Assistant 在 "内容"视图中显示的文档顺序与注册顺序相同。

更改的外观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"，则路径是相对于集合文件所在目录的。如果属性设置为 "默认 "或缺少该属性，则路径是 QDesktopServices::AppDataLocation 指定目录的相对路径。第一种形式适用于以移动方式使用的集合，例如随身携带的 U 盘。
`<enableFullTextSearchFallback>`	启用或禁用回退功能，以便在索引中找不到关键字时使用全文搜索。该功能可在远程控制Qt Assistant 时使用。要将其用于远程控制，请将标签值设置为`true` 。

除了这些Qt Assistant 专用标签外，还可以使用生成和注册文档的标签。更多信息，请参阅Qt Help Collection Files文档。

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

<?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> 指定的边栏窗口（dock widget）。如果窗口部件已经显示，再次发送此命令时，窗口部件将被激活，即它将被唤醒并获得输入焦点。<Widget> 的可能值是 "内容"、"索引"、"书签 "或 "搜索"。
`hide <Widget>`	隐藏 <Widget> 指定的 dock 部件。<Widget> 的可能值是 "内容"、"索引"、"书签 "或 "搜索"。
`setSource <Url>`	显示给定的 <Url>。URL 可以是绝对 URL，也可以是相对于当前显示页面的 URL。如果 URL 是绝对的，它必须是一个有效的 Qt Help 系统 URL。也就是说，必须以 "qthelp://"开头。
`activateKeyword <Keyword>`	将指定的 <Keyword> 插入索引 Dock widget 的行编辑器，并激活索引列表中的相应项目。如果该项目有多个相关链接，则会显示主题选择器。
`activateIdentifier <Id>`	显示给定 <Id> 的帮助内容。ID 在每个名称空间中都是唯一的，并且只有一个链接与之关联，因此不会弹出主题选择器。
`syncContents`	在内容窗口部件中选择与当前显示页面相对应的项目。
`setCurrentFilter <filter>`	选择指定的过滤器，并相应更新可视化显示。
`expandToc <Depth>`	将目录树扩展到给定的深度。如果深度为 0，目录树将完全折叠。如果深度为-1，目录树将完全展开。
`register <help file>`	将给定的 Qt 压缩帮助文件添加到集合中。
`unregister <help file>`	从集合中删除给定的 Qt 压缩帮助文件。

如果想在短时间内发送多条命令，建议只向进程的 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 许可证和归属

© 2025 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.

自定义Qt Assistant

Qt Help 收集文件

显示自定义文档

更改 的外观Qt Assistant

创建自定义帮助集合文件

远程使用Qt Assistant

更改的外观Qt Assistant