Тип QML Image

Отображает изображение Подробнее...

• Список всех членов, включая унаследованные члены

Свойства

• asynchronous : bool
• autoTransform : bool
• cache : bool
• fillMode : enumeration
• horizontalAlignment : enumeration
• mipmap : bool
• mirror : bool
• paintedHeight : real
• paintedWidth : real
• progress : real
• smooth : bool
• source : url
• sourceSize : QSize
• status : enumeration
• verticalAlignment : enumeration

Подробное описание

Тип Image отображает изображение.

Источник изображения указывается как URL-адрес с помощью свойства source. Изображения могут быть предоставлены в любом из стандартных форматов изображений, поддерживаемых Qt, включая растровые форматы, такие как PNG и JPEG, и форматы векторной графики, такие как SVG. Если вам нужно отображать анимированные изображения, используйте AnimatedSprite или AnimatedImage.

Если свойства width и height не указаны, Image автоматически использует размер загруженного изображения. По умолчанию указание ширины и высоты элемента приводит к масштабированию изображения до этого размера. Это поведение можно изменить, установив свойство fillMode, что позволит вместо этого растягивать и чередовать изображение.

Пример использования

В следующем примере показано самое простое использование типа Image.

import QtQuick 2.0

Image {
    source: "pics/qtlogo.png"
}

Производительность

По умолчанию локально доступные изображения загружаются немедленно, и пользовательский интерфейс блокируется до завершения загрузки. Если необходимо загрузить большое изображение, предпочтительнее загрузить его в потоке с низким приоритетом, включив свойство asynchronous.

Если изображение получено из сети, а не из локального ресурса, оно автоматически загружается асинхронно, и свойства progress и status обновляются соответствующим образом.

Изображения кэшируются и совместно используются внутри, поэтому, если несколько элементов Image имеют один и тот же source, будет загружена только одна копия изображения.

Примечание: Изображения часто являются самым большим потребителем памяти в пользовательских интерфейсах QML. Рекомендуется, чтобы изображения, которые не являются частью пользовательского интерфейса, имели ограниченный размер с помощью свойства sourceSize. Это особенно важно для контента, загружаемого из внешних источников или предоставляемого пользователем.

См. также Примеры Qt Quick - Элементы изображения и QQuickImageProvider.

Документация по свойствам

asynchronous : bool

Указывает, что изображения в локальной файловой системе должны загружаться асинхронно в отдельном потоке. Значение по умолчанию — false, из-за чего поток пользовательского интерфейса блокируется во время загрузки изображения. Установка asynchronous в true полезна в тех случаях, когда поддержание отзывчивого пользовательского интерфейса предпочтительнее немедленного отображения изображений.

Обратите внимание, что это свойство действительно только для изображений, считываемых из локальной файловой системы. Изображения, загруженные через сетевой ресурс (например, HTTP), всегда загружаются асинхронно.

autoTransform : bool

Это свойство определяет, должно ли изображение автоматически применять метаданные преобразования изображения, такие как ориентация EXIF.

По умолчанию это свойство установлено в false.

Это свойство QML было введено в Qt 5.5.

cache : bool

Указывает, следует ли кэшировать изображение. Значение по умолчанию — true. Установка cache в false полезна при работе с большими изображениями, чтобы убедиться, что они не кэшируются за счет небольших изображений «элементов пользовательского интерфейса».

fillMode : enumeration

Установите это свойство, чтобы определить, что происходит, когда исходное изображение имеет размер, отличный от размера элемента.

• Image.Stretch - изображение масштабируется для соответствия
• Image.PreserveAspectFit - изображение масштабируется равномерно для соответствия без обрезки
• Image.PreserveAspectCrop - изображение масштабируется равномерно для заполнения, обрезая при необходимости
• Image.Tile - изображение дублируется по горизонтали и вертикали
• Image.TileVertically - изображение растягивается по горизонтали и чередуется по вертикали
• Image.TileHorizontally - изображение растягивается по вертикали и чередуется по горизонтали
• Image.Pad - изображение не преобразуется

Image {
    width: 130; height: 100
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectFit
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectCrop
    source: "qtlogo.png"
    clip: true
}

Image {
    width: 120; height: 120
    fillMode: Image.Tile
    horizontalAlignment: Image.AlignLeft
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileVertically
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileHorizontally
    verticalAlignment: Image.AlignLeft
    source: "qtlogo.png"
}

Обратите внимание, что clip является false по умолчанию, а это значит, что элемент может отрисовываться за пределами своего ограничивающего прямоугольника, даже если fillMode установлен в PreserveAspectCrop.

См. также Примеры Qt Quick - Элементы изображения.

horizontalAlignment : enumeration

Устанавливает горизонтальное и вертикальное выравнивание изображения. По умолчанию изображение выровнено по центру.

Допустимые значения для horizontalAlignment — Image.AlignLeft, Image.AlignRight и Image.AlignHCenter. Допустимые значения для verticalAlignment — Image.AlignTop, Image.AlignBottom и Image.AlignVCenter.

mipmap : bool

Это свойство определяет, использует ли изображение фильтрацию mipmap при масштабировании или преобразовании.

Фильтрация mipmap обеспечивает лучшее визуальное качество при уменьшении масштаба по сравнению с плавной, но это может сказаться на производительности (как при инициализации изображения, так и во время отрисовки).

По умолчанию это свойство установлено в false.

Это свойство QML было введено в Qt 5.3.

См. также smooth.

mirror : bool

Это свойство определяет, следует ли инвертировать изображение по горизонтали (фактически отображая зеркальное изображение).

Значение по умолчанию — false.

paintedHeight : real

Эти свойства содержат размер изображения, которое фактически отрисовывается. В большинстве случаев он совпадает с width и height, но при использовании Image.PreserveAspectFit или Image.PreserveAspectCrop paintedWidth или paintedHeight могут быть меньше или больше, чем width и height элемента Image.

paintedWidth : real

Эти свойства содержат размер изображения, которое фактически отрисовывается. В большинстве случаев он совпадает с width и height, но при использовании Image.PreserveAspectFit или Image.PreserveAspectCrop paintedWidth или paintedHeight могут быть меньше или больше, чем width и height элемента Image.

progress : real

Это свойство содержит ход загрузки изображения, от 0,0 (ничего не загружено) до 1,0 (завершено).

См. также status.

smooth : bool

Это свойство определяет, будет ли изображение плавно фильтроваться при масштабировании или преобразовании. Плавная фильтрация обеспечивает лучшее визуальное качество, но она может быть медленнее на некоторых аппаратных средствах. Если изображение отображается в своем естественном размере, это свойство не оказывает визуального или производительного эффекта.

По умолчанию это свойство установлено в true.

См. также mipmap.

source : url

Изображение может обрабатывать любой формат изображения, поддерживаемый Qt, загруженный из любого URL-схемы, поддерживаемой Qt.

URL может быть абсолютным или относительным к URL компонента.

См. также QQuickImageProvider.

sourceSize : QSize

Это свойство содержит фактическую ширину и высоту загруженного изображения.

В отличие от свойств width и height, которые масштабируют отрисовку изображения, это свойство устанавливает фактическое количество пикселей, хранящихся для загруженного изображения, так что большие изображения не используют больше памяти, чем необходимо. Например, это гарантирует, что изображение в памяти не больше, чем 1024x1024 пикселей, независимо от значений свойств width и height изображения:

Rectangle {
    width: ...
    height: ...

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

Если фактический размер изображения больше, чем sourceSize, изображение уменьшается. Если только одно измерение размера установлено больше 0, другое измерение устанавливается пропорционально для сохранения соотношения сторон исходного изображения. (fillMode не зависит от этого.)

Если установлены и sourceSize.width, и sourceSize.height, изображение будет уменьшено до соответствия указанному размеру, сохраняя соотношение сторон изображения. Фактический размер изображения после масштабирования доступен через Item::implicitWidth и Item::implicitHeight.

Если источником является масштабируемое изображение (например, SVG), это свойство определяет размер загруженного изображения независимо от собственного размера. Избегайте динамического изменения этого свойства; рендеринг SVG медленный по сравнению с изображением.

Если источником является немасштабируемое изображение (например, JPEG), загруженное изображение не будет больше, чем указано в этом свойстве. Для некоторых форматов (в настоящее время только JPEG) все изображение никогда фактически не загружается в память.

sourceSize может быть очищен до естественного размера изображения, установив sourceSize в undefined.

Примечание: Динамическое изменение этого свойства приводит к повторной загрузке источника изображения, потенциально даже из сети, если он не находится в кэше диска.

status : enumeration

Это свойство содержит состояние загрузки изображения. Оно может быть одним из:

• Image.Null - изображение не установлено
• Image.Ready - изображение загружено
• Image.Loading - изображение в настоящее время загружается
• Image.Error - произошла ошибка при загрузке изображения

Используйте это состояние, чтобы предоставить обновление или каким-то образом отреагировать на изменение состояния. Например, вы можете:

• Инициировать изменение состояния:

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

• Реализовать обработчик сигнала onStatusChanged:

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

• Привязать к значению состояния:

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

См. также progress.

verticalAlignment : enumeration

Устанавливает горизонтальное и вертикальное выравнивание изображения. По умолчанию изображение выровнено по центру.

Допустимые значения для horizontalAlignment являются Image.AlignLeft, Image.AlignRight и Image.AlignHCenter. Допустимые значения для verticalAlignment являются Image.AlignTop, Image.AlignBottom и Image.AlignVCenter.