Тип QML Image

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

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

Свойства

• asynchronous : bool
• autoTransform : bool
• cache : bool
• fillMode : перечисление
• 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, изображения также могут быть предоставлены в сжатых файлах текстур. Содержимое должно быть простой 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, поиск файла сначала выполняется по расширениям файлов 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().

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

horizontalAlignment : перечисление

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

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

paintedWidth : real

Эти свойства содержат размер изображения, которое фактически отрисовывается. В большинстве случаев он совпадает с 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 полезна при работе с большими изображениями, чтобы убедиться, что они не кешируются за счёт небольших изображений UI-элементов.

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 - Элементы изображений.

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.