警告

本节包含自动从C++转换为Python的代码片段，可能含有错误。

Qt帮助框架

在应用程序中集成文档

概述

Qt帮助系统包括生成和查看Qt帮助文件的工具。此外，它还提供程序访问帮助内容的类，以便能够将在线帮助集成到Qt应用程序中。

实际的帮助数据，即目录、索引关键字或HTML文档，包含在Qt压缩帮助文件中。因此，一个这样的帮助文件通常代表一份手册或文档集。由于大多数产品都更为全面，由多个工具组成，所以一本手册常常是不够的。相反，还需要更多的手册，它们应该能够同时访问。理想情况下，还应该能够将一本手册的某些感兴趣点引用到另一本手册中。因此，Qt帮助系统在帮助集合文件上操作，这些文件包括任意数量的压缩帮助文件。

然而，拥有集合文件来合并多个文档集可能会导致一些问题。例如，一个索引关键词可能在不同的文档集中被定义。因此，当只看到索引中的关键词并激活时，您无法确定预期的文档将被显示。因此，Qt帮助系统提供在特定属性后过滤帮助内容的可能性。但这要求，在生成压缩帮助文件之前，必须将属性分配给帮助内容。

如前所述，Qt压缩帮助文件包含所有数据，因此不再需要单独发送所有HTML文件。相反，只有压缩帮助文件，可选的，还有集合文件，需要分发。集合文件是可选的，因为任何现有的集合文件（例如较旧版本中）都可以使用。

因此，一般来说，与帮助系统交互的文件有四个，其中两个用于生成Qt帮助，两个用于分发。

名称	扩展名	简要描述
Qt帮助项目	.qhp	包含目录、索引和对实际文档文件 (*.html) 的引用。它还定义了文档的唯一命名空间。该文件被传递给帮助生成器，以创建压缩帮助文件。
Qt压缩帮助	.qch	包含在帮助项目文件中指定的所有信息，以及所有压缩文档文件。
Qt帮助集合项目	.qhcp	包含对应包含在帮助集合中的压缩帮助文件的引用的XML文件。该文件可以传递给帮助生成器，以创建帮助集合文件。
Qt帮助集合	.qhc	帮助集合文件，由 QHelpEngine 操作。它可以包含对任意数量的压缩帮助文件的引用以及额外的信息。

生成Qt帮助

为Qt帮助系统生成帮助文件假定HTML文档文件已经存在。

当 HTML 文档就绪后，需要创建一个扩展名为 .qhp 的 Qt 帮助项目 文件。在文件中指定所有相关信息后，需要通过以下方式编译：

qhelpgenerator doc.qhp -o doc.qch

文件 doc.qch 包含所有 HTML 文件以及目录和索引关键词的压缩版本。为了测试生成的文件是否正确，请打开 Qt 助手，并在“设置 > 文档”中安装该文件。

对于标准的 Qt 源构建，.qhp 文件将与 HTML 页面放置在同一目录中。

第一步是创建一个 Qt 帮助集合项目文件。由于 Qt 帮助集合主要存储对压缩帮助文件的引用，因此项目文件 mycollection.qhcp 看起来很简单。

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

要实际创建集合文件，请调用：

qhelpgenerator mycollection.qhcp -o mycollection.qhc

为了同时生成压缩帮助文件和集合文件，修改帮助集合项目文件，使其指示帮助生成器首先创建压缩帮助文件。

...
<docFiles>
    <generate>
        <file>
            <input>doc.qhp</input>
            <output>doc.qch</output>
        </file>
    </generate>
    <register>
        <file>doc.qch</file>
    </register>
</docFiles>
...

当然，可以在 generate 或 register 部分中指定多个文件，因此可以一次性生成和注册任意数量的压缩帮助文件。

QHelpEngine 允许将帮助内容直接嵌入到应用程序中。

除了在外部应用程序（如网页浏览器）中显示帮助外，还可以将在线帮助嵌入到应用程序中。然后可以通过 QHelpEngine 类检索内容，并以几乎任何形式显示。在 QTextBrowser 中显示帮助可能是最常见的方法，但将帮助嵌入到“这是什么”帮助中也是完全可以的。

从文件引擎检索帮助数据不需要很多代码。第一步是创建帮助引擎的一个实例。然后我们请求引擎为标识符分配的链接，在本例中为 MyDialog::ChangeButton。如果找到链接，即至少有一个帮助文档存在于此主题，我们通过调用 fileData() 获取实际的帮助内容，并将文档显示给用户。

helpEngine = QHelpEngineCore("mycollection.qhc")
...
# get all file references for the identifier
links =
    helpEngine.documentsForIdentifier("MyDialog.ChangeButton")
# If help is available for this keyword, get the help data
# of the first file reference.
if links.count():
    helpData = helpEngine.fileData(links.constBegin().url)
    # show the documentation to the user
    if not helpData.isEmpty():
        displayHelp(helpData)

有关如何使用 API 的更多信息，请参阅 QHelpEngine 类参考。