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