项目 QML 类型

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

在添加子项或资源时，通常没有必要引用这些属性，因为默认的 data 属性将自动将子对象分配给 children 和 resources 属性。有关详细信息，请参见 data 文档。

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

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

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

定义了项的首选宽度和高度。

如果未指定 width 或 height，则项的有效大小将根据其 implicitWidth 或 implicitHeight 确定。

然而，如果项是 layout 的子项，则布局将确定项的首选大小，使用其隐式大小。在这种情况下，显式的 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 为真，则此项要么是当前接收键盘输入的项，要么是当前接收键盘输入的项的 FocusScope 祖先。

通常，通过设置项及其包含的 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。

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

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

锚点通过指定对象与其他对象之间的关系来定位对象。

边距适用于顶部、底部、左侧、右侧和填充锚点。可以使用 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）强制居中对齐的锚点对齐到整个像素；如果居中的项的宽度或高度是奇数，则项目将在整个像素上定位，而不会放置在半像素上。这确保了项目被清晰地绘制。在某些情况下，这可能不是必要的，例如在旋转项时，中心四舍五入可能会导致抖动。

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

由视觉元素用于决定是否应使用抗锯齿。在某些情况下，启用抗锯齿的项目可能需要更多内存，并且可能渲染得更慢（有关详细信息，请参阅抗锯齿）。

默认值为 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()方法中使用的可选掩码。其主要用途是确定是否已向项中添加指针事件。

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

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

item的contains方法只有在anotherItem的contains实现返回true时才会返回true。

Shape可以用作掩码，使项仅对非矩形区域内的指针事件做出响应

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中定义含有方法。例如，要创建一个圆形项，它仅对其实际边界内的事件做出响应

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属性允许你在项中自由混合视觉子项和资源。如果你将视觉项分配给数据列表，它就成为一个子项；如果你分配任何其他对象类型，就将其添加为资源。

因此，你可以写

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

而不是

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

通常不必引用data属性，因为它默认是项的属性，因此所有子项都自动分配到此属性。

此属性表示项是否接收鼠标和键盘事件。默认情况下为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 和 项层。

保存项目是否分层。分层默认是禁用的。

分层项目渲染到离屏表面并缓存，直到它发生变化。为复杂的 QML 项目层次结构启用分层有时可以是优化。

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

另请参阅项层。

此属性定义了背衬纹理的格式。修改此属性在指定 layer.effect 时最有意义。

另请参阅项层。

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

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

此属性在 Qt 6.5 中引入。

另请参阅项层。

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

另请参阅项层。

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

此值必须与效果的源纹理属性的名称相匹配，以便项能够正确地将分层离屏表面传递给效果。

另请参阅layer.effect、ShaderEffect 和 项层。

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

默认情况下，如果整个窗口启用了多采样，则默认启用多采样，前提是使用的场景图渲染器和底层图形 API 支持此功能。

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

表示层是否进行平滑转换。当启用时，对层的纹理进行采样的操作使用 线性插值 进行，而未平滑则使用 最邻近过滤 模式。

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

另请参阅项层。

此属性定义了应渲染到纹理中的项目矩形区域。源矩形可以大于项目本身。如果矩形为空，即默认值，则将整个项目渲染到纹理中。

另请参阅项层。

此属性定义了生成的纹理应如何进行镜像。默认值是 ShaderEffectSource.MirrorVertically。自定义镜像如果生成的纹理直接由自定义着色器（如由 ShaderEffect 指定）访问时可能很有用。如果对分层项目未指定效果，则镜像对项目的UI表示没有影响。

此属性包含层纹理请求的像素大小。如果它为空，即默认值，则使用项目的尺寸。

另请参阅项层。

此属性定义与纹理关联的包装模式。修改此属性最有意义时，layer.effect 被指定。

另请参阅项层。

此属性包含项的不透明度。不透明度以介于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。

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

此属性描述了项所请求的调色板。调色板在项的样式渲染所有控件时使用，并且可以作为确保自定义控件与本地平台的本地外观和感觉保持一致的手段。不同的平台或不同的样式为应用程序定义不同的调色板是很常见的。

默认调色板取决于系统环境。《a href="qml-qtquick-controls-applicationwindow.html" translate="no">ApplicationWindow 维护一个系统/主题调色板，该调色板作为所有控件的默认值。某些类型的控件可能有特殊的默认调色板。您也可以通过以下方式设置控件的默认调色板：

• 传递自定义调色板给 QGuiApplication::setPalette，在加载任何 QML 之前；或者
• 在 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 状态和Qt Quick中的动画和过渡以获取关于使用状态和过渡的更多详细信息。

另请参阅transitions.

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

有关更多信息，请参阅Transform。

此属性包含围绕该点进行缩放和旋转的来源点。

下面有九个变换来源，默认变换来源是Item.Center。

此示例围绕图像的右下角进行旋转。

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

要设置任意变换来源点，请使用具有transform属性缩放或旋转变换类型。

此属性包含该项目要应用的过渡列表。这些定义了在更改state时应用到项目上的过渡。

此属性指定为一系列Transition对象。例如

import QtQuick 2.0

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

请参阅Qt Quick 状态和Qt Quick中的动画和过渡以获取关于使用状态和过渡的更多详细信息。

另请参阅states.

此属性包含项目是否可见。默认情况下为true。

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

（由于这种级联行为，如果属性绑定应仅对显式属性更改做出响应，则使用visible属性可能不会产生预期效果。在这种情况下，最好使用opacity属性代替。）

如果将该属性设置为 false，则该元素将不再接收鼠标事件，但将继续接收按键事件，并且如果已经设置，将保留键盘 焦点。 （相比之下，将 启用 属性设置为 false 将停止接收鼠标和键盘事件，并且从该元素中移除焦点。）

另请参阅：不透明度 和 启用。

此只读属性列出了当前所有可见的子元素。请注意，子元素的可见性可能已明确更改，或因为此（它的父）元素的可见性或其他祖父母的可见性发生更改。

设置兄弟元素的堆叠顺序。默认堆叠顺序为 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, 宽度, 高度) 映射到此元素坐标系中，并返回一个匹配映射坐标的 点 或 矩形。

在映射中使用以下元素属性： x、y、比例、旋转、变换原点 和 变换。

如果 item 是一个 null 值，则将该点或矩形从 场景 坐标系映射过来。

从 Qt 5.15 版本开始接受点和矩形的版本。

将在此项坐标系统中的点（x，y）或矩形（x，y，width，height）映射到item的坐标系统，并返回匹配映射坐标的点或矩形。

在映射中使用以下元素属性： x、y、比例、旋转、变换原点 和 变换。

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

从 Qt 5.15 版本开始接受点和矩形的版本。

返回位于此项坐标系统中的点（x，y）内第一个可见子项。

如果没有这样的项，则返回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, "")

因此，如果您想了解更多信息，您可以实现自己的函数并向控制台.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、比例、旋转、变换原点 和 变换。

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

在映射中使用以下元素属性： x、y、比例、旋转、变换原点 和 变换。

返回关注链中与该项相邻的项。如果forward为true或者未提供，则为正向方向的下一个项。如果forward为false，则为反向方向的下一个项。