📚 课程目录第3章使用Image显示图片

3. 使用Image显示图片

任务目标

在QML中加载并显示本地图片，掌握Image元素的基本用法，包括设置显示尺寸、控制缩放模式以及调整透明度。

环境准备

本案例基于Qt 5.15+或Qt 6.x，需要Qt Quick模块。创建一个Qt Quick Application项目，或在现有项目中添加一个.qml文件。准备一张本地测试图片（如photo.jpg），放在与QML文件相同的目录下。

关键实现

使用Image元素加载图片，通过source属性指定图片路径。设置width和height控制显示尺寸，fillMode决定图片如何适应设定的尺寸，opacity控制透明度。以下代码展示了三种常用的fillMode效果对比：

import QtQuick 2.15
import QtQuick.Window 2.15

Window {
    width: 640
    height: 480
    visible: true
    title: "Image 显示示例"

    // 原始尺寸显示（不缩放）
    Image {
        id: originalImage
        source: "photo.jpg"
        x: 10
        y: 10
        width: 200
        height: 150
        fillMode: Image.PreserveAspectFit
        opacity: 1.0
    }

    // 拉伸填充（可能变形）
    Image {
        source: "photo.jpg"
        x: 220
        y: 10
        width: 200
        height: 150
        fillMode: Image.Stretch
        opacity: 0.8
    }

    // 裁剪填充（保持比例并填满）
    Image {
        source: "photo.jpg"
        x: 430
        y: 10
        width: 200
        height: 150
        fillMode: Image.PreserveAspectCrop
        opacity: 0.5
    }

    // 文字说明
    Text {
        x: 10
        y: 170
        text: "PreserveAspectFit (opacity 1.0)"
        font.pixelSize: 12
    }
    Text {
        x: 220
        y: 170
        text: "Stretch (opacity 0.8)"
        font.pixelSize: 12
    }
    Text {
        x: 430
        y: 170
        text: "PreserveAspectCrop (opacity 0.5)"
        font.pixelSize: 12
    }
}

运行与验证

将上述代码保存为main.qml，确保photo.jpg位于同一目录。
使用qmlscene main.qml命令（Qt 5）或通过Qt Creator直接运行项目（Qt 6）。
观察窗口中的三张图片：

第一张完整显示整张图片，保持宽高比，不裁剪，可能留有空白。
第二张被拉伸至200×150，若原图比例不同则会发生变形。
第三张保持比例并填满200×150区域，超出部分被裁剪。
三张图片透明度依次为1.0、0.8、0.5，背景应能透出。

通过条件：窗口正常显示三张不同效果的图片，且透明度差异清晰可见。若图片未加载，检查source路径是否正确，或使用路径测试。

关键点说明

fillMode的默认值为Image.Stretch，即默认会拉伸图片以适应设定的宽高。
PreserveAspectFit会保持比例并完整显示图片，但可能产生空白区域。
PreserveAspectCrop保持比例并填满整个区域，但会裁剪超出部分。
opacity取值范围为0.0（完全透明）到1.0（不透明）。
若需要加载网络图片，source可直接使用URL字符串，但本案例聚焦本地图片加载。