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

Производительность

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

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

Изображения кешируются и совместно используются внутри, поэтому если несколько элементов Image имеют одинаковый source, будет загружена только одна копия изображения.

Примечание: Изображения часто являются наибольшими потребителями памяти в пользовательских интерфейсах QML. Рекомендуется, чтобы изображения, которые не являются частью пользовательского интерфейса, имели ограниченный размер через свойство sourceSize. Это особенно важно для содержимого, загружаемого из внешних источников или предоставляемого пользователем.

См. также Qt Quick Примеры - Элементы изображений и QQuickImageProvider.

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

asynchronous : bool

Указывает, что изображения на локальном файловом хранилище должны загружаться асинхронно в отдельном потоке. Значение по умолчанию — false, что приводит к блокировке потока пользовательского интерфейса во время загрузки изображения. Установка asynchronous в значение true полезна, когда поддержание отзывчивости пользовательского интерфейса предпочтительнее, чем мгновенное отображение изображений.

Обратите внимание, что это свойство применимо только к изображениям, считанным из локального файлового хранилища. Изображения, загруженные через сетевой ресурс (например, HTTP), всегда загружаются асинхронно.

autoTransform : bool

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

По умолчанию это свойство установлено в false.

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

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

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

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

mipmap : bool

Это свойство указывает, использует ли изображение фильтрацию mipmap при масштабировании или преобразовании.

Фильтрация mipmap обеспечивает лучшую визуальную четкость при уменьшении масштаба по сравнению с smooth, но может повлиять на производительность (как при инициализации изображения, так и во время отрисовки).

По умолчанию это свойство установлено в false.

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

См. также smooth.

mirror : bool

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

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

paintedHeight : real

Эти свойства содержат размер изображения, который фактически отрисовывается. В большинстве случаев это совпадает с width и height, но при использовании Image.PreserveAspectFit или Image.PreserveAspectCrop paintedWidth или paintedHeight могут быть меньше или больше, чем width и height элемента Image.

paintedWidth : real

Эти свойства содержат размер изображения, который фактически отрисовывается. В большинстве случаев это совпадает с width и height, но при использовании Image.PreserveAspectFit или Image.PreserveAspectCrop paintedWidth или paintedHeight могут быть меньше или больше, чем width и height элемента Image.

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

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.

verticalAlignment : enumeration

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

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