Тип 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"
}

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

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

• 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 scene graph, поиск файла сначала выполняется для расширений файлов 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 — это количество кадров в изображении. Большинство изображений содержат только один кадр.

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

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 и Автоматическое определение расширения файла.

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

Если свойство 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.