Item QML Type

一种基本的 QML 可视化类型。更多内容...

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

属性

• activeFocus : bool
• activeFocusOnTab : bool
• anchors
  • anchors.alignWhenCentered : bool
  • anchors.baseline : AnchorLine
  • anchors.baselineOffset : real
  • anchors.bottom : AnchorLine
  • anchors.bottomMargin : real
  • anchors.centerIn : Item
  • anchors.fill : Item
  • anchors.horizontalCenter : AnchorLine
  • anchors.horizontalCenterOffset : real
  • anchors.left : AnchorLine
  • anchors.leftMargin : real
  • anchors.margins : real
  • anchors.right : AnchorLine
  • anchors.rightMargin : real
  • anchors.top : AnchorLine
  • anchors.topMargin : real
  • anchors.verticalCenter : AnchorLine
  • anchors.verticalCenterOffset : real
• antialiasing : bool
• baselineOffset : int
• children : list<Item>
• childrenRect
  • childrenRect.height : real
  • childrenRect.width : real
  • childrenRect.x : real
  • childrenRect.y : real
• clip : bool
• containmentMask : QObject*
• data : list<QtObject>
• enabled : bool
• focus : bool
• focusPolicy : enumeration (since 6.7)
• height : real
• implicitHeight : real
• implicitWidth : real
• layer.effect : Component
• layer.enabled : bool
• layer.format : enumeration
• layer.live : bool (since 6.5)
• layer.mipmap : bool
• layer.samplerName : string
• layer.samples : enumeration
• layer.smooth : bool
• layer.sourceRect : rect
• layer.textureMirroring : enumeration
• layer.textureSize : size
• layer.wrapMode : enumeration
• mutabilityGroup : int (since 6.12)
• opacity : real
• palette : Palette (since 6.0)
• parent : Item
• resources : list<QtObject>
• rotation : real
• scale : real
• smooth : bool
• state : string
• states : list<State>
• transform : list<Transform>
• transformOrigin : enumeration
• transitions : list<Transition>
• visible : bool
• visibleChildren : list<Item>
• width : real
• x : real
• y : real
• z : real

方法

• Item childAt(real x, real y)
• bool contains(point point)
• void dumpItemTree() (since 6.3)
• void forceActiveFocus()
• void forceActiveFocus(Qt::FocusReason reason)
• bool grabToImage(callback, targetSize)
• point mapFromGlobal(real x, real y)
• point mapFromItem(Item item, point p)
• rect mapFromItem(Item item, rect r)
• point mapFromItem(Item item, real x, real y)
• rect mapFromItem(Item item, real x, real y, real width, real height)
• point mapToGlobal(real x, real y)
• point mapToItem(Item item, point p)
• rect mapToItem(Item item, rect r)
• point mapToItem(Item item, real x, real y)
• rect mapToItem(Item item, real x, real y, real width, real height)
• Item nextItemInFocusChain(bool forward)

详细说明

Item 类型是Qt Quick 中所有视觉项的基础类型。

Qt Quick 中的所有可视化项都继承自 Item。虽然 Item 对象本身没有可视化外观，但它定义了所有可视化项共有的属性，例如 x 和 y 位置、宽度和高度、锚点以及键处理支持。

Item 类型可用于将多个项归入单个根可视项之下。例如：

import QtQuick 2.0

Item {
    Image {
        source: "tile.png"
    }
    Image {
        x: 80
        width: 100
        height: 100
        source: "tile.png"
    }
    Image {
        x: 190
        width: 100
        height: 100
        fillMode: Image.Tile
        source: "tile.png"
    }
}

事件处理

所有基于 Item 的视觉类型均可使用输入处理程序（QInputEvent 的子类）来处理传入的输入事件，例如鼠标、触摸和键盘事件。这是处理事件的首选声明式方法。

处理触摸事件的另一种方法是继承 `QQuickItem` 类，在构造函数中调用 `setAcceptTouchEvents()`，并重写 `touchEvent()` 方法。通过 `Accept ` 捕获整个事件，以阻止事件传递给下级项，并独占捕获该事件的所有触摸点。使用 `QPointerEvent::setExclusiveGrabber()` 仅捕获特定的触摸点，并允许事件继续传递。

同样地，QQuickItem 的子类可以调用setAcceptedMouseButtons()来注册接收鼠标按钮事件，调用setAcceptHoverEvents()来接收悬停事件（未按下按钮时的鼠标移动），并重写虚拟函数mousePressEvent()、mouseMoveEvent()和mouseReleaseEvent()。 这些类还可以接受事件以阻止其进一步传递，同时隐式地捕获该事件；或者显式地通过 `grab ` 捕获 `QMouseEvent ` 携带的单个 `QEventPoint `。

所有基于 Item 的可视化类型均可通过Keys 附加属性进行键盘处理。Keys附加属性提供了pressed 和released 等基本信号，以及针对特定键的信号，例如spacePressed 。下面的示例将键盘焦点分配给该项，并通过通用onPressed 处理程序处理左键，通过onReturnPressed 处理程序处理回车键：

import QtQuick 2.0

Item {
    focus: true
    Keys.onPressed: (event)=> {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
    Keys.onReturnPressed: console.log("Pressed return");
}

有关详细文档，请参阅Keys 附加属性。

布局镜像

可通过LayoutMirroring 附加属性对项的布局进行镜像处理。这会使anchors 水平反转，同时也会导致那些对子项进行布局或定位的项（例如ListView 或Row ）将其布局方向水平反转。

更多详细信息请参阅LayoutMirroring 。

项层

通常情况下，一个项会直接渲染到其所属的窗口中。但是，通过设置 `layer.enabled`，可以将该项及其整个子树委托给一个离屏表面。随后，只有该离屏表面（即纹理）才会被绘制到窗口中。

若希望纹理尺寸与项本身不同，可通过layer.textureSize 实现。若仅需将项的一部分渲染到纹理中，请使用layer.sourceRect 。还可以指定layer.sourceRect ，使其超出项的边界。在此情况下，外部区域将用透明像素填充。

如果将layer.smooth 设置为true ，该项将使用线性插值进行缩放；如果将layer.mipmap 设置为true ，则将使用Mipmap进行下采样。Mipmap技术可能提高下采样后项的视觉质量。对于单个Image项的Mipmap处理，建议使用Image::mipmap 。

图层不透明度与项目不透明度

当将opacity 应用于项目层次结构时，不透明度会分别应用于每个项目。当不透明度应用于子树时，这可能会导致不理想的视觉效果。请考虑以下示例：

非分层不透明度 Item { id: nonLayered opacity: 0.5 width: 100 height: 100 Rectangle { width: 80; height: 80; border.width: 1 } Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 } }

渲染图层时，根项的不透明度设为 1，随后在绘制时将根项的不透明度应用于纹理。这意味着，在大型项层次结构中，从透明渐变为不透明，或反之，均可实现，且不会出现常规逐项 alpha 混合所产生的重叠伪影。 以下是启用分层后的相同示例：

Item {
    id: layered

    opacity: 0.5

    layer.enabled: true

    width: 100
    height: 100

    Rectangle { width: 80; height: 80; border.width: 1 }
    Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 }
}

与 ShaderEffects 结合使用

将layer.enabled 设置为true会将该项转换为texture provider ，从而使其能够直接作为纹理使用，例如与ShaderEffect 类型结合使用。

可以通过 layer.effect 在运行时对图层应用特效：

Item {
    id: layerRoot
    layer.enabled: true
    layer.effect: ShaderEffect {
        fragmentShader: "effect.frag.qsb"
    }
}

有关使用效果的更多信息，请参阅ShaderEffect 。

内存与性能

当项目的图层被启用时，场景图将在 GPU 中分配与 `width x height x 4` 相当的内存。在内存受限的配置中，应谨慎使用大型图层。

在QPainter /QWidget 的环境中，有时将复杂内容缓存到像素图、图像或纹理中会更有利。而在Qt Quick 中，由于场景图渲染器已应用的相关技术，在大多数情况下并不需要这样做。 由于批处理机制，过多的绘制调用已被有效减少，而缓存通常会导致需要混合的像素数量超过原始内容。因此，渲染到离屏区域的开销以及绘制最终纹理时涉及的混合操作，往往比直接让该项及其子项正常渲染更为耗费资源。

此外，使用图层的对象在渲染过程中无法进行批处理。这意味着包含大量图层对象的场景可能会出现性能问题。

分层功能对于视觉特效而言既方便又实用，但在大多数情况下，应仅在特效持续期间启用该功能，并在特效结束后将其禁用。

属性文档

activeFocus : bool [read-only]

此只读属性用于指示该项目是否处于活动焦点状态。

如果 activeFocus 为 true，则表示该项要么是当前接收键盘输入的项，要么是当前接收键盘输入的项的FocusScope 祖先。

通常，通过在项目及其包含的FocusScope 对象上设置focus 来获得activeFocus。在下面的示例中，input 和focusScope 对象将具有活动焦点，而根矩形对象则不会。

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

另请参阅《 Qt Quick 》中的focus 和键盘焦点。

activeFocusOnTab : bool

该属性用于指定该项是否希望加入Tab键焦点链。默认情况下，该属性设置为false 。

Tab 焦点链遍历元素时，会先访问父元素，然后按 `children` 属性中元素出现的顺序访问其子元素。在 Tab 焦点链中的某个项目上按下 Tab 键，将把键盘焦点移至链中的下一个项目；按下 BackTab（通常为 Shift+Tab）将把焦点移至上一个项目。

要设置手动 Tab 焦点链，请参阅KeyNavigation 。由 Keys 或KeyNavigation 使用的 Tab 键事件优先于焦点链行为；请忽略其他键处理程序中的事件，以允许焦点传播。

另请参阅 QStyleHints::tabFocusBehavior 和focusPolicy 。

anchors group

锚点通过指定项目与其他项目之间的关系，提供了一种定位项目的方法。

边距适用于顶部、底部、左侧、右侧和填充锚点。anchors.margins 属性可用于一次性将所有边距统一设置为同一值。它不会覆盖先前已设置的特定边距；若要清除显式设置的边距，请将其值设为undefined 。请注意，边距是针对特定锚点的，如果项目未使用锚点，则不会应用边距。

偏移量适用于水平居中、垂直居中和基线锚点。

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.horizontalCenter: pic.horizontalCenter
        anchors.top: pic.bottom
        anchors.topMargin: 5
        // ...
    }
}

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.left: pic.right
        anchors.leftMargin: 5
        // ...
    }
}

anchors.fill 提供了一种便捷的方式，使一个项目具有与另一个项目相同的几何形状，这相当于连接所有四个方向锚点。

要清除锚点值，请将其设置为undefined 。

anchors.alignWhenCentered (默认值为 `true`) 强制居中锚点对齐到整像素；如果要居中的项目具有奇数值的 `width ` 或 `height`，该项目将被定位在整像素上，而不是半像素处。这确保了项目能够清晰地绘制出来。 在某些情况下，这种行为并不理想，例如在旋转项目时，由于中心位置被四舍五入，可能会出现抖动现象。

有关更多信息，请参阅“锚点布局”。

antialiasing : bool

由视觉元素用于决定该项是否应使用抗锯齿。在某些情况下，启用抗锯齿的项会占用更多内存，且渲染速度可能会变慢（更多详情请参阅“抗锯齿”）。

默认值为 false，但可由派生元素覆盖。

baselineOffset : int

指定项目基线在本地坐标系中的位置。

Text 对象的基线是文本所在的假想线。包含文本的控件通常将其基线设置为文本的基线。

对于非文本项目，将使用默认的基线偏移量 0。

“children” 属性包含该项的视觉子项列表。“resources” 属性包含您希望按名称引用的非视觉资源。

在添加子项或资源时，通常无需引用这些属性，因为默认的data 属性会根据需要自动将子对象分配给children 和resources 属性。详情请参阅data 文档。

childrenRect group

此只读属性存储了该项子项的集合位置和大小。

若需访问项目子节点的集合几何信息以正确调整项目大小，此属性将非常有用。

返回的几何信息仅针对该项本身。例如：

Item {
    x: 50
    y: 100

    // prints: QRectF(-10, -20, 30, 40)
    Component.onCompleted: print(childrenRect)

    Item {
        x: -10
        y: -20
        width: 30
        height: 40
    }
}

clip : bool

无论是否启用了裁剪，此属性均有效。默认裁剪值为false 。

如果启用了裁剪，则项目会将其自身的绘制内容及其子节点的绘制内容裁剪至其边界矩形内。

containmentMask : QObject*

该属性保存了该项的可选遮罩，用于在contains()方法中使用。其目前的主要用途是判断pointer event 是否落入了该项中。

默认情况下，对于位于 Item 边界框内的任何点，contains() 方法都会返回 true。containmentMask 则允许进行更精细的控制。例如，如果将一个具有特化contains() 方法的自定义 C++QQuickItem 子类用作 containmentMask：

Item { id: item; containmentMask: AnotherItem { id: anotherItem } }

则只有当另一个项（anotherItem）的`contains()` 实现返回 `true` 时，该项的`contains` 方法才会返回 `true `。

Shape 可作为掩码使用，使项仅在非矩形区域内对 `pointer events ` 做出响应：

Rectangle { width: 90; height: 100 color: hoverHandler.hovered ? "wheat" : "lightgray" containmentMask: shape HoverHandler { id: hoverHandler } Shape { id: shape containsMode: Shape.FillContains ShapePath { fillColor: "lightsteelblue" startX: 10; startY: 20 PathArc { x: 10; y: 80 radiusX: 40; radiusY: 40 useLargeArc: true } PathLine { x: 10; y: 20 } } } }

还可以在 QML 中定义 contains 方法。例如，要创建一个仅对其实际边界内的事件做出响应的圆形项：

Rectangle { id: circle width: 100; height: width radius: width / 2 color: tapHandler.pressed ? "tomato" : hoverHandler.hovered ? "darkgray" : "lightgray" TapHandler { id: tapHandler } HoverHandler { id: hoverHandler } containmentMask: QtObject { property alias radius: circle.radius function contains(point: point) : bool { return (Math.pow(point.x - radius, 2) + Math.pow(point.y - radius, 2)) < Math.pow(radius, 2) } } }

另请参阅 《Qt Quick 示例——形状》。

data : list<QtObject> [default]

“数据”属性允许您在项目中自由混合视觉子元素和资源。如果您将一个视觉项分配给数据列表，它就会成为子元素；如果您分配任何其他类型的对象，它则会被添加为资源。

因此，您可以这样编写：

Item {
    Text {}
    Rectangle {}
    Timer {}
}

而不是：

Item {
    children: [
        Text {},
        Rectangle {}
    ]
    resources: [
        Timer {}
    ]
}

通常无需引用 `data ` 属性，因为它是 `Item` 的默认属性，因此所有子项都会自动分配给该属性。

enabled : bool

该属性控制项目是否接收鼠标和键盘事件。默认情况下，该属性值为true 。

当设置为false 时，该控件不会接收键盘或指针设备事件（如按下、释放或点击），但仍可接收悬停事件。

设置此属性会直接影响子项的enabled 值。当设置为false 时，所有子项的enabled 值也将变为false 。当设置为true 时，子项的enabled 值将恢复为true ，除非它们已被显式设置为false 。

将此属性设置为false 会自动导致activeFocus 被设置为false ，且该项将不再接收键盘事件。

另请参阅 visible 。

focus : bool

该属性控制该项目在所包含的FocusScope 中是否具有焦点。如果为true，当所包含的FocusScope 获得活动焦点时，该项目也将获得活动焦点。

在下面的示例中，当scope 获得活动焦点时，input 将获得活动焦点：

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

就该属性而言，整个场景被视为一个焦点范围。实际上，这意味着以下 QML 代码将在启动时将活动焦点赋予input 。

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

另请参阅 activeFocus 以及 Qt Quick 中的“键盘焦点”。

focusPolicy : enumeration [since 6.7]

此属性决定了该控件接受焦点的模式。

该属性在 Qt 6.7 中引入。

定义项的位置和大小。默认值为0 。

(x,y) 位置相对于parent 。

Item { x: 100; y: 100; width: 100; height: 100 }

定义项的首选宽度或高度。

如果未指定 `width ` 或 `height `，则项的有效大小将由其 `implicitWidth ` 或 `implicitHeight` 决定。

但是，如果某个项是布局的子项，则布局将使用其隐式尺寸来确定该项的首选尺寸。在这种情况下，显式的width 或height 将被忽略。

大多数项目的默认隐式大小为 0x0，但某些项目具有固有的隐式大小，无法被覆盖，例如Image 和Text 。

设置隐式大小有助于定义根据内容具有首选大小的组件，例如：

// Label.qml
import QtQuick 2.0

Item {
    property alias icon: image.source
    property alias label: text.text
    implicitWidth: text.implicitWidth + image.implicitWidth
    implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
    Image { id: image }
    Text {
        id: text
        wrapMode: Text.Wrap
        anchors.left: image.right; anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
    }
}

layer.effect : Component

保存应用于该图层的效果。

该效果通常是ShaderEffect 组件，但也可以分配任何Item 组件。该效果应具有一个源纹理属性，其名称需与layer.samplerName 匹配。

另请参阅 layer.samplerName 和Item Layers 。

layer.enabled : bool

表示该项是否启用了分层。默认情况下，分层功能处于禁用状态。

分层项会被渲染到屏幕外的表面并缓存，直到其发生变化为止。对于复杂的 QML 项层次结构，启用分层有时可以起到优化作用。

当分层功能被禁用时，其他所有分层属性均不生效。

另请参阅 Item Layers 。

layer.format : enumeration

该属性定义了底纹的格式。当同时指定了layer.effect 时，修改此属性最为合理。

另请参阅 Item Layers 。

layer.live : bool [since 6.5]

当此属性为 true 时，每当项目更新，图层纹理也会随之更新。否则，它将始终显示为静止图像。

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

该属性在 Qt 6.5 中引入。

另请参阅 Item Layers 。

layer.mipmap : bool

如果此属性为真，则会为该纹理生成米普图。

另请参阅 Item Layers 。

layer.samplerName : string

存储效果的源纹理属性的名称。

该值必须与效果的源纹理属性名称一致，以便该项能够正确地将图层的离屏表面传递给效果。

另请参阅 layer.effect 、ShaderEffect 和Item Layers 。

layer.samples : enumeration

此属性允许在图层中请求多采样渲染。

默认情况下，当整个窗口启用了多采样时，该属性也会被启用，前提是所使用的场景图渲染器和底层图形 API 支持此功能。

通过将该值设置为 2、4 等，可以在不为整个场景启用多采样的情况下，为场景的一部分请求多采样渲染。这样，多采样仅应用于给定的子树，由于多采样不应用于场景的其他部分，因此可以显著提高性能。

layer.smooth : bool

用于指定图层是否进行平滑变换。启用时，对图层纹理的采样将采用linear 插值法；若未启用，则采用nearest 过滤模式。

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

另请参阅 Item Layers 。

layer.sourceRect : rect

该属性定义了应渲染到纹理中的项的矩形区域。源矩形可以比项本身更大。如果矩形为空（这是默认值），则整个项都会渲染到纹理中。

另请参阅 Item Layers 。

layer.textureMirroring : enumeration

此属性定义了生成的纹理应如何进行镜像处理。默认值为“ShaderEffectSource.MirrorVertically ”。如果生成的纹理被自定义着色器直接访问（例如由ShaderEffect 指定的着色器），则自定义镜像处理会很有用。如果未为分层项指定效果，则镜像处理不会影响该项在用户界面中的显示效果。

layer.textureSize : size

该属性存储图层纹理的请求像素尺寸。如果为空（这是默认情况），则使用该项的尺寸。

另请参阅 Item Layers 。

layer.wrapMode : enumeration

此属性定义了与纹理相关的环绕模式。当指定了“layer.effect ”时，修改此属性最为合理。

另请参阅 Item Layers 。

mutabilityGroup : int [since 6.12]

这是一个高级属性，可用于低级优化。它向渲染器提供提示，说明一个项将被更新的频率。在典型用例中，将此属性保留为默认值（Item.AutoMutabilityGroup （0 ））即可满足需求。

然而，在某些情况下，性能分析可能会发现一些瓶颈，而Qt Quick 场景图渲染器的默认行为无法对此进行优化。 通常，当快速更新的几何体与静态几何体被批量渲染时，就会发生这种情况。为避免此问题，您可以尝试将快速更新的组件分配给 Item.DynamicMutabilityGroup。来自不同可变性组的几何体不会被批量渲染在一起。

可变性组仅适用于项目本身，不会传播到子项。

有关“ Qt Quick ”场景图渲染器的内部工作原理以及几何体批处理的更多信息，请参阅《Qt Quick 场景图默认渲染器》。

预定义值：

该属性在 Qt 6.12 中引入。

opacity : real

该属性存储了项的不透明度。不透明度以介于 0.0（完全透明）和 1.0（完全不透明）之间的数值指定。默认值为 1.0。

设置此属性时，指定的不透明度也会单独应用于子项。在某些情况下，这可能会产生意想不到的效果。例如，在下图中的第二组矩形中，红色矩形指定了 0.5 的不透明度，这会影响其蓝色子矩形的不透明度，即使该子矩形未指定不透明度。

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

更改项目的透明度不会影响该项目是否接收用户输入事件。（相比之下，将visible 属性设置为false 会阻止鼠标事件；将enabled 属性设置为false 会阻止鼠标和键盘事件，并会移除该项目的活动焦点。）

另请参阅 visible 。

palette : Palette [since 6.0]

该属性存储当前为该项设置的配色方案。

该属性描述了该项请求的配色方案。该配色方案在渲染所有控件时由该项的样式使用，并可作为一种手段，确保自定义控件能与原生平台的原生外观和风格保持一致。通常情况下，不同的平台或不同的样式会为应用程序定义不同的配色方案。

默认配色方案取决于系统环境。`ApplicationWindow ` 维护着一个系统/主题配色方案，作为所有控件的默认配色方案。某些类型的控件可能还有特殊的默认配色方案。您还可以通过以下任一方式为控件设置默认配色方案：

• 在加载任何 QML 之前，向 `QGuiApplication::setPalette()` 传递自定义调色板；或者
• 在qtquickcontrols2.conf 文件中指定颜色。

项目会将显式调色板属性从父项传播到子项。如果您更改了项目调色板中的某个特定属性，该属性将传播到该项目的所有子项，并覆盖该属性的一切系统默认值。

Item {
    palette {
        buttonText: "maroon"
        button: "lavender"
    }

    Button {
        text: "Click Me"
    }
}

该属性在 Qt 6.0 中引入。

另请参阅 Window::palette 、Popup::palette 、ColorGroup 、Palette 以及SystemPalette 。

parent : Item

该属性存储了该项的视觉父项。

rotation : real

该属性表示项目围绕其transformOrigin 顺时针旋转的度数。

默认值为 0 度（即未旋转）。

Rectangle {
    color: "blue"
    width: 100; height: 100
    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        rotation: 30
    }
}

另请参阅 Transform 和Rotation 。

scale : real

该属性存储了该项的缩放因子。

缩放因子小于 1.0 时，该元素将以较小的尺寸渲染；缩放因子大于 1.0 时，该元素将以较大的尺寸渲染。负缩放因子会导致该元素在渲染时被镜像。

默认值为 1.0。

缩放从transformOrigin 开始应用。

import QtQuick 2.0

Rectangle {
    color: "blue"
    width: 100; height: 100

    Rectangle {
        color: "green"
        width: 25; height: 25
    }

    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        scale: 1.4
        transformOrigin: Item.TopLeft
    }
}

另请参阅 Transform 和Scale 。

smooth : bool

主要用于基于图像的项目，用于决定该项目是否应使用平滑采样。平滑采样采用线性插值，而非平滑采样则采用最近邻插值。

在Qt Quick 2.0中，此属性对性能的影响微乎其微。

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

state : string

该属性存储了该项当前状态的名称。

如果项目处于默认状态（即未显式设置任何状态），则该属性保存一个空字符串。同样，您可以通过将该属性设置为空字符串，将项目恢复为默认状态。

另请参阅 Qt Quick 状态。

states : list<State>

该属性保存了该项的所有可能状态列表。要更改该项的状态，请将state 属性设置为这些状态之一；若要将该项恢复为默认状态，请将state 属性设置为空字符串。

该属性指定为一个由State 对象组成的列表。例如，下面是一个具有“red_color”和“blue_color”状态的项目：

import QtQuick 2.0

Rectangle {
    id: root
    width: 100; height: 100

    states: [
        State {
            name: "red_color"
            PropertyChanges { root.color: "red" }
        },
        State {
            name: "blue_color"
            PropertyChanges { root.color: "blue" }
        }
    ]
}

有关使用状态和过渡的更多详细信息，请参阅《Qt Quick 状态》以及《 Qt Quick 中的动画和过渡》。

另请参阅 transitions 。

transform : list<Transform> [read-only]

该属性存储要应用的变换列表。

该属性指定为由Transform 派生而来的对象列表。例如：

import QtQuick

Image {
    source: "images/qt-logo.png"
    transform: [
        Scale { origin.x: 25; origin.y: 25; xScale: 1.25 },
        Rotation { origin.x: 45; origin.y: 55; angle: 45 }
    ]
}

有关详细信息，请参阅Transform 。

transformOrigin : enumeration

该属性存储了缩放和旋转变换的原点。

如下图所示，共有九种变换原点可供选择。默认的变换原点为Item.Center 。

本示例将图像围绕其右下角进行旋转。

Image {
    source: "myimage.png"
    transformOrigin: Item.BottomRight
    rotation: 45
}

若要设置任意的变换原点，请使用Scale 或Rotation 变换类型，并配合transform 使用。

transitions : list<Transition>

该属性保存了该项的过渡列表。这些过渡定义了每当该项的“state ”发生变化时，将对其应用的过渡效果。

该属性指定为一组Transition 对象的列表。例如：

import QtQuick 2.0

Item {
    transitions: [
        Transition {
            //...
        },
        Transition {
            //...
        }
    ]
}

有关使用状态和转场的更多详细信息，请参阅 Qt Quick 中的“ Qt Quick 状态”以及“动画和转场”。

另请参阅 states 。

visible : bool

该属性用于控制项目是否可见。默认值为 true。

设置此属性会直接影响子项的visible 值。当设置为false 时，所有子项的visible 值也会变为false 。当设置为true 时，子项的visible 值将恢复为true ，除非它们已被显式设置为false 。

（由于这种连锁行为，如果属性绑定仅应响应显式的属性更改，则使用visible 属性可能无法达到预期效果。在这种情况下，最好改用opacity 属性。）

如果将此属性设置为 `false`，该项目将不再接收鼠标事件，但将继续接收键盘事件，并且如果已设置键盘 `focus `，则会保留该设置。（相比之下，将 `enabled ` 属性设置为 `false ` 会同时阻止鼠标和键盘事件，并移除该项目的焦点。）

另请参阅 opacity 和enabled 。

visibleChildren : list<Item>

此只读属性列出了该项目当前可见的所有子项。请注意，子项的可见性可能是被显式更改的，也可能是由于该子项（即其父项）或某个其他祖先项的可见性发生了变化而导致的。

z : real

设置同级元素的堆叠顺序。默认情况下，堆叠顺序为 0。

堆叠值较高的项目会显示在堆叠值较低的同级项目之上。堆叠值相同的项目将按其出现的顺序从上到下显示。堆叠值为负的项目会显示在其父级内容之下。

以下示例展示了堆叠顺序的各种效果。

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        z: 1
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            z: -1
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

方法文档

Item childAt(real x, real y)

返回在该项的坐标系内，位于坐标点 (x,y) 处找到的第一个可见子项。

如果不存在此类项，则返回null 。

bool contains(point point)

如果该项包含以本地坐标系表示的point ，则返回true ；否则返回false 。此检查与事件传递过程中对QEventPoint 进行碰撞检测时使用的检查相同，且若containmentMask 已设置，则会受到其影响。

[since 6.3] void dumpItemTree()

递归地输出以该项及其子项为起点的项的视觉树的相关详细信息。

输出结果与以下 QML 代码的输出类似：

function dump(object, indent) {
    console.log(indent + object)
    for (const i in object.children)
        dump(object.children[i], indent + "    ")
}

dump(myItem, "")

因此，若需获取更多详细信息，您可以实现自定义函数，并在 `console.log` 中添加额外输出，例如特定属性的值。

该方法在 Qt 6.3 中引入。

另请参阅 QObject::dumpObjectTree()。

void forceActiveFocus()

将焦点强制转移到该项目上。

此方法将焦点设置为该项，并确保对象层次结构中所有祖先FocusScope 对象也获得focus 。

焦点变化的原因将设置为Qt::OtherFocusReason 。请使用重载方法指定焦点原因，以便更好地处理焦点变化。

另请参阅 activeFocus 。

void forceActiveFocus(Qt::FocusReason reason)

将焦点主动移至具有指定reason 的项上。

此方法将焦点设置在该项上，并确保对象层次结构中所有祖先FocusScope 对象也获得focus 。

另请参阅 activeFocus 和Qt::FocusReason 。

bool grabToImage(callback, targetSize)

将项目抓取到内存图像中。

抓取操作以异步方式进行，当抓取完成时，将调用 JavaScript 函数 `callback `。该回调函数接受一个参数，即抓取操作的结果——一个 `ItemGrabResult ` 对象。

使用 `targetSize ` 指定目标图像的尺寸。默认情况下，结果图像的尺寸将与该项目相同。

如果无法启动截图操作，该函数将返回false 。

以下代码片段演示了如何抓取项目并将结果保存到文件中：

Rectangle {
    id: sourceRectangle
    width: 100
    height: 100
    focus: true
    gradient: Gradient {
        GradientStop { position: 0; color: "steelblue" }
        GradientStop { position: 1; color: "black" }
    }

    Keys.onSpacePressed: {
        sourceRectangle.grabToImage(function(result) {
           result.saveToFile("something.png")
        })
    }
}

以下代码片段演示了如何抓取项目并将结果用于另一个图像元素：

Image {
    id: image
}

Keys.onSpacePressed: {
    sourceRectangle.grabToImage(function(result) {
        image.source = result.url
    }, Qt.size(50, 50))
}

point mapFromGlobal(real x, real y)

将位于全局坐标系中的点（x ，y ）映射到项的坐标系，并返回一个与映射坐标匹配的point 。

映射过程中会使用项的以下属性：x 、y 、scale 、rotation 、transformOrigin 和transform 。

如果这些项目属于不同的场景，则映射信息中包含两个场景之间的相对位置。

将位于item 坐标系中的点（x 、y ）或矩形（x 、y 、width 、height ）映射到该项的坐标系中，并返回一个与映射坐标匹配的point 或rect 。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些对象属于不同的场景，则映射结果将包含两个场景之间的相对位置。

如果 `item ` 是 `null ` 类型的值，则会将该点或矩形从场景的坐标系中映射出来。

支持点和矩形作为参数的版本自 Qt 5.15 起提供。

point mapToGlobal(real x, real y)

将位于该项坐标系中的点（x ，y ）映射到全局坐标系，并返回一个与映射坐标匹配的point 。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射信息中包含这两个场景之间的相对位置。

将位于该项坐标系中的点（x 、y ）或矩形（x 、y 、width 、height ）映射到item 的坐标系中，并返回与映射坐标对应的point 或rect 。

映射过程中会使用项目的以下属性：x 、y 、scale 、rotation 、transformOrigin 和transform 。

如果这些对象属于不同的场景，则映射会包含两个场景之间的相对位置。

如果 `item ` 是 `null ` 类型，则会将点或矩形映射到场景的坐标系中。

支持 point 和 rect 参数的版本自 Qt 5.15 起提供。

Item nextItemInFocusChain(bool forward)

返回焦点链中紧邻该项的下一项。如果forward 的值为true ，或者未提供该参数，则返回向前方向上的下一项；如果forward 的值为false ，则返回向后方向上的下一项。