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"
}

<span style="font-size:18px;"> import QtQuick 1.0

 Image {
     source: "pics/qtlogo.png"
 }
</span>

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，特別是作為外部資源圖片或是用戶提供的圖片。

See also Image example and QDeclarativeImageProvider.

 

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 Image example.

read-onlypaintedWidth : real

read-onlypaintedHeight : real

These properties hold the size of the image that is actually painted. In most cases it is the same as width and height, but when using a fillMode PreserveAspectFit or fillMode PreserveAspectCrop paintedWidth or paintedHeight can be smaller or larger than width and height of the Image element.

read-onlyprogress : real

This property holds the progress of image loading, from 0.0 (nothing loaded) to 1.0 (finished).

progress屬性表明圖片加載進度，0.0表示沒有加載，1.0表示加載完成。

See also status.

smooth : bool

Set this property if you want the image to be smoothly filtered when scaled or transformed. Smooth filtering gives better visual quality, but is slower. If the image is displayed at its natural size, this property has no visual or performance effect.

如果設置smooth屬性為真則當圖片縮放或是向量變換會給予圖片比較好的顯示效果，但這將導致速度變慢。如果圖片顯示是其固有大小則沒有影響。

Note: Generally scaling artifacts are only visible if the image is stationary on the screen. A common pattern when animating an image is to disable smooth filtering at the beginning of the animation and reenable it at the conclusion.

source : url

Image can handle any image format supported by Qt, loaded from any URL scheme supported by Qt.

 

The URL may be absolute, or relative to the URL of the component.

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
    }
}

<span style="font-size:18px;"> Rectangle {
     width: ...
     height: ...

     Image {
        anchors.fill: parent
        source: "reallyBigImage.jpg"
        sourceSize.width: 1024
        sourceSize.height: 1024
     }
 }
</span>

 

 

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:

  Image {
      id: image
      onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
  }

  <span style="font-size:18px;"> Image {
       id: image
       onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
   }
  </span>

• Bind to the status value:

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

 

頂

0

踩