包含外部代码
使用以下命令，您可以包含外部文件中的代码片段。您可以让 QDoc 包含文件的全部内容，也可以引用文件的特定部分而跳过其他部分。后者的典型用法是逐块引用文件。
\引用文件
\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. */
另请参见\quotefromfile和\code。
\从文件引用
\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）。无需 "关闭 "文件。
\打印行
\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 命令会扩展到从当前位置到包含给定子串的下一行的所有行。
该命令将该行的其余部分视为其参数的一部分，请确保在子串后使用换行符。该命令还遵循与\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 命令会扩展到从当前位置到包含给定子串的下一行的所有行。
该命令将该行的其余部分视为其参数的一部分，请确保在子串后使用换行符。该命令还遵循与\printline命令相同的定位和参数约定。
如果 \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 命令忽略当前源文件中的下一行非空行。
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 命令忽略从当前位置到包含给定子串的下一行的所有行。
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... */
\点
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 命令可将代码片段作为预格式化文本逐字包含，并可突出显示语法。
每个代码片段都由其所在的文件和该文件的唯一标识符来引用。代码片段文件通常存储在文档目录内的snippets 目录中（例如$QTDIR/doc/src/snippets ）。
例如，以下文档引用了文档目录下一个子目录中的一个文件中的代码片段：
\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 文件中接受<!-- 。
\代码线
\codeline 命令插入预格式化文本的空行。它用于在片段之间插入空行，而不会关闭当前的预格式化文本区域并打开一个新的区域。
© 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.
