Тип QML Image

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

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

Свойства

• asynchronous : bool
• autoTransform : bool
• cache : bool
• currentFrame : int
• fillMode : перечисление
• frameCount : int
• horizontalAlignment : перечисление
• mipmap : bool
• mirror : bool
• mirrorVertically : bool
• paintedHeight : real
• paintedWidth : real
• progress : real
• smooth : bool
• source : url
• sourceClipRect : rect
• sourceSize : size
• 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 во время выполнения, изображения также могут быть предоставлены в сжатых файлах текстур. Содержимое должно быть простым текстурой RGB(A) 2D. Поддерживаемые схемы сжатия ограничены только базовым драйвером и графическим процессором. Поддерживаются следующие форматы контейнерных файлов:

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

transform: [ Translate { y: -myImage.height }, Scale { yScale: -1 } ]

или

mirrorVertically: true

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.

[с версии 6.2] mirrorVertically : bool

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

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

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

[только для чтения] 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.

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

sourceSize : size

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

В отличие от свойств 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 : перечисление

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

• 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.