Тип 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
• sourceClipRect : rect
• 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"
}

Сжатые файлы текстур

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

• 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, то этот файл будет загружен.

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

// 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 — количество кадров в изображении. Большинство изображений содержат только один кадр.

Это свойство QML было добавлено в 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), всегда загружаются асинхронно.

[с 5.5] 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 — Элементы изображения.

[с 5.3] 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, Сжатые текстурные файлы и Автоматическое определение расширения файла.

[с 5.15] sourceClipRect : rect

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

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

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

    Image {
       anchors.fill: parent
       source: "reallyBigImage.svg"
       sourceSize.width: 1024
       sourceSize.height: 1024
       sourceClipRect: Qt.rect(100, 100, 512, 512)
    }
}

В приведенном выше примере мы концептуально масштабируем SVG-графику до 1024x1024 сначала, а затем вырезаем область интереса размером 512x512 пикселей из положения на 100 пикселей от верхнего и левого краев. Таким образом, sourceSize определяет масштаб, но фактическое выходное изображение имеет размер 512x512 пикселей.

Некоторые форматы изображений могут сохранять время ЦП, рендеринг только указанной области. Другие должны сначала загрузить всё изображение, а затем обрезать его до указанной области.

Это свойство можно очистить, чтобы перезагрузить всё изображение, установив sourceClipRect на undefined.

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

Примечание: Подпиксельная обрезка не поддерживается: заданный прямоугольник будет передан в QImageReader::setScaledClipRect().

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

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) всё изображение никогда фактически не загружается в память.

Если свойство sourceClipRect также установлено, sourceSize определяет масштаб, но он будет обрезан до размера прямоугольника обрезки.

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.