Тип QML Image

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

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

Свойства

• asynchronous : bool
• autoTransform : bool
• cache : bool
• currentFrame : int
• fillMode : перечисление
• frameCount : int
• 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 графического ядра, изображения также могут быть предоставлены в сжатых файлах текстур. Содержание должно быть простой текстурой RGB(A) 2D. Поддерживаемые схемы сжатия ограничены только драйвером OpenGL и графическим процессором. Поддерживаются следующие контейнерные форматы файлов:

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

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

convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.png

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

Если 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().

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

currentFrame — кадр, который отображается в данный момент. По умолчанию 0. Можно установить его на число между 0 и frameCount - 1, чтобы отобразить другой кадр, если изображение содержит несколько кадров.

frameCount — количество кадров в изображении. Большинство изображений содержат только один кадр.

Эта документация была добавлена в Qt 5.14.

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

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

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

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

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

mipmap : bool

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

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

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

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

См. также smooth.

mirror : bool

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

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

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 установлены, изображение уменьшится до размера, соответствующего заданным размерам (если не используются PreserveAspectCrop или PreserveAspectFit, тогда оно будет масштабироваться до оптимального размера для обрезки/вписывания), сохраняя соотношение сторон изображения. Фактический размер изображения после масштабирования доступен через 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.