插入图片

通过图形命令，可以在文档中插入图片。这些图片可以作为独立段落显示，也可以嵌入到连续文本中。

\image

\image 命令会展开为由其第一个参数指定的图像，并将其居中显示为一个独立段落。

该命令接受两个参数。第一个参数是图像文件的名称。第二个参数是对图像内容的描述，用于生成 HTML 中的 `alt ` 属性。其内容会被屏幕阅读器朗读出来，因此出于无障碍访问的目的，强烈建议使用该参数。该属性还可被不支持图像的浏览器（如 Lynx 文本浏览器）使用。您还可以设置usealttextastitle变量，让 QDoc 为图像生成title属性，该属性通常会在用户将鼠标悬停在图像上时，由图形文本浏览器作为工具提示显示。

虽然 QDoc 的容错性较强，但您仍应将文件名和描述都用大括号括起来，如下所示：

\image {Bandit.png} {A Golden Retriever holding a bag of coffee in its mouth}

这种语法最为明确，通常能产生预期的结果。如果未达到预期效果，请确保在文件名或描述后添加换行符。如果 description 参数跨多行，则必须使用大括号。如果 description 被双引号包围，QDoc 在生成输出前会将其移除。特殊字符可能会在 QDoc 的 HTML 输出中被替换为相应的 HTML 实体代码。

/*!
    Qt is a C++ toolkit for cross-platform GUI application development.

    \image {happyguy.jpg} {Happy guy}

    Qt provides single-source portability across Microsoft
    Windows, macOS, Linux, and all major commercial Unix
    variants. It is also available for embedded devices.
*/

另请参阅 \inlineimage 以及 \caption。

\inlineimage

\inlineimage 命令会展开为其参数指定的图片。该图片将与其余文本内联显示。

该命令接受两个参数。第一个参数是图像文件的名称。第二个参数是可选的，用于在花括号 {} 中对图像进行简要描述，其作用等同于 HTML 图像标签中的 alt="" 属性。该描述用于显示工具提示，以及当浏览器不支持图像时（例如 Lynx 文本浏览器）。

\inlineimage 命令最常见的用途是在列表和表格中。以下是在列表中插入内联图片的示例：

/*!
    \list 1
      \li \inlineimage happy.gif {Oh so happy, I am a caption!}
      \li \inlineimage happy.gif Oh so happy, but I'm not a caption.
    \endlist
*/

以下是在表格中插入内联图片的示例：

/*!
    \table
    \header
        \li Qt
        \li Qt Creator
    \row
        \li \inlineimage happy.gif {Oh so happy!}
        \li \inlineimage happy.gif Oh so happy!
    \row
        \li \inlineimage happy.gif Oh so happy!
        \li \inlineimage happy.gif {Oh so happy!}
    \endtable
*/

该命令也可用于将图片内联插入到文本中。

/*!
    \inlineimage training.jpg {Qt Training} The Qt Programming course is
    offered as a five day Open Enrollment Course. The classes are open to
    the public. Although the course is open to anyone who wants to learn,
    attendees should have significant experience in C++ development to
    derive maximum benefit from the course.
*/

另请参阅 \image 以及 \caption。

\caption

\caption 命令用于为图像添加标题。

该命令会将段落结尾前的所有文本都作为图注。请反复尝试，直到获得您想要的效果。

/*!
  \table 100%
    \row
      \li \image windows-pushbutton.png
         \caption The QPushButton widget provides a command button.
      \li \image windows-toolbutton.png
         \caption The QToolButton class provides a quick-access button to commands
         or options, usually used inside a QToolBar.
   \endtable
*/

另请参阅 \image 和 \inlineimage

创建链接表格和列表

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