Qt Help 项目

Qt 帮助项目收集了生成压缩帮助文件所需的所有数据。除了实际的帮助数据（如目录、索引关键字和帮助文档）外，它还包含一些额外的信息，如用于标识帮助文件的命名空间。一个帮助项目代表一个文档集，例如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 帮助系统使用命名空间作为标识符，命名空间由强制性命名空间标签定义。在上面的例子中，命名空间是 "mycompany.com.myapplication.1.0"。

虚拟文件夹

每个文档集都有一个命名空间，这自然意味着文档集是完全分开的。从帮助引擎的角度来看，这是有益的。但是，从编写者的角度来看，他们往往希望将某些主题从一本手册交叉引用到另一本手册，而不必指定绝对链接。为了解决这个问题，帮助系统引入了虚拟文件夹的概念。

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

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

上例指定doc为虚拟文件夹。如果其他手册指定了相同的文件夹，例如小型辅助工具My Application，则只需编写doc.html#section1引用My Application手册中的第一节即可。

虚拟文件夹标记是强制性的，文件夹名称不得包含任何斜线 (/)。

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

关键字

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

关键字部分列出了该过滤器部分的所有关键字。关键字主要由名称和文件引用组成。如果使用了属性名称，则该处指定的关键字将出现在可见索引中。也就是说，可以通过QHelpIndexModel 类访问该关键字。如果使用id，关键字不会出现在索引中，只能通过QHelpEngineCore::documentsForIdentifier() 访问。name和id可以同时指定。

文件

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

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

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

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

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