QML Image Element

The Image element displays an image in a declarative user interface More...

Image元素在一个声明式的用户接口中显示一张图片。

Inherits Item

Inherited by AnimatedImage.

List of all members, including inherited members

Properties

asynchronous : bool
fillMode : enumeration
paintedHeight : real
paintedWidth : real
progress : real
smooth : bool
source : url
sourceSize : QSize
status : enumeration

Detailed Description

The Image element is used to display images in a declarative user interface.

Image元素用来显示图片。

The source of the image is specified as a URL using the source property. Images can be supplied in any of the standard image formats supported by Qt, including bitmap formats such as PNG and JPEG, and vector graphics formats such as SVG. If you need to display animated images, use the AnimatedImageelement.

图片通过source属性来指定来源。Image支持各种标准格式的图片，包括bitmap,png,jpeg,svg。如果想显示图片动画，请使用AnimatedImage元素。

If the width and height properties are not specified, the Image element automatically uses the size of the loaded image. By default, specifying the width and height of the element causes the image to be scaled to that size. This behavior can be changed by setting the fillMode property, allowing the image to be stretched and tiled instead.

如果width和height属性没有指定，则使用图片真实的width和height。通常是通过指定width和height来实现图片缩放，这里可以通过设置fillMode属性来设置是否允许图片拉伸或是平铺。

Example Usage

The following example shows the simplest usage of the Image element.

下面一个例子显示了一个Image元素的最简单用法。

import QtQuick 1.0
Image {
source: "pics/qtlogo.png"
}

import QtQuick 1.0
Image {
source: "pics/qtlogo.png"
}

Performance

By default, locally available images are loaded immediately, and the user interface is blocked until loading is complete. If a large image is to be loaded, it may be preferable to load the image in a low priority thread, by enabling the asynchronous property.

默认情况下，程序启动前会马上加载本地图片，而用户接口则等到图片加载完了之后才开始显示。如果加载的图片比较大则等待时间会比较长，这时可以将asynchronous属性置为真。

If the image is obtained from a network rather than a local resource, it is automatically loaded asynchronously, and the progress and status properties are updated as appropriate.

如果图片是来自网络下载，则asynchronous属性自动为真，而progress属性和status属性也会随着下载的进度自动更新。

Images are cached and shared internally, so if several Image elements have the same source, only one copy of the image will be loaded.

图片会被缓存并做内部共享，同一个图片只会被加载一次并且只有一个拷贝。

Note: Images are often the greatest user of memory in QML user interfaces. It is recommended that images which do not form part of the user interface have their size bounded via the sourceSize property.
This is especially important for content that is loaded from external sources or provided by the user.

注意：图片往往是QML中消耗内存最多，建议将用户界面不需要的图片的size自动绑定到其sourceSize，特别是作为外部资源图片或是用户提供的图片。

Property Documentation

asynchronous : bool

Specifies that images on the local file system should be loaded asynchronously in a separate thread. The default value is false, causing the user interface thread to block while the image is loaded. Setting asynchronous to
true is useful where maintaining a responsive user interface is more desirable than having images immediately visible.

默认值为假，此时用户接口线程会阻塞知道将图片加载完。如果asynchronous为真则会在另外一个线程中加载图片，不会阻塞用户接口线程。

Note that this property is only valid for images read from the local filesystem. Images loaded via a network resource (e.g. HTTP) are always loaded asynchonously.

注意这个属性只对读取本地的图片有效，网络资源图片则总是在另外一个线程中加载。

fillMode : enumeration

Set this property to define what happens when the image set for the item is smaller than the size of the item.

fillMode属性用来定义当图片大小设置小于item大小时的填充方式。

Image.Stretch - the image is scaled to fit
此时图片会被拉伸到item的大小。Image.Stretch是fillMode的默认填充方式。
Image.PreserveAspectFit - the image is scaled uniformly to fit without cropping
此时图片会统一缩放，没有剪切。
Image.PreserveAspectCrop - the image is scaled uniformly to fill, cropping if necessary
此时图片会被统一缩放，如果有必要则会剪切。
Image.Tile - the image is duplicated horizontally and vertically
在垂直和水平方向平铺图片。
Image.TileVertically - the image is stretched horizontally and tiled vertically
图片水平方向拉伸，垂直方向平铺
Image.TileHorizontally - the image is stretched vertically and tiled horizontally
图片水平方向平铺，垂直方向拉伸。

	Stretch (default) Image { width: 130; height: 100 smooth: true source: "qtlogo.png" } <span style="font-size:18px;"> Image { width: 130; height: 100 smooth: true source: "qtlogo.png" } </span>
	PreserveAspectFit Image { width: 130; height: 100 fillMode: Image.PreserveAspectFit smooth: true source: "qtlogo.png" }
	PreserveAspectCrop Image { width: 130; height: 100 fillMode: Image.PreserveAspectCrop smooth: true source: "qtlogo.png" clip: true } <span style="font-size:18px;"> Image { width: 130; height: 100 fillMode: Image.PreserveAspectCrop smooth: true source: "qtlogo.png" clip: true } </span>
	Tile Image { width: 120; height: 120 fillMode: Image.Tile source: "qtlogo.png" }
	TileVertically Image { width: 120; height: 120 fillMode: Image.TileVertically smooth: true source: "qtlogo.png" } <span style="font-size:18px;"> Image { width: 120; height: 120 fillMode: Image.TileVertically smooth: true source: "qtlogo.png" } </span>
	TileHorizontally Image { width: 120; height: 120 fillMode: Image.TileHorizontally smooth: true source: "qtlogo.png" }

See also QDeclarativeImageProvider.

sourceSize : QSize

This property holds the actual width and height of the loaded image.

sourceSize属性指明了加载图片的实际宽度和高度。

Unlike the width and height properties, which scale the painting of the image, this property sets the actual number of pixels stored for the loaded image so that large images do not use more memory than necessary. For example, this ensures the image in memory is no larger than 1024x1024 pixels, regardless of the Image's width and height values:

width/height属性用来缩放图像，而QSize实际上指出了内存中加载这个图片在水平方向和垂直方向上的像素数，即这个图片的分辨率。在下面这个例子中，限制了图片的分辨率为1024X1024，而不管图片的width属性和height属性。

Rectangle {
width: ...
height: ...
Image {
anchors.fill: parent
source: "reallyBigImage.jpg"
sourceSize.width: 1024
sourceSize.height: 1024
}
}

Rectangle {
width: ...
height: ...
Image {
anchors.fill: parent
source: "reallyBigImage.jpg"
sourceSize.width: 1024
sourceSize.height: 1024
}
}

If the image's actual size is larger than the sourceSize, the image is scaled down. If only one dimension of the size is set to greater than 0, the other dimension is set in proportion to preserve the source
image's aspect ratio. (The fillMode is
independent of this.)

If the source is an instrinsically scalable image (eg. SVG), this property determines the size of the loaded image regardless of intrinsic size. Avoid changing this property dynamically; rendering an SVG is slow compared
to an image.

如果图片本质上就支持缩放（例如SVG），这个属性将决定加载图片的大小而不管这个图片本质上的大小。对于SVG图片应该避免动态改变这个属性，因为渲染SVG图片跟普通图片相比速度要慢。

If the source is a non-scalable image (eg. JPEG), the loaded image will be no greater than this property specifies. For some formats (currently only JPEG), the whole image will never actually be loaded into memory.

对于不可缩放的图片（例如JPEG）,加载的图片将不会比这个属性大。实际上对于JPEG图片来说，整个图片并没有真正全部加载到内存中。

Note: Changing this property dynamically causes the image source to be reloaded, potentially even from the network, if it is not in the disk cache.

注意这个属性不能动态改变，否则图片奖重新加载，如果这个图片来自网络则重新下载。

read-onlystatus : enumeration

This property holds the status of image loading. It can be one of:

status属性表明图片加载的状态。可取如下值：

Image.Null - no image has been set
Image.Null 表明没有设置图片
Image.Ready - the image has been loaded
Image.Ready 表明图片已经加载完毕
Image.Loading - the image is currently being loaded
Image.Loading 表明图片正在加载
Image.Error - an error occurred while loading the image
Image.Error 表明加载图片时出错

Use this status to provide an update or respond to the status change in some way. For example, you could:

我们可以使用status来做一些针对图片加载完毕后的一些处理。如下例所示：

Trigger a state change:

 State { name: 'loaded'; when: image.status == Image.Ready }

Implement an onStatusChanged signal handler:
1. Image {
2. id: image
3. onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
4. }
1. Image {
2. id: image
3. onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
4. }
5.

Bind to the status value:

 Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }

顶: 0

踩