BorderImage QML Type

根据图像绘制边框。更多...

• 所有成员的列表，包括继承的成员

属性

• asynchronous : bool
• border
  • border.bottom : int
  • border.left : int
  • border.right : int
  • border.top : int
• cache : bool
• currentFrame : int
• frameCount : int
• horizontalTileMode : enumeration
• mirror : bool
• progress : real
• retainWhileLoading : bool (since 6.8)
• smooth : bool
• source : url
• sourceSize : size
• status : enumeration
• verticalTileMode : enumeration

详细说明

BorderImage 类型用于通过缩放或平铺每张图像的局部区域来生成边框。

BorderImage 会将通过source 属性指定的源图像划分为 9 个区域，如下所示：

当图像被缩放时，源图像的各个区域会通过缩放或平铺的方式，按以下方式生成显示的边框图像：

• 四个角（区域 1、3、7 和 9）完全不进行缩放。
• 区域 2 和 8 根据 `horizontalTileMode` 进行缩放。
• 区域 4 和 6 根据verticalTileMode 进行缩放。
• 中间部分（区域 5）同时根据horizontalTileMode 和verticalTileMode 进行缩放。

图像的区域是通过border 属性组定义的，该属性组描述了源图像各边缘到边框的距离。

使用示例

以下示例展示了不同模式对图像产生的效果。图像上叠加了引导线，以显示上文所述的图像不同区域。

为了进行比较，使用简单的 Image 控件显示了一张未缩放的图像。这里我们叠加了线条，以展示我们希望如何使用 BorderImage 将其分割：

Image {
    source: "pics/borderframe.png"
    anchors.centerIn: parent
}

但当使用 BorderImage 显示图像时，border 属性将用于确定图像中哪些部分位于未缩放的角区域内，哪些部分将被水平和垂直拉伸。 此时，您可以将其尺寸设置为大于原始图像。由于horizontalTileMode 属性设置为BorderImage.Stretch ，区域2和8中的图像部分会被水平拉伸。由于verticalTileMode 属性设置为BorderImage.Stretch ，区域4和6中的图像部分会被垂直拉伸：

BorderImage {
    anchors { fill: parent; margins: 1 }
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Stretch
    verticalTileMode: BorderImage.Stretch
    source: "pics/borderframe.png"
}

同样，使用一个较大的 BorderImage 来显示图像。当horizontalTileMode 属性设置为BorderImage.Repeat 时，图像中第 2 和第 8 区域的部分会被平铺，以填满项目顶部和底部的空间。 同样地，将verticalTileMode 属性设置为BorderImage.Repeat ，因此区域4和6中的图像部分会被平铺以填充项目左右两侧的空间：

BorderImage {
    anchors { fill: parent; margins: 1 }
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Repeat
    verticalTileMode: BorderImage.Repeat
    source: "pics/borderframe.png"
}

在某些情况下，区域 2 和 8 的宽度可能并非源图像中相应区域宽度的精确倍数。同样，区域 4 和 6 的高度也可能并非相应区域高度的精确倍数。如果您使用“BorderImage.Round ”模式，系统将选择整数个平铺块并将其缩小以适应空间：

BorderImage {
    anchors { fill: parent; margins: 6 }
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Round
    verticalTileMode: BorderImage.Round
    source: "pics/borderframe.png"
}

《Qt Quick 示例——图像元素》中的“BorderImage”示例展示了如何利用BorderImage在矩形项目上模拟阴影效果。

图像加载

根据源图像的原始位置不同，源图像可能无法立即加载。可通过progress 属性监控加载进度。

另请参阅 Image 和AnimatedImage 。

属性文档

asynchronous : bool

指定应通过单独的线程异步加载本地文件系统中的图像。默认值为 false，这会导致在加载图像期间用户界面线程被阻塞。当保持用户界面的响应性比立即显示图像更为重要时，将asynchronous 设置为 true 会很有帮助。

请注意，此属性仅对从本地文件系统读取的图像有效。通过网络资源（例如 HTTP）加载的图像始终以异步方式加载。

border group

4条边框线（2条水平线和2条垂直线）将图像划分为9个区域，如下所示：

每条边框线（左、右、上、下）都指定了相对于源图像相应边缘的像素偏移量。默认情况下，每条边框线的值为 0。

例如，以下定义将底边设置为距图像底部向上10像素处：

BorderImage {
    border.bottom: 10
    // ...
}

边框线也可以使用.sci file 进行指定。

cache : bool

指定是否应缓存该图像。默认值为 true。在处理大图像时，将 `cache ` 设置为 false 很有用，这样可以确保不会为了缓存大图像而牺牲小尺寸的“UI 元素”图像的缓存空间。

currentFrame 是当前可见的帧。默认值为0 。如果图像包含多帧，您可以将其设置为0 到frameCount - 1 之间的数值，以显示不同的帧。

frameCount 是图像中的帧数。大多数图像只有一帧。

此属性描述了如何重复或拉伸边框图像的中间部分。

每个属性的默认平铺模式均为BorderImage.Stretch。

mirror : bool

此属性用于控制图像是否应进行水平翻转（即显示镜像图像）。

默认值为 false。

progress : real [read-only]

该属性用于记录图像加载进度，范围从 0.0（未加载）到 1.0（已完成）。

另请参阅 status 。

retainWhileLoading : bool [since 6.8]

该属性定义了在source 属性发生变化且加载以异步方式进行时的工作行为。当asynchronous 属性设置为true 时，或者图像不在本地文件系统上时，即会发生这种情况。

如果retainWhileLoading 的值为false （默认值），则旧图像将立即被丢弃，并在加载新图像期间清空组件。如果设置为true ，则保留旧图像，并使其保持可见，直到新图像准备就绪为止。

启用此属性可在加载新图像耗时较长的情况下避免闪烁。但代价是在加载新图像期间，双缓冲机制会消耗额外的内存。

该属性在 Qt 6.8 中引入。

smooth : bool

该属性控制在缩放或变换图像时是否进行平滑滤波。平滑滤波可提升视觉质量，但在某些硬件上可能会降低运行速度。如果以原始尺寸显示图像，该属性不会对视觉效果或性能产生影响。

默认情况下，此属性设置为 true。

source : url

该属性存储指向源图像的 URL。

BorderImage 可处理 Qt 支持的任何图像格式，并可从 Qt 支持的任何 URL 方案加载。

该属性还可以引用一个.sci 文件——这是一种 QML 专有的基于文本的格式，将边框值、源图像和平铺规则直接嵌入文件中。使用.sci 文件时，BorderImage 会从文件本身读取边框信息，因此无需在 QML 中指定边框属性。

以下 .sci 文件将图像picture.png 的每边边框设置为 10：

border.left: 10
border.top: 10
border.bottom: 10
border.right: 10
source: "picture.png"

URL 可以是绝对路径，也可以是相对于组件 URL 的相对路径。

另请参阅 QQuickImageProvider 。

sourceSize : size [read-only]

该属性存储已加载图像的实际宽度和高度。

在BorderImage 中，该属性为只读。

另请参阅 Image::sourceSize 。

status : enumeration [read-only]

该属性描述了图像加载的状态。其取值可以是以下之一：

另请参阅 progress 。