Тип QML Image

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

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

Свойства

• asynchronous : bool
• autoTransform : bool
• cache : bool
• fillMode : перечисление
• horizontalAlignment : перечисление
• mipmap : bool
• mirror : bool
• paintedHeight : real
• paintedWidth : real
• progress : real
• smooth : bool
• source : url
• sourceSize : QSize
• status : перечисление
• verticalAlignment : перечисление

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

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

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

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

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

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

import QtQuick 2.0

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

Файлы текстур OpenGL

Когда используется стандартный бэкэнд сцены OpenGL, изображения также могут быть предоставлены в сжатых файлах текстур. Содержимое должно быть простой 2D-текстурой формата RGB(A). Поддерживаемые схемы сжатия ограничены только базовым драйвером OpenGL и GPU. Поддерживаются следующие контейнерные форматы файлов:

• PKM (с Qt 5.10)
• KTX (с Qt 5.11)

Примечание: Полупрозрачные исходные изображения требуют предварительного умножения альфа-канала перед сжатием текстуры для правильного отображения в Qt Quick. Это можно сделать с помощью следующей командной строки ImageMagick:

convert MYORIGIMAGE \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite MYPMIMAGE

Автоматическое определение расширения файла

Если URL-адрес свойства source указывает на несуществующий локальный файл или ресурс, элемент Image пытается автоматически определить расширение файла. Если найден существующий файл путем добавления любого из поддерживаемых расширений файлов изображений к URL-адресу свойства source, то этот файл будет загружен.

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

// Assuming the "pics" directory contains the following files:
//   dog.jpg
//   cat.png
//   cat.pkm

Image {
    source: "pics/cat.png"     // loads cat.png
}

Image {
    source: "pics/dog"         // loads dog.jpg
}

Image {
    source: "pics/cat"         // normally loads cat.pkm, but if no OpenGL, loads cat.png instead.
}

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

Эта функциональность была введена в Qt 5.11.

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

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

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

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

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

См. также Примеры Qt Quick - Элементы изображений, QQuickImageProvider и QImageReader::setAutoDetectImageFormat().

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

asynchronous : bool

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

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

autoTransform : bool

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

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

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

cache : bool

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

fillMode : перечисление

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

• 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 : перечисление

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

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

mipmap : bool

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

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

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

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

См. также smooth.

mirror : bool

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

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

paintedHeight : real

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

paintedWidth : вещественное

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

progress : вещественное

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

См. также status.

smooth : логическое

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

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

См. также mipmap.

source : url

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

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

См. также QQuickImageProvider и Автоматическое определение расширения файла.

sourceSize : QSize

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

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

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

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

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

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

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

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

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

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

status : перечисление

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

• 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 : перечисление

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

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