Qt 6.3 文档翻译：QImageReader类，QImageReader Class

QImageReader 类，提供了一种，与格式无关的，从文件或其它设备中读取图片的接口。 详细说明……

详细说明

要想读取图片，最常见的方式就是使用QImage和QPixmap的构造函数，或是调用QImage::load()和QPixmap::load()方法。QImageReader 是一个特殊的类，它让你在读取图片时可进行更精确的控制。例如，可以调用setScaledSize()，以使得将图片按照指定的缩放尺寸来读取，也可以调用setClipRect()，以指定一个裁剪区域，以便高效地读取图片中的部分内容。取决于这种图片格式的底层支持情况，这样做有可能节省内存，并且加快读取速度。

读取图片之前，首先要构造一个QImageReader 对象。向QImageReader 的构造函数传入一个文件名或设备指针，以及一个图片格式说明。之后，可以设置更多的选项，例如裁剪区域（setClipRect()）和缩放尺寸（setScaledSize()）。使用canRead()可以判断QImageReader 是否能够读取这个图片(图片格式是被支持的，并且设备已经打开为可读模式)。调用read() 来具体读取图片。

如果在读取的过程中出现任何错误，则read() 会返回一个空（null）的QImage。之后，可以调用error() 来查询具体的错误原因，或是调用errorString() 来获取对于该错误的自然语言说明。

注意：QImageReader 假设对于所关联的文件或设备拥有排他性的控制权。在QImageReader 对象的生命周期中，以任何方式尝试对关联的文件或设备进行修改，都可能产生不可预知的结果。

格式

调用supportedImageFormats() 以查询出QImageReader 可以读取的格式的列表。QImageReader 支持所有已有的内置图片格式，以及所有支持读取功能的图片格式插件。调用supportedMimeTypes() 以查询出受支持的文件类型列表，这个列表可以直接向其它接口传递，例如QFileDialog::setMimeTypeFilters()。

QImageReader 默认会自动探测图片的格式：参考（可选的）你所提供的格式字符串，检查文件名的后缀，以及检查数据流中的内容。你可以通过调用setAutoDetectImageFormat()来启用或禁用这个功能。

参考QImageWriter、QImageIOHandler、QImageIOPlugin、QMimeDatabase、QColorSpace、QImage::devicePixelRatio()、QPixmap::devicePixelRatio()、QIcon、QPainter::drawPixmap()和QPainter::drawImage()。

成员类型文档

enum QImageReader::ImageReaderError

这个枚举，说明的是，在使用QImageReader读取图片的过程中，可能出现的错误。

成员函数文档

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

构造一个QImageReader 对象，并且指定文件名为fileName，指定图片格式为format。

参考setFileName()。

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

构造一个QImageReader 对象，并且指定设备为device，指定图片格式为format。

QImageReader::QImageReader()

构造一个空白的QImageReader 对象。在具体读取图片之前，要调用setDevice()或setFileName()。

bool QImageReader::canRead() const

canRead() 是一个轻量级的函数，它只会进行一个快速的测试，以判断该图片的数据是否有效。如果图片的数据被损坏了，那么，即使canRead()返回了真（true），read() 仍然可能返回假（false）。

注意：通常情况下，如果想要识别潜在的非图片文件或数据的话，使用QMimeDatabase进行查询，会比使用这个函数来判断更合适。

对于支持动画的图片，当所有的帧都被读取完毕之后，canRead()会返回假（false）。

参考read()、supportedImageFormats()和QMimeDatabase。

QByteArray QImageReader::format() const

返回QImageReader在读取图片时使用的格式。

你可以在向读取器设置了设备之后，调用这个函数，以确认该个设备的格式。例如：

QImageReader reader( "image.png" );

// reader.format() == "png"

如果有以下任何情况，则这个函数会返回一个空白的QByteArray()：读取器无法从设备中读取任何图片（例如，其中没有图片，或者图片已被读取）；格式不被支持。

参考setFormat()和supportedImageFormats()。

QImage::Format QImageReader::imageFormat() const

在不实际读取图片内容的情况下，返回图片的格式。此处的格式，说明的是QImageReader::read()返回的图片的格式，而不是实际图片本身的储存格式。

如果对应的图片格式不支持这个特性，则这个函数会返回一个无效的格式值。

参考QImageIOHandler::ImageOption、QImageIOHandler::option()和QImageIOHandler::supportsOption()。

QImage QImageReader::read()

从设备中读取一张图片。如果成功，会返回实际读取到的图片；否则，返回一个空（null）的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)) {

// 显示图标

}

对于支持动画的图片格式，重复地调用read()，会返回下一帧。当所有的帧都被读取完毕时，会返回一个空的图片。

参考canRead()、supportedImageFormats()、supportsAnimation()和QMovie。

QSize QImageReader::scaledSize() const

返回图片的缩放尺寸。

参考setScaledSize()。

void QImageReader::setFileName(const QString &fileName)

将QImageReader的文件名设置为fileName。在内部实现中，QImageReader会创建一个QFile对象，并以只读（ReadOnly）模式打开，之后用于读取图片的过程中。

如果fileName并不包含扩展名(例如，.png 或)，那么，QImageReader会对所有支持的扩展名进行尝试，直到找到一个匹配的文件。

参考fileName()、setDevice()和supportedImageFormats()。

void QImageReader::setScaledSize(const QSize &size)

将图片的缩放尺寸设置为size。缩放是在初始的裁剪区域被执行之后，且在缩放裁剪区域被执行之前执行的。具体的缩放算法，取决于图片格式。默认(也就是说，对应的图片格式不支持缩放)情况下，QImageReader会使用QImage::scale()来进行缩放，并传入Qt::SmoothScaling参数。

参考scaledSize()、setClipRect()和setScaledClipRect()。

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()。