QML Item 类型

Item QML Type

• Qt官方文档：https://doc.qt.io/qt-5/qml-qtquick-item.html

详细说明

• item类型是Qt Quick中所有可视项目的基本类型。Qt Quick中的所有可视化项目都继承自Item。
• 尽管Item对象没有可视化外观，但它定义了可视化项目中常见的所有属性，如x和y位置、宽度和高度、锚定和键处理支持。
• Item类型对于将多个item分组到单个根可视化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的可视化类型都可以使用Input Handlers来处理传入的输入事件(QInputEvent的子类)，如鼠标、触摸和按键事件。这是处理事件的首选声明性方法。
• 处理触摸事件的另一种方法是子类化QQuickItem，在构造函数中调用setAcceptTouchEvents()，并覆盖touchEvent()。接受整个事件以停止向下面的项目交付，并独占地获取所有事件的接触点。
• 同样，QQuickItem子类可以调用setAcceptedMouseButtons()来注册接收鼠标按钮事件，setAcceptHoverEvents()来接收鼠标悬空事件(没有按钮被按下时鼠标移动)，并覆盖虚拟函数mousePressEvent()、mouseMoveEvent()和mouseReleaseEvent()。它们还可以接受事件以防止进一步交付，同时获得隐式抓取。
• Key处理可通过Keys附加属性用于所有基于item的可视类型。
  • Keys attached属性提供了按下和释放等基本信号，以及特定键的信号，如spacePressed。
  • 下面的例子将键盘焦点分配给item，并通过常规的onPressed处理程序处理左键，通过onReturnPressed处理程序处理返回键:

import QtQuick 2.0

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

• 详细的文档请参见Keys附加属性

布局镜像

• 可以使用LayoutMirroring附加属性镜像item布局。这会导致锚点水平颠倒，也会导致布局或定位其子元素(如ListView或Row)的项水平颠倒其布局方向。

Item图层

• tem通常会直接呈现到它所属的窗口中。然而，通过设置图层。启用后，可以将item及其整个子树委托到屏幕外表面。只有屏幕外的表面，一个纹理，将被绘制到窗口。
• 如果希望有于item的纹理大小，这可以使用layer.textureSize。
  • 要将项目的一部分渲染到纹理中，使用layer.sourceRect。
  • 也可以指定层layer.sourceRect，因此它扩展超出项目的边界。在这种情况下，外部将填充透明像素。
• 该项item将插值缩放，如果层平滑设置为true，并将使用 layer.mipmap进行下采样。Mipmap设置为true。填充映射可以改善缩小项目的视觉质量，用于Image::mipmap。

图层不透明度与item不透明度

• 当将不透明度应用于item层次结构时，不透明度将分别应用于每个item。当不透明度应用于子树时，这会导致不希望的视觉结果。考虑以下例子:
• Non-layered 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 }
}

• 根item的不透明度为1时，一个图层被渲染，然后根item的不透明度在纹理被绘制时被应用。
• 这意味着在一个大的项目层次结构中从透明到不透明，或者反之，可以在没有常规item逐项alpha混合的重叠工件的情况下完成。下面是启用图层的相同例子:

Layered Opacity

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将会把item变成一个 texture provider，使它可以直接使用item作为纹理，例如与ShaderEffect类型结合使用。
• 可以在运行时使用layer.effect在图层上应用一个效果:

Item {
    id: layerRoot
    layer.enabled: true
    layer.effect: ShaderEffect {
        fragmentShader: "
            uniform lowp sampler2D source; // this item
            uniform lowp float qt_Opacity; // inherited opacity of this item
            varying highp vec2 qt_TexCoord0;
            void main() {
                lowp vec4 p = texture2D(source, qt_TexCoord0);
                lowp float g = dot(p.xyz, vec3(0.344, 0.5, 0.156));
                gl_FragColor = vec4(g, g, g, p.a) * qt_Opacity;
            }"
    }

• 在这个例子中，我们手动实现着色效果。Qt Graphical Effects 模块包含一套可与Qt Quick一起使用的现成效果。

内存与效能表现

• 当一个物品的图层被启用时，场景图形将在GPU中分配等于宽×高× 4的内存。在内存受限的配置中，应该小心使用大的层。
• 在QPainter / QWidget领域中，有时将复杂内容缓存到像素图、图像或纹理中是有利的。
• 在Qt Quick中，由于场景图形渲染器已经应用了一些技术，所以在大多数情况下，这种情况不会发生。
  • 由于批量处理，过多的绘制调用已经减少，缓存在大多数情况下将混合比原始内容更多的像素。
  • 因此，渲染到屏幕外和绘制结果纹理所涉及的混合开销通常比简单地让item及其子item正常绘制要昂贵得多。
• 此外，在渲染过程中，使用图层的item不能被批处理。这意味着有许多分层物品的场景可能会有性能问题。
• 图层对于视觉效果来说是方便和有用的，但是在大多数情况下应该在效果持续期间启用，之后禁用。

属性

implicitHeight : real

implicitWidth : real

• 如果未指定宽度或高度，则定义item的自然宽度或高度。
• 大多数项的默认隐式大小是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
    }
}

• 注意:使用implicitWidth of Text或TextEdit和显式设置宽度会导致性能损失，因为text必须布局两次。

 

height : real

width : real

x : real

y : real

• 定义item的位置和大小。缺省值为0。
• (x,y)位置相对于父节点。

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

 

children : list<Item>

resources : list<Object>

• children属性包含此item的可视子元素列表。
• resources属性包含希望按名称引用的非可视资源。
• 在添加子项目或资源时，通常没有必要引用这些属性，因为默认的 data 属性会自动将子对象分配给适当的子项目和资源属性。详细信息请参见data文档。

 

activeFocus : bool

• 此只读属性指示item是否具有活动焦点。
• 如果activeFocus为真，则该项目要么是当前接收键盘输入的项目，要么是当前接收键盘输入的项目的FocusScope祖先。
• 通常，activeFocus是通过对一个item及其封装的FocusScope对象设置焦点来获得的。
• 在下面的例子中，Input 和FocusScope对象将具有活动焦点，而根矩形对象则没有。

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

• 参考： focus 和Keyboard Focus in Qt Quick.

 

activeFocusOnTab : bool

• 此属性保存项是否要位于选项卡焦点链中。默认情况下，它被设置为false。
• 选项卡焦点链遍历元素，首先访问父元素，然后按元素在children属性中出现的顺序访问其子元素。
  • 在选项卡焦点链中的项目上按下选项卡键将把键盘焦点移动到链中的下一个。
  • 按下BackTab键(通常是Shift+Tab键)将焦点个item。
• 要设置手动选项卡焦点链，请参见KeyNavigation。或KeyNavigation使用的Tab键事件优先于焦点链行为;忽略其他键处理程序中的事件以允许其传播。

 

anchors group

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

• 锚点提供了一种通过指定项与其他项的关系来定位项的方法
• 页边距适用于顶部、底部、左侧、右侧和填充锚。
  •  anchors.margins 属性可用于一次性将所有不同的页边距设置为相同的值。
  • 它不会覆盖先前设定的属性设置;若要清除显式的边距，请将其值设置为undefined。
  • 注意边距是特定于锚点的，如果项目不使用锚点，则不应用边距。
• 偏移量适用于水平中心、垂直中心和基线锚定。
• 示例：本锚定在图像上，水平居中和垂直下方，带空白。

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

• 示例：文本的eft锚定在图像的右边，带空白。这两个的y属性默认为0

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

• anchors.fill提供了一种方便的方式，使一个item具有与另一个item相同的几何形状，相当于连接所有四个定向锚。
• 若要清除锚定值，请将其设置为undefined
• anchors.alignWhenCentered (默认为true)强制以中心的锚对齐到整个像素；如果居中的项的宽度或高度为奇数，则该项将被放置在整个像素上，而不是放置在半像素上。
  • 这可以确保物品的颜色清晰。在有些情况下，这是不可取的，例如，当旋转item抖动可能是明显的中心是圆角。
• 注意: 只能将一个项目锚定到兄弟或父对象。
• 有关更多信息，请参阅 Anchor Layouts.

 

antialiasing : bool

• 由视觉元素来决定项目是否应该使用抗锯齿。
• 在某些情况下，带有抗锯齿的道具需要更多内存，渲染速度可能会更慢(更多细节请参阅Antialiasing )。

 

baselineOffset : int

• 指定item的基线在本地坐标中的位置。
• Text 的基线是文本所在的假想线。包含文本的控件通常将其基线设置为其文本的基线。
• 对于非文本项，默认基线偏移量为0。

 

childrenRect group

[read-only]childrenRect.height : real
[read-only]childrenRect.width : real
[read-only]childrenRect.x : real
[read-only]childrenRect.y : real

• 这个只读属性保存item的子元素的集合位置和大小。
• 如果需要访问item的子项目的集合几何形状以正确设置item的大小，则此属性非常有用。
• 返回的几何图形对于item来说是局部的。例如:

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。
• 如果启用了剪切，item将剪切其自己的绘画，以及其子绘画到其边界矩形。

 

containmentMask : QObject*

• 此属性保存了要在 QtQuick::Item::contains方法中使用的Item的可选掩码。
• QtQuick::Item::contains当前的主要用途是确定一个输入事件是否已经进入到该item中。
• 默认情况下， contains 方法将为Item的边框内的任何点返回true。
• containmentMask允许更细粒度的控制。例如，开发人员可以定义并使用AnotherItem元素作为containmentMask，它有一个特殊的contains方法，如:

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

• 只有当otheritem的contains实现返回true时，item的contains方法才返回true。
• 这个属性是在Qt 5.11中引入的。

 

data : list<Object>

• data属性允许您在item中自由地混合可视子元素和资源。如果您将一个可视化item分配给数据列表，它将成为一个子item，如果您分配任何其他对象类型，它将作为资源添加。
• 所以你可以这样写:

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

• 替代：

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

• 通常不需要引用data属性，因为它是Item的默认属性，因此所有子项都自动分配给这个属性。

 

enabled : bool

• 此属性保存item是否接收鼠标和键盘事件。默认情况下是true。
• 设置此属性直接影响子item的启用值。当设置为false时，所有子item的启用值也变为false。当设置为true时，子item的启用值将返回true，除非它们已显式设置为false。
• 将此属性设置为false会自动将activeFocus设置为false，并且该项目将不再接收键盘事件。
• 可参考： visible

 

focus : bool

• 此属性保存是否在封闭的 FocusScope内具有焦点。如果为真，当封闭的 FocusScope获得活动焦点时，该item将获得活动焦点
• 在下面的例子中，当scope获得活动焦点时，input将被赋予活动焦点:

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

• 出于此属性的目的，场景作为一个整体被假定为一个焦点范围。在实际层面上，这意味着下面的QML将积极关注启动时的输入。

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

• 参阅 activeFocus 和Keyboard Focus in Qt Quick.

 

layer.effect : Component

• 保持应用于此图层的效果
• 这个效果通常是一个 ShaderEffect组件，尽管任何Item组件都可以被分配。这个效果应该有一个名称匹配layer.samplerName.的源纹理属性。
• 参阅：layer.samplerName 和Item Layers.

 

layer.enabled : bool

• 保存item是否分层。分层默认是禁用的。
• 一个分层的item被渲染到一个屏幕外的表面，并被缓存，直到它被改变。为复杂的QML项层次结构启用分层有时是一种优化。
• 当图层被禁用时，其他的图层属性都没有任何效果。
• 参考：Item Layers.

 

layer.format : enumeration

• 这个属性定义了纹理的内部OpenGL格式。
  • 在图层中修改这个属性最有意义。还指定了效果。根据OpenGL的实现，这个属性可能允许你保存一些纹理内存。

• ShaderEffectSource.Alpha - GL_ALPHA;
• ShaderEffectSource.RGB - GL_RGB
• ShaderEffectSource.RGBA - GL_RGBA
• 注意:ShaderEffectSource.RGB和ShaderEffectSource.Alpha应该谨慎使用，因为底层硬件和驱动程序通常不支持这些格式。
• 参考：Item Layers.

 

layer.mipmap : bool

• 如果此属性为真，则为纹理生成mipmap。
• 注意:一些OpenGL ES 2实现不支持非二次方纹理的填充映射

 

layer.samplerName : string

• 保存效果的源纹理属性的名称。
• 此值必须与效果的源纹理属性的名称匹配，以便item可以正确地将层的屏幕外表面传递到效果
• 参考: layer.effect, ShaderEffect, 和 Item Layers.

 

layer.samples : enumeration

• 这个属性允许在层中请求多采样渲染。
• 默认情况下，只要整个窗口启用了multisampling, multisampling就会被启用，假设正在使用的场景渲染器和底层的图形API支持这个功能。
• 通过将数值设置为2,4等，可以要求对场景的一部分进行多采样渲染，而无需对整个场景进行多采样。
  • 这样，多重采样只应用于给定的子树，这可以导致显著的性能提高，因为多重采样没有应用于场景的其他部分。
• 注意:无论层的大小如何，启用多重采样都可能代价高昂，因为它需要依赖于硬件和驱动程序的性能和内存成本。
• 注意:这个属性只有在支持multisample renderbuffer和framebuffer blit时才有用。否则该值将被静默忽略。

 

layer.smooth : bool

• 保持图层是否平滑转换。当启用时，采样层的纹理使用线性插值，而非平滑的结果使用最近的滤波模式。
• 默认情况下，此属性设置为false。

 

layer.sourceRect : rect

• 这个属性定义了应该被渲染到纹理中的item的矩形区域。源矩形可以大于item本身。如果矩形为空(这是默认值)，那么整个item将被渲染到纹理中。

 

layer.textureMirroring : enumeration

• 这个属性定义了生成的OpenGL纹理应该如何镜像。
• 默认值是shadereffectsource . mirrorvertical。
• 如果生成的纹理被自定义着色器直接访问，比如那些由ShaderEffect指定的，自定义镜像是有用的。如果没有为分层item指定效果，则镜像对该item的UI表示没有影响。
  • ShaderEffectSource.NoMirroring - No mirroring
  • ShaderEffectSource.MirrorHorizontally - The generated texture is flipped along X-axis.
  • ShaderEffectSource.MirrorVertically - The generated texture is flipped along Y-axis.

 

layer.textureSize : size

• 此属性保存层纹理请求的像素大小。如果为空(默认为空)，则使用item的大小。
• 注意:有些平台对framebuffer对象的大小有限制，这意味着实际的纹理大小可能大于请求的大小。

 

layer.wrapMode : enumeration

• 这个属性定义了与纹理相关的OpenGL换行模式。在图层中修改这个属性最有意义。效果是指定。
  • ShaderEffectSource.ClampToEdge - GL_CLAMP_TO_EDGE both horizontally and vertically
  • ShaderEffectSource.RepeatHorizontally - GL_REPEAT horizontally, GL_CLAMP_TO_EDGE vertically
  • ShaderEffectSource.RepeatVertically - GL_CLAMP_TO_EDGE horizontally, GL_REPEAT vertically
  • ShaderEffectSource.Repeat - GL_REPEAT both horizontally and vertically
• 一些OpenGL ES 2的实现不支持GL_REPEAT wrap模式的非两次幂纹理。

 

opacity : real

• 此属性保存该item的不透明度。不透明度被指定为一个介于0.0(完全透明)和1.0(完全不透明)之间的数字。默认值为1.0。
• 设置此属性后，指定的不透明度也将单独应用于子item。
• 在某些情况下，这可能会产生意想不到的影响。
  • 例如，在下面第二组矩形中，红色矩形指定了不透明度为0.5，这将影响其蓝色子矩形的不透明度，即使子矩形没有指定不透明度。

• 更改item的不透明度不会影响项目是否接收用户输入事件。(相反，将visible属性设置为false会停止鼠标事件，将enabled属性设置为false会停止鼠标和键盘事件，还会从item中移除活动焦点。)

 

parent : Item

• 此属性保存该item的可视父元素。
• 注意:可视父类的概念与QObject父类的概念不同。一个item的可视父元素不一定与它的对象父元素相同。更多细节请参见 Concepts - Visual Parent in Qt Quick中的可视父类。

 

rotation : real

• 此属性保存项围绕 transformOrigin 顺时针旋转的程度。
• 默认值是0°(即不旋转)

• 参阅：Transform 和 Rotation.

 

scale : real

• 此属性保存该item的比例因子。
  • 小于1.0的比例将使item以较小的尺寸呈现。
  • 大于1.0的比例将以较大的尺寸呈现item。
  • 负比例会导致item在渲染时被镜像。
• 默认值为1.0。
• 从transformOrigin 应用缩放。

• 参阅：Transform 和Scale.

 

smooth : bool

• 主要用于基于图像的item，以决定item是否应该使用平滑采样或不。平滑采样采用线性插值法，非平滑采样采用最近邻法。
• 在Qt Quick 2.0中，这个属性对性能的影响很小。
• 默认情况下，该属性被设置为true。

 

state : string

• 此属性保存item的当前状态的名称。
• 如果item处于默认状态，即没有设置显式状态，则此属性保存一个空字符串。
• 同样，您以通过将此属性设置为空字符串，将item返回到其默认状态。
• 参考： Qt Quick States.

 

states : list<State>

• 此属性保存此item的可能状态列表。若要更改该item的状态，请将state 属性设置为这些状态之一，或将state属性设置为空字符串，以便将该项恢复为其默认状态。
• 此属性指定为State对象列表。例如，下面是一个带有“red_color”和“blue_color”状态的项目:

import QtQuick 2.0

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

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

• 参考 Qt Quick States 和Animation and Transitions in Qt Quick 有关使用状态和转换的详细信息.
• 参考 transitions.

 

transform : list<Transform>

• 此属性保存要应用的转换列表。
• 有关更多信息，请参阅Transform。

 

transformOrigin : enumeration

• 这个属性保存了缩放和旋转变换的原点。
• 有九个变换原点，如下图所示。默认的转换原点是Item.Center。

• 这个例子将图像旋转到右下角。

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

• 要设置任意的变换原点，请使用transform的 Scale or Rotation 变换类型。

 

transitions : list<Transition>

• 此属性保存此item的转换列表。它们定义了当item改变其状态时应用到它的转换。
• 此属性指定为转换对象列表。例如:

import QtQuick 2.0

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

• 参考  Qt Quick States 和Animation and Transitions in Qt Quick 获取有关使用状态和转换的详细信息
• 参考  states.

 

visible : bool

• 此属性保存该item是否可见。默认情况下是true。
• 设置此属性直接影响子项的可见值。当设置为false时，所有子项的可见值也变为false。当设置为true时，子项的可见值将返回true，除非它们被显式设置为false。
• (由于这种flow-on行为，如果属性绑定只响应显式的属性更改，则使用visible属性可能没有预期的效果。在这种情况下，使用不透明度属性可能会更好。)
• 如果此属性设置为false，则该项将不再接收鼠标事件，但将继续接收键事件，并将保持键盘焦点(如果已设置)。(相反，将enabled属性设置为false将同时停止鼠标和键盘事件，并从项目中移除焦点。)
• 注意:此属性的值仅受此属性或父属性的visible属性更改的影响。例如，如果该项目移出屏幕，或者不透明度变为0，它不会改变。
• 参考：opacity 和enabled.

 

visibleChildren : list<Item>

• 这个只读属性列出了该项当前可见的所有子项。请注意，一个子item的可见性可能已经显式改变，或者因为这个(它的父项目)项或另一个祖父项目的可见性发生了改变。

 

z : real

• 设置兄弟项的堆叠顺序。缺省情况下，堆叠顺序为0。
• 堆叠值较高的物品被绘制在堆叠顺序较低的兄弟姐妹的顶部。
• 具有相同堆叠值的项目将按照它们出现的顺序从下往上绘制。
• 负叠加值的项目被绘制在它们的父内容下。
• 下面的例子显示了堆叠顺序的各种影响。

Method

object mapToItem(Item item, point p)
object mapToItem(Item item, real x, real y)
object mapToItem(Item item, real x, real y, real width, real height)
object mapToItem(Item item, rect r)

• 将该item坐标系统中的点(x, y)或矩形(x, y，宽度，高度)映射到item的坐标系统，并返回与映射坐标匹配的点或矩形。
• 项目的以下属性用于映射: x, y, scale, rotation, transformOrigin, and transform。
• 如果item是空值，则将点或矩形映射到根QML视图的坐标系统。
• 接受点和rect的版本是从Qt 5.15开始的。

 

object mapFromItem(Item item, point p)
object mapFromItem(Item item, real x, real y)
object mapFromItem(Item item, real x, real y, real width, real height)
object mapFromItem(Item item, rect r)

• 将item坐标系统中的点(x, y)或矩形(x, y，宽度，高度)映射到该item的坐标系统，并返回与映射坐标匹配的点或矩形。
• item的以下属性用于映射: x, y, scale, rotation, transformOrigin, and transform。
• 如果item是空值，这将从根QML视图的坐标系统映射点或矩形。
• 接受点和rect的版本是从Qt 5.15开始的。

 

childAt(real x, real y)

• 返回在该项的坐标系统内(x, y)点找到的第一个可见的子项。
• 如果没有这样的项，则返回null。

 

bool contains(point point)

• 如果该项包含在局部坐标中的point，则返回true;否则返回false。
• 这与在事件传递期间对QEventPoint进行命中测试时使用的检查相同，如果设置了该检查，则会受到containmentMask()的影响。

 

forceActiveFocus(Qt::FocusReason reason)

• 这是一个重载函数。
• 用给定的理由迫使积极的焦点在item上。
• 该方法将焦点设置在item上，并确保对象层次结构中的所有祖先 FocusScope 对象也获得焦点。
• 该方法在Qt 5.1中进行了介绍。
• 参考：ctiveFocus and Qt::FocusReason.

 

forceActiveFocus()

• 迫使积极的焦点在item上。
• 该方法将焦点设置在item上，并确保对象层次结构中的所有祖先 FocusScope 对象也获得焦点。
• 焦点变化的原因是 Qt::OtherFocusReason。使用重载方法来指定焦点原因，以便更好地处理焦点变更。
• 参考：activeFocus.

 

bool grabToImage(callback, targetSize)

• 将item抓取到in-memory 图像中。
• 抓取是异步发生的，当抓取完成时将调用JavaScript函数回调。回调函数接受一个参数，它是抓取操作的结果;一个 ItemGrabResult对象。
• 使用targetSize指定目标图像的大小。默认情况下，结果将具有与item相同的大小。
• 如果抓取不能被初始化，函数将返回false。
• 下面的代码片段展示了如何获取项并将结果存储到文件中。

Rectangle {
    id: source
    width: 100
    height: 100
    gradient: Gradient {
        GradientStop { position: 0; color: "steelblue" }
        GradientStop { position: 1; color: "black" }
    }
}
    // ...
    source.grabToImage(function(result) {
                           result.saveToFile("something.png");
                       });

• 下面的代码片段展示了如何获取一个item并在另一个图像元素中使用结果

Image {
    id: image
}
    // ...
    source.grabToImage(function(result) {
                           image.source = result.url;
                       },
                       Qt.size(50, 50));

• 注意:这个函数将渲染item到一个屏幕外的表面，并将该表面从GPU的内存复制到CPU的内存，这可能是相当昂贵的。对于“实时”预览，使用 layers or ShaderEffectSource。

 

object mapFromGlobal(real x, real y)

• 将全局坐标系统中的点(x, y)映射到item的坐标系统，并返回与映射坐标匹配的点。
• item的以下属性在映射中使用:x, y, scale, rotation, transformOrigin, and transform.
• 该方法是在qt5.7中介绍的。

 

object mapToGlobal(real x, real y)

• 将该item坐标系中的点(x, y)映射到全局坐标系，并返回与映射坐标匹配的点。
• item的以下属性在映射中使用: x, y, scale, rotation, transformOrigin, and transform
• 该方法是在qt5.7中介绍的。

 

nextItemInFocusChain(bool forward)

• 返回焦点链中紧邻此项的项。如果forward为真，或者没有提供，则它是forward方向的下一项。如果forward为false，则表示向后方向的下一项。
• 该方法在Qt 5.1中进行了介绍。