Item QML Type

children 属性包含此项目的可视化子项目列表。resources 属性包含要通过名称引用的非可视化资源。

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

定义项目的位置和大小。默认值为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
    }
}

activeFocus 此只读属性指示项目是否有活动焦点。

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

通常，activeFocus 是通过在项目及其外围FocusScope 对象上设置focus 而获得的。在下面的示例中，input 和focusScope 对象将拥有主动焦点，而根矩形对象则没有。

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

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

该属性用于确定项目是否处于选项卡焦点链中。默认情况下，该属性设置为false 。

标签焦点链遍历元素时，首先访问父元素，然后按照子元素在子属性中出现的顺序访问其子元素。在制表符焦点链中的某个项目上按下制表符键，键盘焦点就会移动到链中的下一个项目。按 BackTab 键（通常为 Shift+Tab）会将焦点移到上一个项目。

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

另请参见 QStyleHints::tabFocusBehavior 和focusPolicy 。

锚点通过指定项目与其他项目的关系来定位项目。

边距适用于顶部、底部、左侧、右侧和填充锚点。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

更多信息请参阅锚点布局。

视觉元素用于决定项目是否应使用抗锯齿。在某些情况下，使用抗锯齿的项目需要更多内存，渲染速度也可能更慢（详情请查看抗锯齿）。

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

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

Text 项目的基线是文本所在的虚线。包含文本的控件通常会将基线设置为文本的基线。

对于非文本项目，默认基线偏移量为 0。

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

如果需要访问项的子项的集合几何图形，以便正确调整项的大小，该属性将非常有用。

返回的几何图形是项目的本地几何图形。例如

Item {
    x: 50
    y: 100

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

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

该属性显示是否启用剪切。默认剪辑值为false 。

如果启用了剪切，项目将剪切其自身的绘制及其子项的绘制，并将其剪切到其边界矩形中。

此属性包含一个项目的可选遮罩，将在contains() 方法中使用。目前，它的主要用途是确定pointer event 是否已降落到项目中。

默认情况下，contains() 方法将对 Item 边界框内的任何点返回 true。containmentMask 允许更精细的控制。例如，如果使用具有专门contains() 方法的自定义 C++QQuickItem 子类作为 containmentMask：

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

item 的 contains 方法将仅在另一个item 的contains() 实现返回true 时才返回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 示例 - 形状。

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

因此，您可以写

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

而不是

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

一般情况下没有必要引用data 属性，因为它是 Item 的默认属性，因此所有子项都会自动分配给该属性。

该属性表示项目是否接收鼠标和键盘事件。默认为 true。

设置该属性会直接影响子项目的enabled 值。当设置为false 时，所有子项目的enabled 值也会变成false 。设置为true 时，子项目的enabled 值将返回到true ，除非已明确设置为false 。

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

另请参阅 visible 。

此属性可确定项目是否在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 中的键盘焦点。

该属性决定了项目接受焦点的方式。

该属性在 Qt 6.7 中引入。

持有应用于该图层的效果。

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

另请参阅 layer.samplerName 和Item Layers 。

显示项目是否分层。分层默认为禁用。

分层项目会被渲染到屏幕外的表面并缓存起来，直到它被更改。对复杂的 QML 项目层次结构启用分层有时是一种优化。

当图层被禁用时，其他图层属性都不会有任何影响。

另请参阅 Item Layers 。

该属性定义了背景纹理的格式。当layer.effect 也被指定时，修改该属性是最合理的。

另请参阅 Item Layers 。

当此属性为 true 时，图层纹理会在项目更新时更新。否则，它将始终是一幅冻结图像。

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

此属性在 Qt 6.5 中引入。

另请参阅 Item Layers 。

如果此属性为 true，则会为纹理生成 mipmaps。

另请参阅 Item Layers 。

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

该值必须与效果的源纹理属性名称相匹配，以便项目能正确地将图层的屏幕外表面传递给效果。

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

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

默认情况下，如果使用的场景图渲染器和底层图形 API 支持多采样，则只要整个窗口启用了多采样，就会启用多采样。

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

保持图层是否平滑变换。启用后，将使用linear 插值对图层纹理进行采样，而非平滑将使用nearest 滤波模式。

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

另请参阅 Item Layers 。

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

另请参阅 Item Layers 。

该属性定义生成的纹理应如何镜像。默认值为ShaderEffectSource.MirrorVertically 。如果自定义着色器（如ShaderEffect 指定的着色器）直接访问生成的纹理，自定义镜像可能会很有用。如果没有为分层项目指定任何效果，镜像对项目的用户界面表现没有任何影响。

此属性用于保存图层纹理的像素大小。如果为空（默认值），则使用项目的大小。

另请参阅 Item Layers 。

该属性定义了与纹理相关的换行模式。在指定layer.effect 时，修改此属性最有意义。

另请参阅 Item Layers 。

此属性用于保存项目的不透明度。不透明度指定为介于 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 。

该属性包含当前为项目设置的调色板。

该属性描述了项目要求的调色板。项目的样式在呈现所有控件时都会使用该调色板，该调色板可确保自定义控件与本地平台的本地外观和感觉保持一致。不同的平台或不同的样式通常会为应用程序定义不同的调色板。

默认调色板取决于系统环境。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 。

该属性保存项的视觉父级。

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

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

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

另请参阅 Transform 和Rotation 。

该属性表示该项目的比例因子。

缩放系数小于 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 。

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

在Qt Quick 2.0 中，该属性对性能的影响很小。

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

该属性包含项目当前状态的名称。

如果项目处于默认状态，即未设置显式状态，则此属性为空字符串。同样，也可以通过将此属性设置为空字符串，将项目恢复到默认状态。

另请参阅 Qt Quick 状态。

此属性包含此项目可能的状态列表。要更改该项目的状态，可将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 StatesandAnimation and Transitions inQt Quick。

另请参阅 transitions 。

此属性包含要应用的变换列表。

该属性以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 。

该属性包含缩放和旋转变换的原点。

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

本示例围绕图像右下角旋转图像。

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

要设置任意变换原点，请使用Scale 或Rotation 变换类型和transform 。

此属性包含此项目的转换列表。它定义了每当项目改变其state 时要应用的变换。

该属性以Transition 对象列表的形式指定。例如

import QtQuick 2.0

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

有关使用状态和转换的更多详情，请参阅Qt Quick StatesandAnimation and Transitions inQt Quick。

另请参阅 states 。

该属性表示项目是否可见。默认为 true。

设置该属性会直接影响子项目的visible 值。当设置为false 时，所有子项目的visible 值也会变成false 。当设置为true 时，子项目的visible 值将返回到true ，除非它们被明确设置为false 。

(由于这种流动行为，如果属性绑定只响应显式属性更改，则使用visible 属性可能达不到预期效果。在这种情况下，最好使用opacity 属性）。

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

另请参阅 opacity 和enabled 。

此只读属性列出了当前可见的项目的所有子项。请注意，子代的可见性可能已明确改变，也可能是因为此（父）项目或另一个祖代的可见性改变了。

设置同级项目的堆叠顺序。默认情况下，堆叠顺序为 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 坐标系中的点 (x,y) 或矩形 (x,y,width,height) 映射到该项目的坐标系，并返回与映射坐标相匹配的point 或rect 。

项目的以下属性将用于映射：x,y,scale,rotation,transformOrigin, 和transform 。

如果项目是不同场景的一部分，则映射包括两个场景的相对位置。

如果item 是null 值，则从场景坐标系映射点或矩形。

接受 point 和 rect 的版本自 Qt 5.15 开始。

将此项目坐标系中的点 (x,y) 或矩形 (x,y,width,height) 映射到item 的坐标系，并返回与映射坐标相匹配的point 或rect 。

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

如果项目是不同场景的一部分，则映射包括两个场景的相对位置。

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

接受 point 和 rect 的版本自 Qt 5.15 开始。

Returns the first visible child item found at point (x,y) within the coordinate system of this item.返回在点 ( , ) 在此项目坐标系内找到的第一个可见子项目。

如果没有子项，则返回null 。

如果此项目包含本地坐标中的point ，则返回true ；否则返回false 。这与在事件传送过程中对QEventPoint 进行命中测试时使用的检查相同，如果设置了containmentMask ，则会受其影响。

以递归方式显示从该项目及其子项目开始的项目可视化树的一些细节。

输出结果与此 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().

强制项目成为焦点。

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

焦点改变的原因将在Qt::OtherFocusReason 中说明。使用重载方法指定焦点原因，以便更好地处理焦点变化。

另请参阅 activeFocus 。

这是一个重载函数。

使用给定的reason 将焦点激活到项目上。

该方法将焦点设置在项目上，并确保对象层次结构中的所有祖先FocusScope 对象也被赋予focus 。

另请参阅 activeFocus 和Qt::FocusReason 。

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

抓取以异步方式进行，抓取完成后会调用 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))
}

将全局坐标系中的点 (x,y) 映射到项目的坐标系中，并返回与映射坐标相匹配的point 。

项目的以下属性将用于映射：x,y,scale,rotation,transformOrigin, 和transform 。

如果项目是不同场景的一部分，则映射包括两个场景的相对位置。

将此项目坐标系中的点 (x,y) 映射到全局坐标系，并返回与映射坐标相匹配的point 。

映射时会用到项目的以下属性：x,y,scale,rotation,transformOrigin, 和transform 。

如果项目属于不同场景的一部分，则映射包括两个场景的相对位置。

返回焦点链中紧邻此项目的项目。如果forward 是true ，或未提供，则是向前方向的下一个项目。如果forward 是false ，则是后向的下一个项目。