QImageReader Class

成员函数文档

QImageReader::QImageReader()

创建一个空的 QImageReader 对象。在读取图像之前，请调用setDevice() 或setFileName()。

[explicit] QImageReader::QImageReader(QIODevice *device, const QByteArray &format = QByteArray())

使用设备device 和图像格式format 创建一个QImageReader对象。

[explicit] QImageReader::QImageReader(const QString &fileName, const QByteArray &format = QByteArray())

创建一个 QImageReader 对象，文件名为fileName ，图像格式为format 。

另请参阅 setFileName()。

[noexcept] QImageReader::~QImageReader()

销毁QImageReader 对象。

[static, since 6.0] int QImageReader::allocationLimit()

返回当前的内存分配限制，单位为兆字节。

该函数在 Qt 6.0 中引入。

另请参阅 ` setAllocationLimit()`。

bool QImageReader::autoDetectImageFormat() const

如果此图像读取器启用了图像格式自动检测，则返回true ；否则返回false 。默认情况下，自动检测处于启用状态。

另请参阅 setAutoDetectImageFormat()。

bool QImageReader::autoTransform() const

如果图像处理程序将在调用read() 和effectiveSize() 时应用变换元数据，则返回true 。

另请参阅 setAutoTransform()、transformation()、read() 和effectiveSize()。

QColor QImageReader::backgroundColor() const

返回读取图像时使用的背景色。如果图像格式不支持设置背景色，则返回一个无效的颜色。

另请参阅 setBackgroundColor() 和read()。

bool QImageReader::canRead() const

如果设备能够读取该图像（即支持该图像格式，且设备中似乎包含有效数据），则返回true ；否则返回false 。

canRead() 是一个轻量级函数，仅进行快速测试以检查图像数据是否有效。如果图像数据已损坏，即使 canRead() 返回true ，read() 仍可能返回 false。

对于支持动画的图像，当所有帧均已读取完毕时，canRead() 会返回false 。

另请参阅 read()、supportedImageFormats() 和QMimeDatabase 。

QRect QImageReader::clipRect() const

返回图像的裁剪矩形（也称为 ROI，即感兴趣区域）。如果未设置裁剪矩形，则返回一个无效的QRect 。

另请参阅 setClipRect()。

int QImageReader::currentImageNumber() const

对于支持动画的图像格式，该函数返回当前帧的序列号。如果图像格式不支持动画，则返回 0。

如果发生错误，该函数将返回 -1。

另请参阅 supportsAnimation()、QImageIOHandler::currentImageNumber()，以及canRead()。

QRect QImageReader::currentImageRect() const

对于支持动画的图像格式，该函数返回当前帧的矩形。否则，返回一个空矩形。

另请参阅 supportsAnimation() 和QImageIOHandler::currentImageRect()。

bool QImageReader::decideFormatFromContent() const

返回值表示图像读取器是否应仅根据数据流的内容（而非文件扩展名）来决定使用哪个插件。

另请参阅 setDecideFormatFromContent()。

QIODevice *QImageReader::device() const

返回当前分配给QImageReader 的设备；若未分配任何设备，则返回nullptr 。

另请参阅 setDevice()。

[since 6.12] QSize QImageReader::effectiveSize() const

返回考虑了变换后的图像有效尺寸，而无需实际读取图像内容。

如果图像格式不支持此功能，该函数将返回一个无效的大小。Qt 的内置图像处理程序均支持此功能，但自定义图像格式插件则无需支持。

该函数在 Qt 6.12 中引入。

另请参阅 setAutoTransform()、size()、QImageIOHandler::ImageOption 、QImageIOHandler::option() 以及QImageIOHandler::supportsOption()。

QImageReader::ImageReaderError QImageReader::error() const

返回上次发生的错误类型。

另请参阅 ImageReaderError 和errorString()。

QString QImageReader::errorString() const

返回最近发生的错误的人类可读描述。

另请参阅 error()。

QString QImageReader::fileName() const

如果当前分配的设备是QFile ，或者已调用setFileName()，则该函数返回QImageReader 读取的文件名。否则（即未分配任何设备，或者设备不是QFile ），则返回一个空的QString 。

另请参阅 setFileName() 和setDevice()。

QByteArray QImageReader::format() const

返回QImageReader 用于读取图像的格式。

在将设备分配给读取器后，您可以调用此函数以确定设备的格式。例如：

QImageReader reader("image.png");
// reader.format() == "png"

如果读取器无法从设备读取任何图像（例如，设备中没有图像，或者图像已被读取），或者该格式不受支持，则此函数将返回一个空的 QByteArray()。

另请参阅 setFormat() 和supportedImageFormats()。

int QImageReader::imageCount() const

对于支持动画的图像格式，此函数返回动画中的图像总数。如果该格式不支持动画，则返回 0。

如果发生错误，该函数将返回 -1。

另请参阅 supportsAnimation()、QImageIOHandler::imageCount() 和canRead()。

QImage::Format QImageReader::imageFormat() const

返回图像的格式，而不会实际读取图像内容。该格式描述的是QImageReader::read()函数返回的图像格式，而非实际图像的格式。

如果图像格式不支持此功能，则该函数将返回一个无效的格式。

另请参阅 QImageIOHandler::ImageOption 、QImageIOHandler::option() 和QImageIOHandler::supportsOption()。

[static] QByteArray QImageReader::imageFormat(QIODevice *device)

如果支持，该函数将返回设备的图像格式device 。否则，将返回一个空字符串。

另请参阅 QImageReader::autoDetectImageFormat()。

[static] QByteArray QImageReader::imageFormat(const QString &fileName)

如果支持，该函数将返回文件fileName 的图像格式；否则，返回一个空字符串。

[static] QList<QByteArray> QImageReader::imageFormatsForMimeType(const QByteArray &mimeType)

返回与mimeType 对应的图像格式列表。

请注意，必须在调用此函数之前创建QGuiApplication 实例。

另请参阅 supportedImageFormats() 和supportedMimeTypes()。

bool QImageReader::jumpToImage(int imageNumber)

对于支持动画的图像格式，该函数会跳转到序列号为imageNumber 的图像，若操作成功则返回 true，若无法找到对应的图像则返回 false。

下次调用read() 时，将尝试读取该图像。

另请参阅 jumpToNextImage() 和QImageIOHandler::jumpToImage()。

bool QImageReader::jumpToNextImage()

对于支持动画的图像格式，此函数会逐帧遍历当前图像，若操作成功则返回 true，若动画中没有后续图像则返回 false。

默认实现会调用 `read()`，然后丢弃生成的图像，但图像处理程序可能有更高效的方式来实现此操作。

另请参阅 jumpToImage() 和QImageIOHandler::jumpToNextImage()。

int QImageReader::loopCount() const

对于支持动画的图像格式，此函数返回动画应循环的次数。如果此函数返回 -1，则可能表示动画应无限循环，也可能表示发生了错误。如果发生了错误，canRead() 将返回 false。

另请参阅 supportsAnimation()、QImageIOHandler::loopCount() 和canRead()。

int QImageReader::nextImageDelay() const

对于支持动画的图像格式，该函数返回在显示动画的下一帧之前需要等待的毫秒数。如果图像格式不支持动画，则返回 0。

如果发生错误，该函数返回 -1。

另请参阅 supportsAnimation()、QImageIOHandler::nextImageDelay() 和canRead()。

int QImageReader::quality() const

返回图像格式的质量设置。

另请参阅 setQuality()。

QImage QImageReader::read()

从设备中读取一张图像。若操作成功，则返回所读取的图像；否则，返回一个空的QImage 。随后，您可以调用error()来查明发生的错误类型，或调用errorString()来获取该错误的人类可读描述。

对于支持动画的图像格式，重复调用 read() 将返回下一帧。当所有帧均已读取完毕时，将返回一个空图像。

另请参阅 canRead()、supportedImageFormats()、supportsAnimation() 以及QMovie 。

bool QImageReader::read(QImage *image)

将设备中的图像读入image ，该参数必须指向一个QImage 。成功时返回true ；否则返回false 。

如果 `image ` 与即将读取的图像数据具有相同的格式和大小，则该函数在读取前可能无需分配新的图像。因此，它可能比总是会构建新图像的另一个 `read()` 重载版本更快；特别是在读取多个具有相同格式和大小的图像时。

QImage icon(64, 64, QImage::Format_RGB32);
QImageReader reader("icon_64x64.bmp");
if (reader.read(&icon)) {
    // Display icon
}

对于支持动画的图像格式，重复调用 read() 将返回下一帧。当所有帧均已读取完毕时，将返回一个空图像。

另请参阅 canRead(),supportedImageFormats(),supportsAnimation() 以及QMovie 。

QRect QImageReader::scaledClipRect() const

返回图像的缩放后裁剪矩形。

另请参阅 setScaledClipRect()。

QSize QImageReader::scaledSize() const

返回图像的缩放后尺寸。

另请参阅 setScaledSize()。

[static, since 6.0] void QImageReader::setAllocationLimit(int mbLimit)

将内存分配上限设置为mbLimit 兆字节。如果图像所需的QImage 内存分配超过此上限，则该图像将被拒绝。如果mbLimit 为0，则将禁用分配大小检查。

此限制有助于应用程序避免因加载损坏的图像文件而导致内存使用量意外增大。通常无需更改此设置。默认限制对于所有常用图像尺寸而言已足够大。

在运行时，此值可能会被环境变量QT_IMAGEIO_MAXALLOC 覆盖。

该函数在 Qt 6.0 中引入。

另请参阅 allocationLimit()。

void QImageReader::setAutoDetectImageFormat(bool enabled)

如果 `enabled ` 为真，则启用图像格式自动检测；否则，则禁用。默认情况下，自动检测处于启用状态。

QImageReader 采用一种全面的方法来检测图像格式；首先，如果您将文件名传递给QImageReader ，当给定的文件名不指向现有文件时，它会尝试检测文件扩展名，方法是将支持的默认扩展名逐个附加到给定的文件名上。然后，它使用以下方法检测图像格式：

• 首先根据可选的格式字符串或文件名后缀（如果源设备是文件）查询图像插件。此阶段不会进行内容检测。QImageReader 将选择第一个支持读取该格式的插件。
• 如果没有插件支持该图像格式，则会根据可选的格式字符串或文件名后缀检查 Qt 的内置处理程序。
• 如果找不到任何支持该格式的插件或内置处理程序，则会通过检查数据流的内容来测试每个插件。
• 如果没有任何插件能够根据数据内容检测到图像格式，则会通过检查内容来测试每个内置图像处理程序。
• 最后，如果上述所有方法均失败，QImageReader 将在尝试读取图像时报告失败。

通过禁用图像格式自动检测，QImageReader 将仅根据格式字符串查询插件和内置处理程序（即，不测试文件名扩展名）。

另请参阅 autoDetectImageFormat()、QImageIOHandler::canRead() 和QImageIOPlugin::capabilities()。

void QImageReader::setAutoTransform(bool enabled)

规定，如果enabled 的值为true ，则read()返回的图像以及effectiveSize()返回的尺寸应自动应用变换元数据。

另请参阅 autoTransform()、transformation()、read() 和effectiveSize()。

void QImageReader::setBackgroundColor(const QColor &color)

将背景色设置为color 。支持此操作的图像格式应在读取图像之前将背景初始化为color 。

另请参阅 backgroundColor() 和read()。

void QImageReader::setClipRect(const QRect &rect)

将图像裁剪矩形（也称为 ROI，即感兴趣区域）设置为rect 。rect 的坐标是相对于未变换的图像尺寸的，该尺寸由size() 返回。

另请参阅 clipRect()、setScaledSize() 以及setScaledClipRect()。

void QImageReader::setDecideFormatFromContent(bool ignored)

如果将 `ignored ` 设置为 `true`，则图像读取器将忽略指定的格式或文件扩展名，仅根据数据流中的内容来决定使用哪个插件。

设置此标志意味着将加载所有图像插件。每个插件都会读取图像数据的前几个字节，并据此判断自身是否兼容。

此设置还会禁用图像格式的自动检测功能。

另请参阅 decideFormatFromContent()。

void QImageReader::setDevice(QIODevice *device)

将QImageReader 的设备设置为device 。如果设备已设置，则从QImageReader 中移除旧设备，其余部分保持不变。

如果该设备尚未打开，QImageReader 将通过调用 open() 尝试以ReadOnly 模式打开该设备。请注意，对于某些设备（例如QProcess 、QTcpSocket 和QUdpSocket ），此方法无法正常工作，因为这些设备需要更复杂的逻辑才能打开。

另请参阅 device() 和setFileName()。

void QImageReader::setFileName(const QString &fileName)

将QImageReader 的文件名设置为fileName 。在内部，QImageReader 会创建一个QFile 对象，并以ReadOnly 模式打开它，在读取图像时使用该对象。

如果fileName 不包含文件扩展名（例如 .png 或 .bmp），QImageReader 将依次遍历所有受支持的扩展名，直到找到匹配的文件。

另请参阅 fileName()、setDevice() 和supportedImageFormats()。

void QImageReader::setFormat(const QByteArray &format)

将QImageReader 读取图像时使用的格式设置为format 。format 是一个不区分大小写的文本字符串。示例：

QImageReader reader;
reader.setFormat("png"); // same as reader.setFormat("PNG");

您可以调用supportedImageFormats() 以获取QImageReader 支持的所有格式列表。

另请参阅 format()。

void QImageReader::setQuality(int quality)

将图像格式的质量设置设为quality 。

某些图像格式（尤其是有损格式）会在 a) 生成的图像的视觉质量与 b) 解码执行时间之间产生权衡。此函数用于为支持该功能的图像格式设置该权衡的程度。

在读取缩放后的图像时，质量设置还可能影响视觉质量与缩放算法执行速度之间的权衡程度。

quality 的取值范围取决于图像格式。例如，“jpeg”格式支持的质量范围为 0（低视觉质量）到 100（高视觉质量）。

另请参阅 quality() 和setScaledSize()。

void QImageReader::setScaledClipRect(const QRect &rect)

将缩放后的裁剪矩形设置为rect 。缩放后的裁剪矩形是指在图像缩放后应用的裁剪矩形（也称为 ROI，即感兴趣区域）。

另请参阅 scaledClipRect() 和setScaledSize()。

void QImageReader::setScaledSize(const QSize &size)

将图像的缩放后尺寸设置为size 。缩放操作在初始裁剪矩形处理之后、但缩放后的裁剪矩形应用之前进行。 所使用的缩放算法取决于图像格式。默认情况下（即图像格式不支持缩放时），QImageReader 将使用QImage::scale()并配合Qt::SmoothScaling。

如果size 中只设置了一维尺寸，则另一维将根据图像的natural size 计算得出，以保持宽高比。

另请参阅 scaledSize()、setClipRect() 和setScaledClipRect()。

QSize QImageReader::size() const

返回图像的大小，而无需实际读取图像内容。

如果图像格式不支持此功能，该函数将返回一个无效的大小值。Qt 的内置图像处理程序均支持此功能，但自定义图像格式插件则无需支持。

另请参阅 effectiveSize()、QImageIOHandler::ImageOption 、QImageIOHandler::option() 以及QImageIOHandler::supportsOption()。

QByteArray QImageReader::subType() const

返回图像的子类型。

[static] QList<QByteArray> QImageReader::supportedImageFormats()

返回QImageReader 支持的图像格式列表。

默认情况下，Qt 可以读取以下格式：

通过 Qt SVG 模块支持读写SVG文件。 Qt Image Formats 模块还支持其他图像格式。

请注意，在调用此函数之前，必须先创建QCoreApplication 实例。

另请参阅 setFormat()、QImageWriter::supportedImageFormats() 和QImageIOPlugin 。

[static] QList<QByteArray> QImageReader::supportedMimeTypes()

返回QImageReader 支持的 MIME 类型列表。

请注意，在调用此函数之前，必须先创建QApplication 实例。

另请参阅 supportedImageFormats() 和QImageWriter::supportedMimeTypes()。

QList<QByteArray> QImageReader::supportedSubTypes() const

返回图像支持的子类型列表。

bool QImageReader::supportsAnimation() const

如果图像格式支持动画，则返回true ；否则，返回false。

另请参阅 QMovie::supportedFormats()。

bool QImageReader::supportsOption(QImageIOHandler::ImageOption option) const

如果读取器支持option ，则返回true ；否则返回 false。

不同的图像格式支持不同的选项。 调用此函数可确定当前格式是否支持某个选项。例如，PNG 格式允许将文本嵌入到图像的元数据中（参见text()），而 BMP 格式允许在不将整个图像加载到内存的情况下确定图像的大小（参见size()）。

QImageReader reader(":/image.png");
if(reader.supportsOption(QImageIOHandler::Size))
    qDebug() << "Size:" << reader.size();

另请参阅 QImageWriter::supportsOption()。

QString QImageReader::text(const QString &key) const

返回与key 关联的图片文本。

此选项的支持通过 `QImageIOHandler::Description` 实现。

另请参阅 textKeys() 和QImageWriter::setText()。

QStringList QImageReader::textKeys() const

返回此图片的文本键。您可以将这些键与text() 结合使用，以列出某个键对应的图片文本。

此选项的支持是通过QImageIOHandler::Description 实现的。

另请参阅 text()、QImageWriter::setText() 和QImage::textKeys()。

QImageIOHandler::Transformations QImageReader::transformation() const

返回图像的变换元数据，包括图像方向。如果该格式不支持变换元数据，则返回QImageIOHandler::TransformationNone 。

另请参阅 setAutoTransform() 和autoTransform()。