Qt Help 项目

一个 Qt Help 项目会收集生成压缩帮助文件所需的所有数据。除了实际的帮助数据（如目录、索引关键词和帮助文档）外，它还包含一些额外信息，例如用于标识帮助文件的命名空间。一个 Help 项目代表一组文档，例如qmake 手册。

Qt Help 项目文件格式

该文件格式基于 XML。为了更好地理解该格式，我们将讨论以下示例：

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
    <namespace>mycompany.com.myapplication.1.0</namespace>
    <virtualFolder>doc</virtualFolder>
    <customFilter name="My Application 1.0">
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
    </customFilter>
    <filterSection>
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
        <toc>
            <section title="My Application Manual" ref="index.html">
                <section title="Chapter 1" ref="doc.html#chapter1"/>
                <section title="Chapter 2" ref="doc.html#chapter2"/>
                <section title="Chapter 3" ref="doc.html#chapter3"/>
            </section>
        </toc>
        <keywords>
            <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
            <keyword name="bar" ref="doc.html#bar"/>
            <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
        </keywords>
        <files>
            <file>classic.css</file>
            <file>*.html</file>
        </files>
    </filterSection>
</QtHelpProject>

命名空间

为了使QHelpEngine 能够根据给定的链接检索正确的文档，每个文档集都必须具有一个唯一的标识符。唯一的标识符还使得帮助集合能够追踪文档集，而无需依赖其文件名。 Qt Help 使用命名空间作为标识符，该命名空间由必填的命名空间标签定义。在上例中，命名空间为“mycompany.com.myapplication.1.0”。

虚拟文件夹

为每个文档集设置命名空间，自然意味着这些文档集之间相互独立。从帮助引擎的角度来看，这是有益的。然而，从编写者的角度来看，通常希望在不同手册之间对某些主题进行交叉引用，而无需指定绝对链接。为了解决这个问题，帮助系统引入了“虚拟文件夹”的概念。

虚拟文件夹将成为压缩帮助文件中所有被引用的文件的根目录。当两个文档集共享同一个虚拟文件夹时，它们在定义相互指向的超链接时可以使用相对路径。如果某个文件同时包含在两个文档集中，则当前文档集中的文件优先于另一个文档集中的文件。

...
<virtualFolder>doc</virtualFolder>
...

上例将doc指定为虚拟文件夹。如果另一本手册也指定了相同的文件夹（例如用于一个名为“My Application”的小型辅助工具），只需写doc.html#section1即可引用“My Application”手册中的第一节。

虚拟文件夹标签是必填的，且文件夹名称中不得包含任何斜杠 (/)。

过滤器部分包含实际的文档内容。一个 Qt Help 项目文件可能包含多个过滤器部分。每个过滤器部分由目录、关键词和文件列表组成。理论上，所有部分都是可选的，但如果未指定任何内容，将导致文档集为空。

一个章节标签代表目录中的一个条目。章节可以任意程度地嵌套，但从用户的角度来看，嵌套层级不应超过四到五级。一个章节由其标题和引用定义。该引用与 Qt Help 帮助项目中的所有文件引用一样，都是相对于帮助项目文件本身而言的。

注意： 被引用的文件必须与帮助项目文件位于同一目录下（或其子目录中）。也不支持绝对文件路径。

关键词

...
<keywords>
   <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
   <keyword name="bar" ref="doc.html#bar"/>
   <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
</keywords>
...

“关键字”部分列出了该过滤器部分的所有关键字。一个关键字基本上由名称和文件引用组成。如果使用“attributename”，则该处指定的关键字将出现在可见索引中。也就是说，可以通过QHelpIndexModel 类访问它。如果使用“id”，则该关键字不会出现在索引中，仅可通过QHelpEngineCore::documentsForIdentifier()访问。可以同时指定“name”和“id”。

文件

...
<files>
    <file>classic.css</file>
    <file>*.html</file>
</files>
...

最后，必须列出实际的文档文件。请确保列出了显示帮助所需的所有文件。也就是说，样式表或类似文件也需要列出。这些文件，如同 Qt Help 帮助项目中的所有文件引用一样，都是相对于帮助项目文件本身而言的。如示例所示，文件（但不包括目录）也可以使用通配符指定为模式。所有列出的文件都将被压缩并写入 Qt 压缩帮助文件中。因此，最终一个单一的 Qt Help 文件中将包含所有文档文件以及内容和索引。

注意： 被引用的文件必须位于与帮助项目文件相同的目录中（或其子目录中）。也不支持绝对文件路径。

将文档集成到应用程序中示例

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