Container QML Type

抽象基本类型，提供容器的通用功能。更多

Import Statement:	`import QtQuick.Controls`
Inherits:	Control
Inherited By:	DialogButtonBox, MenuBar, SplitView, SwipeView, and TabBar

所有成员（包括继承成员）的列表

属性

contentChildren : list<Item>
contentData : list<QtObject>
contentHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
contentModel : model
contentWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
count : int
currentIndex : int
currentItem : Item

方法

void addItem(Item item)
void decrementCurrentIndex() (since QtQuick.Controls 2.1 (Qt 5.8))
void incrementCurrentIndex() (since QtQuick.Controls 2.1 (Qt 5.8))
void insertItem(int index, Item item)
Item itemAt(int index)
void moveItem(int from, int to)
void removeItem(Item item) (since QtQuick.Controls 2.3 (Qt 5.10))
void setCurrentIndex(int index)
Item takeItem(int index) (since QtQuick.Controls 2.3 (Qt 5.10))

详细说明

容器是类似容器的用户界面控件的基本类型，允许动态插入和移除项目。

使用容器

通常，项目会静态地声明为 Container 的子项，但也可以动态地声明add,insert,move 和remove 项目。可以使用itemAt() 或contentChildren 访问容器中的项目。

大多数容器都有 "当前 "项的概念。当前项通过currentIndex 属性指定，并可通过只读的currentItem 属性访问。

下面的示例说明了向TabBar 动态插入项的情况，是容器的具体实现之一。

Row {
    TabBar {
        id: tabBar

        currentIndex: 0
        width: parent.width - addButton.width

        TabButton { text: "TabButton" }
    }

    Component {
        id: tabButton
        TabButton { text: "TabButton" }
    }

    Button {
        id: addButton
        text: "+"
        flat: true
        onClicked: {
            tabBar.addItem(tabButton.createObject(tabBar))
            console.log("added:", tabBar.itemAt(tabBar.count - 1))
        }
    }
}

管理当前索引

当同时使用多个容器（如TabBar 和SwipeView ）时，它们的currentIndex 属性可以相互绑定，以保持同步。当用户与其中一个容器交互时，其当前索引的变化会自动传播到另一个容器。

但请注意，在 JavaScript 中分配currentIndex 值会删除相应的绑定。为了保留绑定，请使用以下方法更改当前索引：

TabBar {
    id: tabBar
    currentIndex: swipeView.currentIndex
}

SwipeView {
    id: swipeView
    currentIndex: tabBar.currentIndex
}

Button {
    text: qsTr("Home")
    onClicked: swipeView.setCurrentIndex(0)
    enabled: swipeView.currentIndex != 0
}

Button {
    text: qsTr("Previous")
    onClicked: swipeView.decrementCurrentIndex()
    enabled: swipeView.currentIndex > 0
}

Button {
    text: qsTr("Next")
    onClicked: swipeView.incrementCurrentIndex()
    enabled: swipeView.currentIndex < swipeView.count - 1
}

实现容器

容器不提供任何默认的可视化。它用于实现SwipeView 和TabBar 等容器。在实现自定义容器时，API 中最重要的部分是contentModel ，它以一种可用作项目视图和重复器对象模型的方式提供所包含的项目。

Container {
    id: container

    contentItem: ListView {
        model: container.contentModel
        snapMode: ListView.SnapOneItem
        orientation: ListView.Horizontal
    }

    Text {
        text: "Page 1"
        width: container.width
        height: container.height
    }

    Text {
        text: "Page 2"
        width: container.width
        height: container.height
    }
}

请注意页面项的大小是手工设置的。这是因为该示例使用的是普通容器，不对可视化布局做任何假设。在具体的 Container 实现（如SwipeView 和TabBar ）中，通常不需要指定项目的大小。

另请参阅 容器控件。

属性文档

contentChildren : list<Item>

该属性包含内容子项列表。

该列表包含已在 QML 中声明为容器子项的所有项目，以及分别使用addItem() 和insertItem() 方法动态添加或插入的项目。

注意： 与contentData 不同，contentChildren 不包括非可视 QML 对象。插入或移动项目时，会重新排序。

另请参阅 Item::children 和contentData 。

contentData : list<QtObject> [default]

该属性包含内容数据列表。

该列表包含在 QML 中声明为容器子对象的所有对象，以及分别使用addItem() 和insertItem() 方法动态添加或插入的项目。

注意： 与contentChildren 不同，contentData 包含非可视 QML 对象。插入或移动项目时不会重新排序。

另请参阅 Item::data 和contentChildren 。

contentHeight : real [since QtQuick.Controls 2.5 (Qt 5.12)]

该属性包含内容高度。它用于计算容器的总隐含高度。

除非显式重载，否则内容高度将根据容器中项的隐式高度自动计算。

该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。

另请参阅 contentWidth 。

contentModel : model [read-only]

该属性保存项目的内容模型。

内容模型用于可视化目的。它可以作为模型分配给内容项，以显示容器的内容。

Container {
    id: container
    contentItem: ListView {
        model: container.contentModel
    }
}

另请参阅 contentData 和contentChildren 。

contentWidth : real [since QtQuick.Controls 2.5 (Qt 5.12)]

该属性包含内容宽度。它用于计算容器的总隐含宽度。

除非显式重载，否则内容宽度将根据容器中项的隐式宽度自动计算。

该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。

另请参阅 contentHeight 。

count : int [read-only]

该属性保存项的数量。

currentIndex : int

该属性保存当前项目的索引。

另请参阅 currentItem 和Managing the Current Index 。

currentItem : Item [read-only]

该属性用于保存当前项目。

另请参阅 currentIndex 。

方法文档

void addItem(Item item)

添加item 。

[since QtQuick.Controls 2.1 (Qt 5.8)] void decrementCurrentIndex()

减小容器的当前索引。

调用该方法可更改当前索引，而不会破坏现有的currentIndex 绑定。

该方法在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。

另请参阅 currentIndex 和Managing the Current Index 。

[since QtQuick.Controls 2.1 (Qt 5.8)] void incrementCurrentIndex()

递增容器的当前索引。

调用该方法可更改当前索引，而不会破坏现有的currentIndex 绑定。

该方法在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。

另请参阅 currentIndex 和Managing the Current Index 。

void insertItem(int index, Item item)

在index 插入item 。

Item itemAt(int index)

返回位于index 的项目，如果不存在，则返回null 。

void moveItem(int from, int to)

移动项目from 一个索引to 另一个索引。

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeItem(Item item)

移除并销毁指定的item 。

该方法在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

void setCurrentIndex(int index)

设置容器的当前index 。

调用该方法可设置特定的当前索引，而不会破坏现有的currentIndex 绑定。

另请参阅 currentIndex 和Managing the Current Index 。

[since QtQuick.Controls 2.3 (Qt 5.10)] Item takeItem(int index)

在index 删除并返回项目。

注意： 项目的所有权将转移给调用者。

此方法在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.