嵌入外部代码

以下命令可让您从外部文件中嵌入代码片段。您可以让 QDoc 包含文件的全部内容，也可以只引用文件中的特定部分并跳过其余内容。后一种用法通常用于按块引用文件内容。

注意：尽管 所有这些命令均可用于呈现 C++ 代码，但 \snippet 和 \codeline 命令比其他命令更受推荐。这些命令允许用其他 Qt 语言绑定中的等效代码片段替换文档中的 C++ 代码片段。

\quotefile

\quotefile 命令会展开为作为参数提供的文件的完整内容。

该命令将该行的其余部分视为其参数的一部分，请确保在文件名后添加换行符。

文件内容将以单独的段落形式呈现，采用等宽字体和标准缩进。代码将原样显示。

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

从 6.11 版本开始，可以在与 `\quotefile ` 命令位于同一行的可选参数中指定语言（不区分大小写）。这会对引号内的文本产生影响，其作用方式与 \code 命令一样，对引号内的文本产生影响。

例如：

\quotefile [text] examples/main.cpp

当引用包含源代码的文件时，此功能非常有用，因为QDoc无法对这些源代码进行标记。

另请参阅 \quotefromfile 以及 \code。

\quotefromfile

\quotefromfile 命令用于打开作为参数传入的文件，以便进行引号处理。

该命令将该行的其余部分视为参数的一部分，请确保在文件名后添加换行符。

该命令旨在配合逐步引导命令从文件中引用部分内容时使用： \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil。这使您能够引用文件中的特定部分。

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDoc 会记住正在引用的是哪个文件，以及在该文件中的当前位置（参见 \printline 以获取更多信息）。无需“关闭”该文件。

从 6.11 版本开始，可以在与\quotefromfile 命令同一行中，将语言作为可选的、不区分大小写的参数指定。这会像 \code 命令一样，对引用的文本产生影响。

例如：

\quotefromfile [text] examples/main.cpp
\skipto main
\printuntil app(argc, argv)

QDoc 还会记住当前引用的代码语言，因此诸如 \printline、 \printto 以及 \printuntil 会引用当前文件中的内容，并应用一致的标记样式，直到读取新文件为止。

另请参阅 \quotefile， \code 以及 \dots。

\printline

\printline 命令会展开为从当前位置开始的一行。

为确保文档与源文件保持同步，必须将该行的子字符串作为命令的参数指定。请注意，该命令会将该行的其余部分视为参数的一部分，因此请务必在子字符串后添加换行符。

源文件中的该行将作为独立段落呈现，采用等宽字体和标准缩进。代码以原样形式显示。

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDoc 按顺序读取文件。要将当前位置向前移动，可以使用\skip ……中的任意一个命令。要将当前位置向后移动，可以再次使用 \quotefromfile 命令。

如果子字符串参数被斜杠包围，则将其解释为regular expression 。

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

（完整的示例文件……）

正则表达式/^\}/ 会使 QDoc 输出直到行首出现第一个未缩进的 '}' 字符为止。/.../ 包围着正则表达式，而 '^' 表示行首。由于 '}' 是正则表达式中的特殊字符，因此必须对其进行转义。

如果无法找到指定的子字符串或正则表达式（即源代码已发生更改），QDoc 会发出警告。

另请参阅 \printto 以及 \printuntil。

\printto

\printto 命令会展开为从当前位置开始，直至但不包括下一个包含给定子字符串的行之间的所有行。

该命令将行余下的内容视为其参数的一部分，请确保在子字符串后跟一个换行符。该命令在定位和参数方面也遵循与 \printline 命令遵循相同的定位和参数约定。

源文件中的行将以单独段落的形式呈现，采用等宽字体和标准缩进。代码以原样形式显示。

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

另请参阅 \printline 以及 \printuntil。

\printuntil

\printuntil 命令会展开为从当前位置开始，直至包含给定子字符串的下一行（该行包含在内）的所有行。

如果\printuntil 不带参数使用，则会展开为从当前位置到引号所包文件末尾的所有行。

源文件中的行将以单独的段落形式呈现，使用等宽字体和标准缩进。代码将原样显示。

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

另请参阅 \printline 以及 \printto。

\skipline

\skipline 命令会忽略当前源文件中接下来的一行非空行。

Doc 按顺序读取文件，\skipline 命令用于移动当前位置（跳过源文件中的一行）。请参阅上文关于文件定位的说明。

该命令将该行的其余部分视为其参数的一部分，请确保在子字符串后跟一个换行符。该命令在参数方面也遵循与 \printline ，并需与 \quotefromfile 命令配合使用。

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

另请参阅 \skipto， \skipuntil 以及 \dots。

\skipto

\skipto 命令会忽略从当前位置开始，直至（但不包括）下一行中包含给定子字符串为止的所有行。

QDoc 按顺序读取文件，而\skipto 命令用于移动当前位置（跳过源文件中的一行或多行）。请参阅上文关于文件定位的说明。

该命令将该行的其余部分视为其参数的一部分，请确保在子字符串后跟一个换行符。

该命令在参数方面也遵循与 \printline 命令遵循相同的参数约定，并需与 \quotefromfile 命令配合使用。

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

另请参阅 \skipline， \skipuntil 以及 \dots。

\skipuntil

\skipuntil 命令会忽略从当前位置开始，直至包含给定子字符串的下一行（该行包含在内）为止的所有行。

QDoc 按顺序读取文件，而 `\skipuntil ` 命令用于移动当前位置（跳过源文件中的一行或多行）。请参阅上文关于文件定位的说明。

该命令将该行的其余部分视为其参数的一部分，请确保在子字符串后跟一个换行符。

该命令在参数方面也遵循与 \printline 命令遵循相同的参数约定，并需与 \quotefromfile 命令配合使用。

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

另请参阅 \skipline， \skipto 以及 \dots。

\dots

\dots 命令表示在引用文件时，源文件的部分内容已被省略。

该命令需与 \quotefromfile 命令配合使用，并应单独写在一行上。这些省略号将使用等宽字体显示在新行上。

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

默认缩进为 4 个空格，但可通过该命令的可选参数进行调整。

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

另请参阅 \skipline， \skipto 以及 \skipuntil。

\snippet

\snippet 命令会将代码片段原样作为预格式化文本包含进来，该文本可能会进行语法高亮显示。

每个代码片段都通过包含它的文件以及该文件的唯一标识符进行引用。代码片段文件通常存储在文档目录下的snippets 目录中（例如，$QTDIR/doc/src/snippets ）。

注意：QDoc 会根据exampledirs和imagedirs变量配置的目录（以及在示例目录下找到的任何doc/images 目录）解析相对代码片段路径。它不会搜索sourcedirs 或headerdirs ，因此位于与示例不同目录树中的代码片段文件仍必须可通过exampledirs 或imagedirs 访问。该 \quotefile 和 \quotefromfile 命令以相同的方式解析其文件。

QDoc 会使用它找到的第一个匹配文件。当同一个相对路径存在于多个搜索目录下时，QDoc 会按字典序遍历这些目录，因此一个文件可能会被另一个文件覆盖。

例如，以下文档引用了位于文档目录子目录中的一个文件中的代码片段：

\snippet snippets/textdocument-resources/main.cpp Adding a resource

文件名后的文本是该代码片段的唯一标识符。它用于限定相关代码片段文件中引用的代码，如下例所示，该示例对应于上文的\snippet 命令：

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

默认情况下，QDoc会将//! 作为代码片段标记进行识别。对于.pro 、.py 、.cmake 和CMakeLists.txt 文件，系统会检测#! 。最后，在.html 、.qrc 、.ui 、.xml 和.xq 文件中，系统会接受<!-- 作为标记。

QDoc 通过将代码片段标记的基于空格的缩进与代码片段内容的最小缩进进行比较（忽略 Qt 宏、空行和整行注释），来规范代码片段的缩进。随后，它会自动将代码片段主体的缩进调整为两者中较小的一方，从而确保生成的代码始终保持其自然结构，无论标记位于何处。缩进不足的标记则保持不变。

注意：QDoc 仅处理空格字符以实现缩进规范化，不处理制表符或其他空白字符。为获得最佳效果，请在包含代码片段的源文件中使用一致的基于空格的缩进。

从 6.11 版本开始，可以在与 `\snippet ` 命令位于同一行的可选参数中指定语言（不区分大小写）。这会以与 \code 命令一样，对引号内的文本产生影响。

此命令示例将覆盖默认的 C++ 标记样式，并输出纯文本：

\snippet [text] code.cpp

当引用 QDoc 无法进行标记的语言时，或者需要引用文件名不符合常规格式的文件时，此功能非常有用。

\codeline

\codeline 命令可插入一行空的预格式化文本。该命令用于在代码片段之间插入空行，而无需关闭当前的预格式化文本区域并打开一个新的。

内联代码创建链接

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