Тип QML изображения

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

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

Свойства

• асинхронный : bool
• autoTransform : bool
• кеш : bool
• режим заполнения : перечисление
• горизонтальное выравнивание : перечисление
• mipmap : bool
• зеркало : bool
• высота отрисовки : real
• ширина отрисовки : real
• прогресс : real
• гладко : bool
• источник : url
• размер источника : QSize
• статус : перечисление
• вертикальное выравнивание : перечисление

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

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

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

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

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

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

import QtQuick 2.0

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

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

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

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

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

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

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

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

Если используется OpenGL граф сцены backend, поиск файла сначала выполняется с использованием расширений файлов 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.

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

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

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

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

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

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

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

асинхронный : bool

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

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

autoTransform : bool

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

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

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

кеш : bool

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

режим заполнения : перечисление

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

• 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 по умолчанию, что означает, что элемент может рисовать за пределами своей области, даже если режим заполнения установлен на PreserveAspectCrop.

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

горизонтальное выравнивание : перечисление

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

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

mipmap : bool

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

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

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

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

См. также гладко.

зеркало : bool

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

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

высота отрисовки : 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.