TableView QML Type

모델의 데이터를 표시할 항목의 테이블 보기를 제공합니다. 자세히...

Import Statement:	`import QtQuick`
Inherits:	Flickable
Inherited By:	TreeView

속성

alternatingRows : bool
animate : bool (since 6.4)
bottomRow : int
columnSpacing : real
columnWidthProvider : var
columns : int
contentHeight : real
contentWidth : real
currentColumn : int
currentRow : int
delegate : Component
editTriggers : enumeration (since 6.5)
keyNavigationEnabled : bool (since 6.4)
leftColumn : int
model : model
pointerNavigationEnabled : bool (since 6.4)
resizableColumns : bool (since 6.5)
resizableRows : bool (since 6.5)
reuseItems : bool
rightColumn : int
rowHeightProvider : var
rowSpacing : real
rows : int
selectionBehavior : enumeration (since 6.4)
selectionMode : enumeration (since 6.6)
selectionModel : ItemSelectionModel (since 6.2)
syncDirection : Qt::Orientations
syncView : TableView
topRow : int

첨부 속성

editDelegate : Component
view : TableView

신호

columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)
layoutChanged() (since 6.5)
rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)

첨부된 신호

commit()
pooled()
reused()

방법

point cellAtIndex(QModelIndex modelIndex) (since 6.4)
Point cellAtPosition(point position, bool includeSpacing)
Point cellAtPosition(real x, real y, bool includeSpacing)
clearColumnReordering() (since 6.8)
clearColumnWidths()
clearRowHeights()
clearRowReordering() (since 6.8)
closeEditor() (since 6.5)
int columnAtIndex(QModelIndex modelIndex) (since 6.4)
real columnWidth(int column) (since 6.2)
edit(QModelIndex modelIndex) (since 6.5)
qreal explicitColumnWidth(int column)
qreal explicitRowHeight(int row)
forceLayout()
real implicitColumnWidth(int column) (since 6.2)
real implicitRowHeight(int row) (since 6.2)
QModelIndex index(int row, int column) (since 6.4.3)
bool isColumnLoaded(int column) (since 6.2)
bool isRowLoaded(int row) (since 6.2)
Item itemAtCell(point cell)
Item itemAtIndex(QModelIndex index) (since 6.5)
QModelIndex modelIndex(point cell) (since 6.4)
moveColumn(int source, int destination) (since 6.8)
moveRow(int source, int destination) (since 6.8)
positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)
positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)
positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect) (since 6.5)
positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)
int rowAtIndex(QModelIndex modelIndex) (since 6.4)
real rowHeight(int row) (since 6.2)
setColumnWidth(int column, real size)
setRowHeight(int row, real size)

상세 설명

TableView에는 표시할 데이터를 정의하는 model 과 데이터를 표시하는 방법을 정의하는 delegate 이 있습니다.

TableView는 Flickable 을 상속합니다. 즉, 모델에는 행과 열이 얼마든지 포함될 수 있지만 일반적으로 뷰포트 내부에는 테이블의 하위 섹션만 표시됩니다. 플릭하는 즉시 새 행과 열이 뷰포트에 들어오고 이전 행과 열은 뷰포트에서 나가서 제거됩니다. 밖으로 이동한 행과 열은 뷰포트 안으로 이동하는 행과 열을 작성하는 데 재사용됩니다. 따라서 TableView는 성능에 영향을 주지 않고 모든 크기의 모델을 지원합니다.

TableView는 ListModel 및 XmlListModel 과 같은 기본 제공 QML 유형에서 만든 모델의 데이터를 표시하며, 이 모델은 TableView에서 첫 번째 열만 채웁니다. 여러 열이 있는 모델을 만들려면 TableModel 또는 QAbstractItemModel 을 상속하는 C++ 모델을 사용합니다.

TableView는 기본적으로 헤더를 포함하지 않습니다. Qt Quick Controls 에서 HorizontalHeaderView 및 VerticalHeaderView 을 사용하여 헤더를 추가할 수 있습니다.

참고: TableView는 뷰를 채우는 데 필요한 만큼의 델리게이트 항목만 load 합니다. 뷰 외부의 항목이 로드된다는 보장은 없지만 TableView는 최적화를 위해 항목을 미리 로드하는 경우가 있습니다. 따라서 너비 또는 높이가 0인 TableView는 델리게이트 항목을 전혀 로드하지 않을 수 있습니다.

사용 예

C++ 모델

다음 예는 여러 열이 있는 C++에서 모델을 만드는 방법을 보여줍니다:

#include <qqml.h>
#include <QAbstractTableModel>

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
    QML_ELEMENT

public:
    int rowCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    int columnCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    QVariant data(const QModelIndex &index, int role) const override
    {
        switch (role) {
            case Qt::DisplayRole:
                return QString("%1, %2").arg(index.column()).arg(index.row());
            default:
                break;
        }

        return QVariant();
    }

    QHash<int, QByteArray> roleNames() const override
    {
        return { {Qt::DisplayRole, "display"} };
    }
};

그리고 QML에서 사용하는 방법을 보여줍니다:

import QtQuick
import TableModel

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {}

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        Text {
            text: display
        }
    }
}

QML 모델

매우 간단한 데이터를 프로토타이핑하고 표시하려면(예: 웹 API에서) TableModel 을 사용할 수 있습니다:

import QtQuick
import Qt.labs.qmlmodels

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {
        TableModelColumn { display: "name" }
        TableModelColumn { display: "color" }

        rows: [
            {
                "name": "cat",
                "color": "black"
            },
            {
                "name": "dog",
                "color": "brown"
            },
            {
                "name": "bird",
                "color": "white"
            }
        ]
    }

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        border.width: 1

        Text {
            text: display
            anchors.centerIn: parent
        }
    }
}

항목 재사용하기

TableView는 새 행과 열을 뷰로 끌어올 때마다 delegate 에서 인스턴스화하는 대신 기본적으로 델리게이트 항목을 재활용합니다. 이 접근 방식은 델리게이트의 복잡성에 따라 성능이 크게 향상됩니다.

항목이 플릭아웃되면 사용하지 않는 항목의 내부 캐시인 재사용 풀로 이동합니다. 이 경우 TableView::pooled 신호가 발생하여 아이템에 이를 알립니다. 마찬가지로 아이템이 풀에서 다시 이동하면 TableView::reused 신호가 전송됩니다.

아이템이 재사용되면 모델에서 가져온 모든 아이템 속성이 업데이트됩니다. 여기에는 index, row, column 뿐만 아니라 모든 모델 역할도 포함됩니다.

참고: 델리게이트 내부에 상태를 저장하지 마세요. 저장하는 경우에는 TableView::reused 신호를 수신할 때 수동으로 재설정하세요.

항목에 타이머나 애니메이션이 있는 경우에는 TableView::pooled 신호를 수신할 때 일시 중지하는 것이 좋습니다. 이렇게 하면 보이지 않는 항목에 CPU 리소스를 사용하지 않아도 됩니다. 마찬가지로 항목에 재사용할 수 없는 리소스가 있는 경우 해당 리소스를 해제할 수 있습니다.

항목을 재사용하고 싶지 않거나 delegate 에서 지원하지 않는 경우 reuseItems 속성을 false 로 설정할 수 있습니다.

참고: 항목이 풀에 있는 동안에도 여전히 살아 있고 연결된 신호 및 바인딩에 응답할 수 있습니다.

다음 예시는 회전하는 직사각형을 애니메이션하는 델리게이트를 보여줍니다. 풀에 있으면 애니메이션이 일시적으로 일시 중지됩니다:

Component {
    id: tableViewDelegate
    Rectangle {
        implicitWidth: 100
        implicitHeight: 50

        TableView.onPooled: rotationAnimation.pause()
        TableView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

행 높이 및 열 너비

새 열이 뷰로 플릭되면 TableView는 columnWidthProvider 함수를 호출하여 열 너비를 결정합니다. 이 함수가 설정되어 있으면 이 함수만으로 열의 너비를 결정합니다. 그렇지 않으면 setColumnWidth()로 명시적 너비가 설정되어 있는지 확인합니다. 그렇지 않은 경우 implicitColumnWidth()가 사용됩니다. 열의 암시적 너비는 해당 열에 현재 로드된 델리게이트 항목 중 가장 큰 implicit width 와 동일합니다. 델리게이트에 직접 명시적으로 width 을 설정하려고 하면 아무런 효과가 없으며 무시되고 덮어쓰기됩니다. 행 높이에도 동일한 논리가 적용됩니다.

기본 로직과 동일한 columnWidthProvider 을 구현하면 됩니다:

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return w;
    return implicitColumnWidth(column)
}

열 너비가 확인되면 나중에 뷰에 플릭된 항목을 포함하여 동일한 열의 다른 모든 항목의 크기가 이 너비로 조정됩니다.

참고: 열의 확인된 너비는 전체 열을 뷰 밖으로 플릭하면 삭제되고 다시 안으로 플릭하면 다시 계산됩니다. 즉, 너비가 implicitColumnWidth()에 따라 달라지는 경우 열이 들어갈 때 어느 행에 있는지에 따라 계산이 매번 달라질 수 있습니다( implicitColumnWidth()는 현재 loaded 인 델리게이트 항목만 고려하므로). 이를 방지하려면 columnWidthProvider 을 사용하거나 같은 열에 있는 모든 델리게이트 항목의 implicitWidth 이 동일한지 확인해야 합니다.

뷰포트 내부의 행과 열에 대해 rowHeightProvider 또는 columnWidthProvider 이 반환하는 값을 변경하는 경우 forceLayout 을 호출해야 합니다. 이렇게 하면 TableView가 공급자 함수를 다시 사용하여 레이아웃을 다시 계산하고 업데이트해야 함을 알립니다.

Qt 5.13부터는 특정 열을 숨기려면 해당 열에 대해 columnWidthProvider 에서 0 을 반환하면 됩니다. 마찬가지로 행을 숨기려면 rowHeightProvider 에서 0을 반환하면 됩니다. 음수를 반환하면 TableView는 델리게이트 항목을 기준으로 크기를 계산하기 위해 폴백합니다.

참고: 항목의 하위 픽셀 정렬을 방지하려면 행 또는 열의 크기는 정수를 사용해야 합니다.

다음 예제는 간단한 columnWidthProvider 을 함수가 반환하는 값을 수정하는 타이머와 함께 설정하는 방법을 보여줍니다. 배열이 수정되면 forceLayout 이 호출되어 변경 사항이 적용됩니다:

TableView {
    id: tableView

    property var columnWidths: [100, 50, 80, 150]
    columnWidthProvider: function (column) { return columnWidths[column] }

    Timer {
        running: true
        interval: 2000
        onTriggered: {
            tableView.columnWidths[2] = 150
            tableView.forceLayout();
        }
    }
}

셀 편집하기

편집 델리게이트를 제공하여 사용자가 표 셀을 편집할 수 있도록 할 수 있습니다. 편집 델리게이트는 기본적으로 사용자가 셀을 두 번 탭하거나 Qt::Key_Enter 또는 Qt::Key_Return 을 누를 때 editTriggers 에 따라 인스턴스화됩니다. 편집 델리게이트는 delegate 에 설정한 첨부 속성인 TableView::editDelegate 을 사용하여 설정됩니다. 다음 스니펫은 그 방법을 보여줍니다:

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            Text {
                anchors.centerIn: parent
                text: display
            }

            TableView.editDelegate: TextField {
                anchors.fill: parent
                text: display
                horizontalAlignment: TextInput.AlignHCenter
                verticalAlignment: TextInput.AlignVCenter
                Component.onCompleted: selectAll()

                TableView.onCommit: {
                    display = text
                    // 'display = text' is short-hand for:
                    // let index = TableView.view.index(row, column)
                    // TableView.view.model.setData(index, "display", text)
                }
            }
        }
    }

편집 델리게이트가 활성화되어 있는 동안 사용자가 Qt::Key_Enter 또는 Qt::Key_Return 을 누르면 TableView는 편집 델리게이트에 TableView::commit 신호를 보내 변경된 데이터를 모델에 다시 쓸 수 있도록 합니다.

참고: 셀을 편집할 수 있으려면 모델에서 QAbstractItemModel::flags()를 재정의하고 Qt::ItemIsEditable 을 반환해야 합니다. 이 플래그는 기본적으로 QAbstractItemModel 에서 활성화되어 있지 않습니다. 예를 들어 다음과 같이 재정의할 수 있습니다:

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

TableView delegate 에 required property bool editing 속성이 정의되어 있는 경우 편집 중인 델리게이트에 대해 true 로 설정됩니다. 사용 방법에 대한 예는 editDelegate 문서를 참조하세요.

오버레이 및 언더레이

델리게이트에서 인스턴스화된 모든 새 항목은 z 값( 1)을 사용하여 contentItem 에 부모가 됩니다. 테이블뷰 내에서 플릭커블의 하위 항목으로 자신만의 항목을 추가할 수 있습니다. z 값을 제어하여 테이블 항목의 위 또는 아래에 위치하도록 만들 수 있습니다.

다음은 테이블 위에 텍스트를 추가하는 방법을 보여주는 예시로, 플릭할 때 테이블과 함께 움직입니다:

TableView {
    id: tableView

    topMargin: header.implicitHeight

    Text {
        id: header
        text: "A table header"
    }
}

다음은 특정 셀 위에 유지되는 오버레이 항목을 만드는 방법을 보여주는 또 다른 예시입니다. 예를 들어 사용자가 셀 앞에 있는 열의 크기를 조정하는 경우 셀의 위치가 change 가 되므로 조금 더 많은 코드가 필요합니다.

Rectangle {
    id: overlay
    width: 20
    height: 20
    radius: 10
    color: "blue"

    z: 10
    parent: tableView.contentItem

    Connections {
        target: tableView
        function onLayoutChanged() {
            let item = tableView.itemAtCell(5, 5)
            let insideViewport = item !== null

            overlay.visible = insideViewport
            if (insideViewport) {
                overlay.x = item.x
                overlay.y = item.y
            }
        }
    }
}

contentItem 대신 셀에 직접 오버레이를 부모로 지정할 수도 있습니다. 하지만 이렇게 하면 뷰포트에서 셀을 내릴 때마다 언로드되거나 재사용되므로 불안정해집니다.

항목 선택

selectionModel 속성에 ItemSelectionModel 을 할당하여 TableView에 선택 지원을 추가할 수 있습니다. 그러면 이 모델을 사용하여 어떤 델리게이트 항목을 선택한 것으로 표시할지, 어떤 항목을 현재 항목으로 표시할지 제어합니다. selectionBehavior 을 설정하여 사용자가 개별 셀, 행 또는 열을 선택할 수 있도록 허용할지 여부를 제어할 수 있습니다.

델리게이트가 선택되었는지 또는 현재 상태인지 확인하려면 다음 속성을 선언하세요:

delegate: Item {
    required property bool selected
    required property bool current
    // ...
}

참고: selected 및 current 속성은 required 로 정의해야 합니다. 이렇게 하면 TableView가 해당 값을 업데이트할 책임이 있음을 알립니다. 그렇지 않으면 단순히 무시됩니다. 필수 속성도 참조하세요.

다음 코드 조각은 애플리케이션이 selected 속성에 따라 델리게이트를 다르게 렌더링하는 방법을 보여줍니다:

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 30
            color: selected ? "blue" : "lightgray"

            required property bool selected

            Text { text: display }
        }
    }

currentRow 및 currentColumn 속성은 델리게이트가 현재 항목과 같은 행 또는 열에 있는지에 따라 다르게 렌더링해야 하는 경우에도 유용할 수 있습니다.

참고: Qt Quick Controls 는 사용자가 셀을 선택하는 데 사용할 수 있는 SelectionRectangle 를 제공합니다.

참고: 기본적으로 셀은 current 이 되며, 사용자가 셀을 탭하면 모든 선택 항목이 제거됩니다. 이러한 기본 탭 동작을 원하지 않는 경우(예: 델리게이트 내에서 사용자 지정 포인터 핸들러를 사용하는 경우) pointerNavigationEnabled 을 false 으로 설정할 수 있습니다.

키보드 탐색을 지원하려면 selectionModel 속성에 ItemSelectionModel 을 할당해야 합니다. 그러면 TableView는 이 모델을 사용하여 모델의 currentIndex 을 조작합니다.

자신을 current 로 렌더링하는 것은 델리게이트의 책임입니다. 이를 위해 required property bool current 속성을 추가하고 해당 상태에 따라 모양이 달라지도록 할 수 있습니다. current 속성의 값은 TableView에서 설정합니다. keyNavigationEnabled 을 false 으로 설정하여 키보드 탐색을 완전히 비활성화할 수도 있습니다(자체 키 핸들러를 구현하려는 경우).

다음 예는 current 및 selected 속성과 함께 키보드 탐색을 사용하는 방법을 보여줍니다:

ApplicationWindow {
    width: 800
    height: 600
    visible: true
    ScrollView {
        anchors.fill: parent
        TableView {
            id: tableView
            clip: true
            interactive: true
            rowSpacing: 1
            columnSpacing: 1
            model: TableModel {
                TableModelColumn { display: "checked" }
                TableModelColumn { display: "amount" }
                TableModelColumn { display: "fruitType" }
                TableModelColumn { display: "fruitName" }
                TableModelColumn { display: "fruitPrice" }

                rows: [
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Apple",
                        fruitName: "Granny Smith",
                        fruitPrice: 1.50
                    },
                    {
                        checked: true,
                        amount: 4,
                        fruitType: "Orange",
                        fruitName: "Navel",
                        fruitPrice: 2.50
                    },
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Banana",
                        fruitName: "Cavendish",
                        fruitPrice: 3.50
                    }
                ]
            }
            selectionModel: ItemSelectionModel {}
            delegate: Rectangle {
                implicitWidth: 100
                implicitHeight: 50
                required property bool selected
                required property bool current
                border.width: current ? 2 : 0
                color: selected ? "lightblue" : palette.base
                Text{
                    text: model.display
                    padding: 12
                }
            }
        }
    }
    SelectionRectangle {
        target: tableView
    }
}

복사 및 붙여넣기

TableView에 대한 복사 및 붙여넣기 작업을 구현할 때는 일반적으로 QUndoStack (또는 다른 실행 취소/다시 실행 프레임워크)를 사용합니다. QUndoStack 은 행 추가 또는 제거, 클립보드에서 데이터 붙여넣기 등 모델에서 수행한 다양한 작업을 저장하고 나중에 다시 실행 취소하는 데 사용할 수 있습니다. 그러나 가능한 작업과 실행 취소 방법을 설명하는 QUndoStack 은 모델과 애플리케이션의 요구 사항에 따라 설계해야 합니다. 따라서 TableView는 복사 및 붙여넣기 처리를 위한 기본 제공 API를 제공하지 않습니다.

다음 코드 조각은 모델과 TableView에 복사 및 붙여넣기 지원을 추가하는 방법에 대한 참조로 사용할 수 있습니다. 이 스니펫은 QAbstractItemModel 의 기존 마임 데이터 API와 QClipboard 을 함께 사용합니다. 이 스니펫은 그대로 작동하지만 QUndoStack 을 사용하도록 확장할 수도 있습니다.

// Inside your C++ QAbstractTableModel subclass:

Q_INVOKABLE void copyToClipboard(const QModelIndexList &indexes) const
{
    QGuiApplication::clipboard()->setMimeData(mimeData(indexes));
}

Q_INVOKABLE bool pasteFromClipboard(const QModelIndex &targetIndex)
{
    const QMimeData *mimeData = QGuiApplication::clipboard()->mimeData();
    // Consider using a QUndoCommand for the following call. It should store
    // the (mime) data for the model items that are about to be overwritten, so
    // that a later call to undo can revert it.
    return dropMimeData(mimeData, Qt::CopyAction, -1, -1, targetIndex);
}

예를 들어 두 함수는 QML에서 다음과 같이 사용할 수 있습니다:

TableView {
    id: tableView
    model: tableModel
    selectionModel: ItemSelectionModel {}

    Shortcut {
       sequence: StandardKey.Copy
       onActivated: {
           let indexes = tableView.selectionModel.selectedIndexes
           tableView.model.copyToClipboard(indexes)
       }
    }

    Shortcut {
       sequence: StandardKey.Paste
       onActivated: {
           let targetIndex = tableView.selectionModel.currentIndex
           tableView.model.pasteFromClipboard(targetIndex)
       }
    }
}

TableView::editDelegate, TableView::commit, editTriggers, edit(), closeEditor(), layoutChanged(), QAbstractItemModel::mimeData(), QAbstractItemModel::dropMimeData(), QUndoStack, QUndoCommand, QClipboard 를참조하세요 .

프로퍼티 문서

alternatingRows : bool

이 속성은 행의 배경색을 번갈아 사용할지 여부를 제어합니다. 기본값은 스타일에 따라 다릅니다.

참고: 이 속성은 힌트일 뿐이므로 사용자 지정 델리게이트에서 존중되지 않을 수 있습니다. 이 힌트가 true 인 경우 델리게이트 외부에서 색상을 설정할 수 있도록 palette.base 과 palette.alternateBase 을 번갈아 사용하는 것이 좋습니다. 예를 들어

background: Rectangle {
    color: control.row === control.tableView.currentRow
           ? control.palette.highlight
           : (control.tableView.alternatingRows && control.row % 2 !== 0
           ? control.palette.alternateBase
           : control.palette.base)
}

animate : bool [since 6.4]

이 속성을 설정하여 contentItem (contentX 및 contentY)에 TableView 애니메이션을 적용할지 여부를 제어할 수 있습니다. positionViewAtCell () 및 키보드로 the current index 을 탐색할 때 사용됩니다. 기본값은 true 입니다.

false 로 설정하면 진행 중인 모든 애니메이션이 즉시 중지됩니다.

참고: 이 속성은 힌트일 뿐입니다. 예를 들어 대상 셀이 loaded 이 아닌 경우 TableView 은 애니메이션 없이 콘텐츠 항목을 배치하도록 선택할 수 있습니다. 그러나 false 로 설정하면 애니메이션이 항상 꺼집니다.

이 속성은 Qt 6.4에 도입되었습니다.

positionViewAtCell()도 참조하십시오 .

bottomRow : int

이 속성은 현재 뷰 내부에 표시되는 가장 아래쪽 행을 보유합니다.

leftColumn, rightColumn, 및 topRow 를참조하십시오 .

columnSpacing : real

이 속성은 열 사이의 간격을 유지합니다.

기본값은 0 입니다.

columnWidthProvider : var

이 속성에는 모델의 각 열에 대한 열 너비를 반환하는 함수가 포함될 수 있습니다. TableView 에서 특정 열의 너비를 알아야 할 때마다 호출됩니다. 이 함수는 TableView 에서 너비를 알아야 하는 하나의 인수 column 를 받습니다.

Qt 5.13부터 특정 열을 숨기려면 해당 열의 0 너비를 반환하면 됩니다. 음수를 반환하면 TableView 은 델리게이트 항목에 따라 너비를 계산합니다.

참고: 열을 로드하려고 할 때(또는 레이아웃을 수행할 때) columnWidthProvider는 일반적으로 두 번 호출됩니다. 첫째, 열이 표시되고 로드되어야 하는지 확인하기 위해 호출됩니다. 둘째, 모든 항목이 로드된 후 열의 너비를 결정하기 위해 호출합니다. 델리게이트 항목의 크기를 기준으로 열 너비를 계산해야 하는 경우 모든 항목이 로드된 후 두 번째 호출을 기다려야 합니다. isColumnLoaded (열)을 호출하여 이를 확인할 수 있으며, 아직 그렇지 않은 경우 -1을 반환하면 됩니다.

rowHeightProvider, isColumnLoaded() 및 Row heights and column widths 를참조하세요 .

columns : int [read-only]

이 속성은 테이블의 열 수를 보유합니다.

참고: columns 은 일반적으로 모델의 열 수와 같지만 보류 중인 모든 모델 변경이 처리될 때까지 일시적으로 다를 수 있습니다.

모델이 목록인 경우 열은 1 입니다.

이 속성은 읽기 전용입니다.

contentHeight : real

이 속성은 데이터 모델의 행 수를 수용하는 데 필요한 테이블 높이를 보유합니다. 이는 일반적으로 view 의 height 과 같지 않으므로 테이블의 높이가 뷰포트 높이보다 크거나 작을 수 있습니다. TableView 은 모델의 모든 행을 로드하지 않고는 테이블의 정확한 높이를 항상 알 수 없으므로 일반적으로 contentHeight 은 처음 로드된 테이블을 기반으로 한 추정치입니다.

테이블의 높이를 알고 있는 경우 contentHeight 에 값을 할당하여 TableView 에 대한 불필요한 계산 및 업데이트를 방지합니다.

contentWidth 및 rowHeightProvider 을참조하세요 .

contentWidth : real

이 속성은 모델의 열 수를 수용하는 데 필요한 테이블 너비를 보유합니다. 이는 일반적으로 view 의 width 과 같지 않으므로 테이블 너비가 뷰포트 너비보다 크거나 작을 수 있습니다. TableView 은 모델의 모든 열을 로드하지 않고는 항상 테이블의 정확한 너비를 알 수 없으므로 일반적으로 contentWidth 은 처음 로드된 테이블을 기반으로 한 추정치입니다.

테이블 너비를 알고 있는 경우 contentWidth 에 값을 할당하여 TableView 에 대한 불필요한 계산 및 업데이트를 방지합니다.

contentHeight 및 columnWidthProvider 을참조하세요 .

currentColumn : int [read-only]

이 읽기 전용 속성은 뷰에서 current. 항목이 포함된 열을 보유합니다. 현재 항목이 없는 경우 -1 이 됩니다.

참고: TableView 에서 현재 열이 무엇인지 보고하려면 ItemSelectionModel 을 selectionModel 에 할당해야 합니다.

currentRow, selectionModel, Selecting items도 참조하세요 .

currentRow : int [read-only]

이 읽기 전용 속성은 뷰에서 current. 항목이 포함된 행을 보유합니다. 현재 항목이 없는 경우 -1 이 됩니다.

참고: TableView 에서 현재 행이 무엇인지 보고하려면 ItemSelectionModel 을 selectionModel 에 할당해야 합니다.

currentColumn, selectionModel, Selecting items도 참조하세요 .

delegate : Component

델리게이트는 뷰에 의해 인스턴스화된 각 셀 항목을 정의하는 템플릿을 제공합니다. 모델 인덱스는 액세스 가능한 index 속성으로 노출됩니다. row 및 column 에도 동일하게 적용됩니다. 데이터 모델 유형에 따라 모델의 속성도 사용할 수 있습니다.

델리게이트는 implicitWidth 및 implicitHeight 을 사용하여 크기를 지정해야 합니다. TableView 은 해당 정보를 기반으로 항목을 배치합니다. 명시적인 너비 또는 높이 설정은 무시되고 덮어쓰기됩니다.

델리게이트 내에서 다음 속성 중 하나 이상을 선택적으로 추가할 수 있습니다. TableView 은 이러한 속성 값을 수정하여 델리게이트가 어떤 상태인지 알려줍니다. 델리게이트가 자신의 상태에 따라 다르게 렌더링하는 데 사용할 수 있습니다.

필수 속성 bool current - true 델리게이트인 경우 current.
필수 속성 값 선택됨 - true 델리게이트가 선택된 경우 selected.
필수 속성 값 편집 - true 델리게이트가 편집 중인 경우 edited.
필수 속성 bool containsDrag - true 열 또는 행이 현재 이 델리게이트 위로 드래그되고 있는 경우. 이 프로퍼티는 HorizontalHeaderView 와 VerticalHeaderView 에서만 지원됩니다 (Qt 6.8부터).

다음 예제는 이러한 프로퍼티를 사용하는 방법을 보여줍니다:

delegate: Rectangle {
    required property bool current
    required property bool selected
    border.width: current ? 1 : 0
    color: selected ? palette.highlight : palette.base
}

참고: 델리게이트는 필요에 따라 인스턴스화되며 언제든지 삭제될 수 있습니다. reuseItems 속성이 true 으로 설정된 경우에도 재사용됩니다. 따라서 델리게이트에 상태 정보를 저장하지 않아야 합니다.

Row heights and column widths, Reusing items 및 필수 속성도참조하세요 .

editTriggers : enumeration [default: TableView.DoubleTapped | TableView.EditKeyPressed., since 6.5]

이 속성에는 사용자가 셀 편집을 시작할 수 있는 다양한 방법이 저장됩니다. 다음 값을 조합할 수 있습니다:

상수	Description
`TableView.NoEditTriggers`	- 사용자가 셀 편집을 트리거할 수 없습니다. 이 값을 설정하면 TableView 은 사용자 상호 작용에 대한 응답으로 편집 델리게이트를 열거나 닫지 않습니다. 그러나 애플리케이션은 edit() 및 closeEditor()을 수동으로 호출할 수 있습니다.
`TableView.SingleTapped`	- 사용자가 셀을 한 번 탭하여 셀을 편집할 수 있습니다.
`TableView.DoubleTapped`	- 사용자가 셀을 두 번 탭하여 셀을 편집할 수 있습니다.
`TableView.SelectedTapped`	- 사용자가 selected cell 을 탭하여 편집할 수 있습니다.
`TableView.EditKeyPressed`	- 사용자는 편집 키 중 하나를 눌러 current cell 을 편집할 수 있습니다. 편집 키는 OS에 따라 결정되지만 일반적으로 `Qt::Key_Enter` 및 `Qt::Key_Return` 입니다.
`TableView.AnyKeyPressed`	- 사용자는 셀 탐색 키가 아닌 다른 키를 눌러 current cell 을 편집할 수 있습니다. 누른 키는 edit delegate 내부의 포커스 객체로도 전송됩니다.

TableView.SelectedTapped, TableView.EditKeyPressed, TableView.AnyKeyPressed 이 효과를 발휘하려면 TableView 에 selection model 가 할당되어 있어야 하는데, 이는 current index 가 설정되어 있어야 하기 때문입니다. 모든 키 이벤트를 수신하려면 TableView 에 QQuickItem::activeFocus 도 있어야 합니다.

셀을 편집할 때 사용자는 Qt::Key_Tab 또는 Qt::Key_Backtab 을 눌러 데이터를 commit 로 이동하고 편집을 다음 셀로 옮길 수 있습니다. 이 동작은 TableView 에서 QQuickItem::activeFocusOnTab 을 false 으로 설정하여 비활성화할 수 있습니다.

참고: 셀을 편집할 수 있으려면 delegate 에 edit delegate 이 첨부되어야 하고 모델에서 QAbstractItemModel::flags()에서 Qt::ItemIsEditable 을 반환해야 합니다(아래 예시). 지정된 트리거 중 하나를 활성화한 후에도 셀을 편집할 수 없는 경우 도움말을 참조하여 edit()를 명시적으로 호출해 볼 수 있습니다(예: 버튼/TapHandler)에서). 이렇게 하면 셀을 편집할 수 없는 이유를 설명하는 경고가 출력됩니다.

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

이 속성은 Qt 6.5에 도입되었습니다.

TableView::editDelegate, TableView::commit, Editing cells 를참조하세요 .

keyNavigationEnabled : bool [since 6.4]

이 속성은 사용자가 키보드를 사용하여 the current index 을 변경할 수 있는지 여부를 제어하도록 설정할 수 있습니다. 기본값은 true 입니다.

참고: TableView 이 키보드 탐색을 지원하려면 ItemSelectionModel 을 selectionModel 에 할당해야 합니다.

이 속성은 Qt 6.4에 도입되었습니다.

Keyboard navigation, selectionModel, selectionBehavior, pointerNavigationEnabled, interactive도 참조하십시오 .

leftColumn : int

이 속성은 현재 뷰 내부에 표시되는 가장 왼쪽 열을 보유합니다.

rightColumn, topRow, 및 bottomRow도 참조하십시오 .

model : model

이 속성은 테이블에 데이터를 제공하는 모델을 보유합니다.

모델은 뷰에서 항목을 만드는 데 사용되는 데이터 집합을 제공합니다. 모델은 TableModel, ListModel, ObjectModel 를 사용하여 QML에서 직접 만들거나 사용자 지정 C++ 모델 클래스에서 제공할 수 있습니다. C++ 모델은 QAbstractItemModel 의 하위 클래스이거나 간단한 목록이어야 합니다.

데이터 모델도참조하세요 .

pointerNavigationEnabled : bool [since 6.4]

이 속성을 설정하여 사용자가 마우스 또는 터치를 사용하여 the current index 을 변경할 수 있는지 여부를 제어할 수 있습니다. 기본값은 true 입니다.

이 속성은 Qt 6.4에 도입되었습니다.

selectionModel, keyNavigationEnabled, interactive 를참조하십시오 .

resizableColumns : bool [since 6.5]

이 속성은 사용자가 셀 사이를 드래그하여 열 크기를 조정할 수 있는지 여부를 저장합니다. 기본값은 false 입니다.

이 프로퍼티는 Qt 6.5에 도입되었습니다.

resizableRows : bool [since 6.5]

이 속성은 사용자가 셀 사이를 드래그하여 행의 크기를 조정할 수 있는지 여부를 저장합니다. 기본값은 false 입니다.

이 속성은 Qt 6.5에 도입되었습니다.

reuseItems : bool

이 속성은 delegate 에서 인스턴스화된 항목을 재사용할지 여부를 저장합니다. false 로 설정하면 현재 풀링된 모든 항목이 소멸됩니다.

Reusing items, TableView::pooled, TableView::reused 를참조하세요 .

rightColumn : int

이 속성은 현재 뷰 내부에 표시되는 가장 오른쪽 열을 보유합니다.

leftColumn, topRow, 및 bottomRow도 참조하십시오 .

rowHeightProvider : var

이 속성은 모델의 각 행에 대한 행 높이를 반환하는 함수를 보유할 수 있습니다. TableView 에서 특정 행의 높이를 알아야 할 때마다 호출됩니다. 이 함수는 TableView 에서 높이를 알아야 하는 row 이라는 인수를 하나 받습니다.

Qt 5.13부터 특정 행을 숨기려면 해당 행의 0 높이를 반환하면 됩니다. 음수를 반환하면 TableView 은 델리게이트 항목에 따라 높이를 계산합니다.

참고: 행을 로드하려고 할 때(또는 레이아웃을 수행할 때) rowHeightProvider는 일반적으로 두 번 호출됩니다. 첫째, 행이 표시되고 로드되어야 하는지 확인하기 위해서입니다. 둘째, 모든 항목이 로드된 후 행의 높이를 결정하기 위해 호출합니다. 델리게이트 항목의 크기를 기준으로 행 높이를 계산해야 하는 경우 모든 항목이 로드된 후 두 번째 호출을 기다려야 합니다. isRowLoaded (행)을 호출하여 이를 확인할 수 있으며, 아직 그렇지 않은 경우 -1을 반환하면 됩니다.

행높이제공자, isRowLoaded() 및 Row heights and column widths도 참조하세요 .

rowSpacing : real

이 속성은 행 사이의 간격을 유지합니다.

기본값은 0 입니다.

rows : int [read-only]

이 속성은 테이블의 행 수를 보유합니다.

참고: rows 은 일반적으로 모델의 행 수와 같지만 보류 중인 모든 모델 변경이 처리될 때까지 일시적으로 다를 수 있습니다.

이 속성은 읽기 전용입니다.

selectionBehavior : enumeration [since 6.4]

이 속성은 사용자가 셀, 행 또는 열을 선택할 수 있는지 여부를 보유합니다.

Constant	설명
`TableView.SelectionDisabled`	사용자가 선택을 수행할 수 없습니다.
`TableView.SelectCells`	(기본값) 사용자가 개별 셀을 선택할 수 있습니다.
`TableView.SelectRows`	사용자가 행만 선택할 수 있음
`TableView.SelectColumns`	사용자는 열만 선택할 수 있습니다.

이 속성은 Qt 6.4에 도입되었습니다.

Selecting items, selectionMode, selectionModel, keyNavigationEnabled 을참조하십시오 .

selectionMode : enumeration [since 6.6]

selectionBehavior 가 TableView.SelectCells 로 설정된 경우 이 속성은 사용자가 한 번에 하나의 셀을 선택할 수 있는지 또는 여러 셀을 선택할 수 있는지를 보유합니다. selectionBehavior 가 TableView.SelectRows 으로 설정된 경우 이 속성은 사용자가 한 번에 하나의 행을 선택할 수 있는지 또는 여러 행을 선택할 수 있는지를 유지합니다. selectionBehavior 이 TableView.SelectColumns 으로 설정된 경우 이 속성은 사용자가 한 번에 하나의 열을 선택할 수 있는지, 아니면 여러 열을 선택할 수 있는지를 저장합니다.

다음 모드를 사용할 수 있습니다:

상수	설명
`TableView.SingleSelection`	사용자가 단일 셀, 행 또는 열을 선택할 수 있습니다.
`TableView.ContiguousSelection`	사용자가 연속된 단일 셀 블록을 선택할 수 있습니다. 선택하는 동안 `Shift` 수정자를 길게 누르면 기존 선택 항목을 더 크게 또는 더 작게 만들 수 있습니다.
`TableView.ExtendedSelection`	(기본값) 사용자는 여러 개의 개별 셀 블록을 선택할 수 있습니다. 선택하는 동안 `Shift` 수정자를 누르고 있으면 기존 선택 영역을 더 크게 또는 더 작게 만들 수 있습니다. 선택하는 동안 `Control` 수정자를 누르고 있으면 현재 선택을 지우지 않고 새 선택 블록을 시작할 수 있습니다.

이 속성은 Qt 6.6에 도입되었습니다.

Selecting items, selectionBehavior, selectionModel, keyNavigationEnabled 를참조하세요 .

selectionModel : ItemSelectionModel [since 6.2]

이 속성을 설정하여 어떤 델리게이트 항목을 선택한 것으로 표시할지, 어떤 항목을 현재로 표시할지 제어할 수 있습니다. 델리게이트에 required property bool selected 가 정의되어 있는 경우 TableView 은 선택 모델에서 해당 모델 항목의 선택 상태와 동기화 상태를 유지합니다. 델리게이트에 required property bool current 가 정의된 경우 TableView 는 selectionModel.currentIndex 와 동기화 상태를 유지합니다.

이 프로퍼티는 Qt 6.2에 도입되었습니다.

Selecting items, SelectionRectangle, keyNavigationEnabled, pointerNavigationEnabled 를참조하십시오 .

syncDirection : Qt::Orientations

syncView 가 TableView 에 설정된 경우 이 속성은 두 테이블의 플릭 방향 동기화를 제어합니다. 기본값은 Qt.Horizontal | Qt.Vertical 이며, 이는 어느 한 쪽 테이블을 어느 방향으로 밀면 다른 쪽 테이블도 같은 방향으로 같은 양만큼 밀린다는 의미입니다.

이 속성과 syncView 을 사용하면 오버슈트/언더슈트, 속도, 가속/감속 또는 리바운드 애니메이션 등이 다르더라도 두 테이블뷰를 플릭할 때 서로 원활하게 동기화할 수 있습니다.

일반적인 사용 사례는 여러 개의 헤더를 테이블과 함께 플릭하는 것입니다.

syncView 를참조하세요 .

syncView : TableView

TableView 의 이 속성이 다른 TableView 으로 설정되어 있으면 두 테이블 모두 syncDirection 에 따라 플릭, 열 너비/행 높이 및 간격이 동기화됩니다.

syncDirection 에 Qt.Horizontal 이 포함된 경우 현재 tableView의 열 너비, 열 간격 및 수평 플릭 이동은 syncView의 것과 동기화됩니다.

syncDirection 에 Qt.Vertical 이 포함된 경우 현재 tableView의 행 높이, 행 간격 및 수직 플릭 이동이 syncView와 동기화됩니다.

syncDirection도 참조하세요 .

topRow : int

이 속성은 현재 뷰 내부에 표시되는 최상위 행을 보유합니다.

leftColumn, rightColumn, bottomRow 를참조하십시오 .

첨부된 속성 문서

TableView.editDelegate : Component

이 첨부 프로퍼티는 편집 델리게이트를 보유합니다. 편집이 시작될 때 인스턴스화되고 편집하는 델리게이트에 부모가 됩니다. index , row 및 column 을 포함하여 TableView delegate 과 동일한 필수 속성을 지원합니다. display 및 edit 과 같은 모델의 속성도 사용할 수 있습니다(모델에 노출된 role names 에 따라 다름).

editTriggers 에 지정된 작업이 충족되고 현재 셀이 편집 가능한 상태가 되면 편집이 시작됩니다.

참고: 셀을 편집할 수 있게 하려면 모델에서 QAbstractItemModel::flags()를 재정의하고 Qt::ItemIsEditable 을 반환해야 합니다.

edit() 및 closeEditor()을 각각 호출하여 편집 델리게이트를 수동으로 열고 닫을 수도 있습니다. 그러면 Qt::ItemIsEditable 플래그는 무시됩니다.

사용자가 Qt::Key_Enter 또는 Qt::Key_Return ( TableView 에 QQuickItem::activeFocusOnTab 가 설정되어 있는 경우 Qt::Key_Tab 또는 Qt::Key_Backtab 도 누르면 편집이 종료됩니다.) 이 경우 TableView::commit 신호가 전송되어 편집 위임자가 수정된 데이터를 모델에 다시 쓰면서 응답할 수 있습니다. 다른 이유로 편집이 종료된 경우(예: 사용자가 Qt::Key_Escape)를 누르는 경우 신호가 전송되지 않습니다. 어떤 경우에도 destruction()가 마지막에 전송됩니다.

편집 델리게이트가 표시되는 동안에도 아래 셀은 계속 표시되므로 편집 델리게이트가 반투명하거나 전체 셀을 덮지 않는 경우 빛을 발합니다. 이를 원하지 않는 경우 편집 델리게이트의 루트 항목을 단색 Rectangle 으로 설정하거나 TableView delegate. 안에 있는 일부 항목을 숨길 수 있습니다. 후자는 그 안에 required property bool editing 속성을 정의하여 일부 하위 항목의 visible 속성에 바인딩하면 됩니다. 다음 스니펫은 그 방법을 보여줍니다:

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            required property bool editing

            Text {
                id: textField
                anchors.fill: parent
                anchors.margins: 5
                text: display
                visible: !editing
            }

            TableView.editDelegate: TextField {
                x: textField.x
                y: textField.y
                width: textField.width
                height: textField.height
                text: display
                TableView.onCommit: display = text
            }
        }

편집 델리게이트가 인스턴스화되면 TableView 은 QQuickItem::forceActiveFocus()을 호출합니다. 대신 편집 델리게이트의 하위 항목에 활성 포커스를 설정하려면 편집 델리게이트를 FocusScope 로 설정하세요.

editTriggers, TableView::commit, edit(), closeEditor() 및 Editing cells도 참조하세요 .

TableView.view : TableView

이 연결된 속성은 델리게이트 인스턴스를 관리하는 보기를 보유합니다. 델리게이트의 각 인스턴스에 첨부됩니다.

시그널 문서

[since 6.8] columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

이 신호는 열이 이동될 때 발생합니다. 열의 논리적 인덱스는 logicalIndex, 이전 인덱스는 oldVisualIndex, 새 인덱스 위치는 newVisualIndex 로 지정됩니다.

참고: 해당 핸들러는 onColumnMoved 입니다.

이 신호는 Qt 6.8에 도입되었습니다.

[since 6.5] layoutChanged()

이 신호는 loaded 행과 열의 레이아웃이 변경될 가능성이 있을 때마다 발생합니다. 특히 forceLayout()가 호출될 때뿐만 아니라 행이나 열의 크기를 조정하거나 행이나 열이 뷰포트에 들어오거나 나갈 때에도 발생합니다.

이 신호는 예를 들어 오버레이의 지오메트리를 업데이트하는 데 사용할 수 있습니다.

참고: 해당 핸들러는 onLayoutChanged 입니다.

이 신호는 Qt 6.5에 도입되었습니다.

forceLayout() 및 Overlays and underlays 을참조하십시오 .

[since 6.8] rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

이 신호는 행이 이동될 때 발생합니다. 행의 논리적 인덱스는 logicalIndex, 이전 인덱스는 oldVisualIndex, 새 인덱스 위치는 newVisualIndex 로 지정됩니다.

참고: 해당 핸들러는 onRowMoved 입니다.

이 신호는 Qt 6.8에 도입되었습니다.

첨부된 신호 문서

commit()

이 신호는 edit delegate

이 첨부 신호는 edit delegate 가 활성화되어 있고 사용자가 Qt::Key_Enter 또는 Qt::Key_Return 를 누르면 발생합니다. 또한 TableView 에 QQuickItem::activeFocusOnTab 가 설정되어 있고 사용자가 Qt::Key_Tab 또는 Qt::Key_Backtab 을 누르면 발생합니다.

언급된 이유 이외의 이유로 편집이 종료되면 이 신호는 전송되지 않습니다. 예를 들어 사용자가 Qt::Key_Escape 를 누르거나 델리게이트 외부를 탭하거나 편집 중인 행 또는 열이 삭제되거나 애플리케이션이 closeEditor()를 호출하는 경우 등이 여기에 포함됩니다.

신호를 받으면 편집 델리게이트는 수정된 데이터를 모델에 다시 써야 합니다.

참고: 이 프로퍼티는 delegate 이 아닌 edit delegate 에 연결해야 합니다.

참고: 해당 핸들러는 onCommit 입니다.

TableView::editDelegate, editTriggers, Editing cells도 참조하세요 .

pooled()

이 신호는 항목이 재사용 풀에 추가된 후에 발신됩니다. 이 신호를 사용하여 항목 내에서 진행 중인 타이머나 애니메이션을 일시 중지하거나 재사용할 수 없는 리소스를 확보할 수 있습니다.

이 신호는 reuseItems 속성이 true 인 경우에만 발생합니다.

참고: 해당 핸들러는 onPooled 입니다.

Reusing items, reuseItems, reused도 참조하세요 .

reused()

이 신호는 항목이 재사용된 후에 발생합니다. 이 시점에서 항목이 풀에서 꺼내져 콘텐츠 보기에 배치되고 인덱스, 행 및 열과 같은 모델 속성이 업데이트되었습니다.

모델에서 제공하지 않는 다른 속성은 항목이 재사용될 때 변경되지 않습니다. 델리게이트 내부에 상태를 저장하지 않는 것이 좋지만, 저장하는 경우에는 이 신호를 수신하면 해당 상태를 수동으로 재설정하세요.

이 신호는 항목을 처음 만들 때가 아니라 항목을 재사용할 때 발생합니다.

이 신호는 reuseItems 속성이 true 인 경우에만 발생합니다.

참고: 해당 핸들러는 onReused 입니다.

Reusing items, reuseItems, pooled 를참조하세요 .

메서드 문서

[since 6.4] point cellAtIndex(QModelIndex modelIndex)

모델에서 modelIndex 에 매핑되는 뷰의 셀을 반환합니다. 작업을 위한 편리한 함수입니다:

Qt.point(columnAtIndex(modelIndex), rowAtIndex(modelIndex))

셀은 단순히 행과 열을 단일 유형으로 결합한 point 입니다.

참고: point.x 은 열에 매핑되고 point.y 은 행에 매핑됩니다.

이 메서드는 Qt 6.4에 도입되었습니다.

Point cellAtPosition(point position, bool includeSpacing)

테이블에서 주어진 position 에 있는 셀을 반환합니다. position 은 contentItem 에 상대적이어야 합니다. loaded 셀이 position 와 교차하지 않으면 반환 값은 point(-1, -1) 입니다.

includeSpacing 이 true 으로 설정된 경우 셀의 바운딩 박스는 양쪽에 인접한 rowSpacing 과 columnSpacing 의 절반을 포함하는 것으로 간주됩니다. 기본값은 false 입니다.

참고: TableView 에 연결된 입력 핸들러는 뷰가 아닌 contentItem 에 설치됩니다. 따라서 핸들러가 보고한 위치는 mapping 없이 이 함수에 대한 호출에서 직접 사용할 수 있습니다.

columnSpacing 및 rowSpacing 을참조하세요 .

Point cellAtPosition(real x, real y, bool includeSpacing)

cellAtPosition(Qt.point(x, y), includeSpacing) 을 호출할 때 편리합니다.

[since 6.8] clearColumnReordering()

이전에 적용된 모든 열 재정렬을 재설정합니다.

참고: syncView 가 설정되어 있으면 이 함수에 대한 호출이 해당 뷰 항목으로 전달되어 열 순서가 재설정됩니다.

이 메서드는 Qt 6.8에 도입되었습니다.

clearColumnWidths()

setColumnWidth()로 설정된 모든 열 너비를 지웁니다.

참고: syncView 가 Qt.Horizontal syncDirection 와 함께 설정된 경우 동기화 보기가 열 너비를 제어합니다. 따라서 이 경우 이 함수에 대한 모든 호출은 동기화 보기로 대신 전달됩니다.

setColumnWidth(), clearRowHeights() 및 Row heights and column widths 를참조하세요 .

clearRowHeights()

setRowHeight()로 설정된 모든 행 높이를 지웁니다.

참고: syncView 가 설정된 경우 Qt.Vertical syncDirection 와 함께 동기화 보기가 행 높이를 제어합니다. 따라서 이 경우 이 함수에 대한 모든 호출은 동기화 보기로 대신 전달됩니다.

setRowHeight(), clearColumnWidths() 및 Row heights and column widths 를참조하세요 .

[since 6.8] clearRowReordering()

이전에 적용된 모든 행 재정렬을 재설정합니다.

참고: syncView 가 설정되어 있으면 이 함수에 대한 호출이 해당 뷰 항목으로 전달되어 행 순서가 재설정됩니다.

이 메서드는 Qt 6.8에 도입되었습니다.

[since 6.5] closeEditor()

사용자가 셀을 편집 중인 경우 이 함수를 호출하면 편집이 중지되고 편집 델리게이트 인스턴스가 파괴됩니다.

이 메서드는 Qt 6.5에 도입되었습니다.

edit(), TableView::editDelegate, 및 Editing cells 를참조하십시오 .

[since 6.4] int columnAtIndex(QModelIndex modelIndex)

모델에서 modelIndex 에 매핑되는 뷰의 열을 반환합니다.

이 메서드는 Qt 6.4에 도입되었습니다.

rowAtIndex() 및 index()도 참조하십시오 .

[since 6.2] real columnWidth(int column)

주어진 column 의 너비를 반환합니다. 열이 로드되지 않아서 보이지 않는 경우 반환값은 -1 입니다.

이 메서드는 Qt 6.2에 도입되었습니다.

setColumnWidth(), columnWidthProvider, implicitColumnWidth(), isColumnLoaded() 및 Row heights and column widths 를참조하십시오 .

[since 6.5] edit(QModelIndex modelIndex)

이 함수는 modelIndex 을 나타내는 셀에 대한 편집 세션을 시작합니다. 사용자가 이미 다른 셀을 편집 중인 경우 해당 세션이 종료됩니다.

일반적으로 editTriggers 대신 다른 방법으로 편집 세션을 시작하도록 지정할 수 있습니다. 이 방법으로 충분하지 않은 경우 이 기능을 사용할 수 있습니다. 셀 편집을 완전히 제어하고 TableView 이 간섭하지 못하도록 하려면 editTriggers 을 TableView.NoEditTriggers 으로 설정하세요.

참고: selection model 의 current index 도 modelIndex 로 변경됩니다.

이 방법은 Qt 6.5에 도입되었습니다.

closeEditor(), editTriggers, TableView::editDelegate, Editing cells도 참조하십시오 .

qreal explicitColumnWidth(int column)

setColumnWidth()로 설정된 column 의 너비를 반환합니다. columnWidthProvider 을 사용 중인 경우 이 너비는 열의 실제 너비와 다를 수 있습니다. 열의 실제 너비를 가져오려면 columnWidth()를 사용합니다.

반환 값이 0 와 같으면 열을 숨기라는 지시를 받았음을 의미합니다. 반환값이 -1 같으면 열에 명시적인 너비가 설정되지 않았음을 의미합니다.

setColumnWidth(), columnWidth() 및 Row heights and column widths 를참조하세요 .

qreal explicitRowHeight(int row)

setRowHeight()로 설정된 row 의 높이를 반환합니다. rowHeightProvider 을 사용 중인 경우 이 높이는 열의 실제 높이와 다를 수 있습니다. 행의 실제 높이를 가져오려면 rowHeight()를 사용합니다.

반환 값이 0 와 같으면 행을 숨기라는 지시를 받았음을 의미합니다. 반환값이 -1 같으면 행에 대한 명시적 높이가 설정되지 않았음을 의미합니다.

참고: syncView 가 Qt.Vertical syncDirection 와 함께 설정된 경우 동기화 보기가 행 높이를 제어합니다. 따라서 이 경우 이 함수에 대한 모든 호출은 동기화 보기로 대신 전달됩니다.

setRowHeight(), rowHeight() 및 Row heights and column widths 를참조하세요 .

forceLayout()

모델의 변경 사항에 대한 응답은 프레임당 한 번만 처리되도록 일괄 처리됩니다. 즉, 스크립트가 실행되는 동안에는 TableView 에 변경 사항이 표시되는 것이 지연됩니다. rowSpacing 또는 leftMargin 과 같은 속성을 변경할 때도 마찬가지입니다.

이 메서드는 TableView 가 레이아웃을 즉시 업데이트하여 최근 변경 사항을 적용하도록 합니다.

이 함수를 호출하면 표시되는 각 행과 열의 크기와 위치가 다시 평가됩니다. rowHeightProvider 또는 columnWidthProvider 에 할당된 함수가 이미 할당된 값과 다른 값을 반환하는 경우에 이 함수가 필요합니다.

[since 6.2] real implicitColumnWidth(int column)

주어진 column 의 암시적 너비를 반환합니다. 현재 해당 열에 있는 loaded 델리게이트 항목 중 가장 큰 implicitWidth 입니다.

column 가 로드되지 않아서 보이지 않으면 반환값은 -1 입니다.

이 메서드는 Qt 6.2에 도입되었습니다.

columnWidth(), isRowLoaded() 및 Row heights and column widths 를참조하십시오 .

[since 6.2] real implicitRowHeight(int row)

주어진 row 의 암시적 높이를 반환합니다. 현재 해당 행에 있는 loaded 델리게이트 항목 중 가장 큰 implicitHeight 입니다.

row 이 로드되지 않아서 보이지 않는 경우 반환값은 -1 입니다.

이 메서드는 Qt 6.2에 도입되었습니다.

rowHeight(), isColumnLoaded() 및 Row heights and column widths 를참조하십시오 .

[since 6.4.3] QModelIndex index(int row, int column)

뷰에서 row 및 column 에 매핑되는 QModelIndex 을 반환합니다.

row 와 column 는 뷰의 행과 열(테이블 행과 테이블 열)이어야 하며 모델의 행과 열이 아니어야 합니다. 일반 TableView 의 경우 model.index(row, column). 을 호출하는 것과 같습니다. 그러나 데이터 모델이 트리 구조를 테이블로 평평하게 만드는 내부 프록시 모델 내부에 래핑된 TableView 의 서브클래스(예: TreeView)의 경우 이 함수를 사용하여 모델 인덱스를 확인해야 합니다.

이 방법은 Qt 6.4.3에 도입되었습니다.

rowAtIndex() 및 columnAtIndex()도 참조하십시오 .

[since 6.2] bool isColumnLoaded(int column)

지정된 column 이 로드된 경우 true 을 반환합니다.

TableView 에서 뷰 내에 열을 표시하는 데 필요한 델리게이트 항목을 로드한 경우 열이 로드됩니다. 이는 일반적으로 열이 사용자에게 표시된다는 의미이기도 하지만 항상 그런 것은 아닙니다.

이 함수는 열의 델리게이트 항목을 반복해야 할 때마다(예: columnWidthProvider 에서) 델리게이트 항목을 반복할 수 있는지 확인하기 위해 사용할 수 있습니다.

이 메서드는 Qt 6.2에 도입되었습니다.

[since 6.2] bool isRowLoaded(int row)

지정된 row 이 로드된 경우 true 을 반환합니다.

TableView 에서 뷰 내부에 행을 표시하는 데 필요한 델리게이트 항목을 로드한 경우 행이 로드됩니다. 이는 일반적으로 사용자에게 행이 표시된다는 의미이기도 하지만 항상 그런 것은 아닙니다.

이 함수는 예를 들어 rowHeightProvider 에서와 같이 행의 델리게이트 항목을 반복해야 할 때마다 델리게이트 항목을 반복할 수 있는지 확인하기 위해 사용할 수 있습니다.

이 메서드는 Qt 6.2에 도입되었습니다.

Item itemAtCell(point cell)

델리게이트 항목이 로드된 경우 cell 로, 그렇지 않으면 null 으로 반환합니다.

참고: 일반적으로 뷰에 표시되는 항목만 로드됩니다. 셀을 뷰 밖으로 밀면 그 안에 있는 항목은 언로드되거나 재활용 풀에 배치됩니다. 따라서 반환 값은 절대로 저장해서는 안 됩니다.

[since 6.5] Item itemAtIndex(QModelIndex index)

index 을 나타내는 셀에 대해 인스턴스화된 델리게이트 항목을 반환합니다. 항목이 loaded 이 아닌 경우 값은 null 입니다.

참고: 일반적으로 뷰에 표시되는 항목만 로드됩니다. 셀을 뷰 밖으로 밀면 그 안에 있는 항목은 언로드되거나 휴지통에 배치됩니다. 따라서 반환 값은 절대로 저장해서는 안 됩니다.

참고: model 가 QAbstractItemModel 이 아닌 경우 itemAtCell(Qt.point(열, 행)을 사용할 수도 있습니다.) 단, point.x 은 열에 매핑되고 point.y 은 행에 매핑된다는 점에 유의하세요.

이 메서드는 Qt 6.5에 도입되었습니다.

[since 6.4] QModelIndex modelIndex(point cell)

작업을 위한 편의 기능입니다:

index(cell.y, cell.x)

cell 는 단순히 행과 열을 하나의 유형으로 결합한 point 입니다.

참고: point.x 은 열에 매핑되고 point.y 은 행에 매핑됩니다.

이 메서드는 Qt 6.4에 도입되었습니다.

index()도 참조하세요 .

[since 6.8] moveColumn(int source, int destination)

열을 source 위치에서 destination 위치로 이동합니다.

참고: syncView 을 설정하면 동기화 보기가 열 재정렬을 위한 내부 인덱스 매핑을 제어합니다. 따라서 이 경우 이 함수에 대한 호출은 대신 동기화 보기로 전달됩니다.

이 메서드는 Qt 6.8에 도입되었습니다.

[since 6.8] moveRow(int source, int destination)

source 위치에서 destination 위치로 행을 이동합니다.

참고: syncView 을 설정하면 동기화 보기가 행 재정렬을 위한 내부 인덱스 매핑을 제어합니다. 따라서 이 경우 이 함수에 대한 호출은 동기화 보기로 대신 전달됩니다.

이 메서드는 Qt 6.8에 도입되었습니다.

positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)

cell 이 mode 에 지정된 위치에 있도록 contentX 과 contentY 위치 mode 는 다음의 또는- 조합일 수 있습니다:

상수	설명
`TableView.AlignLeft`	셀을 뷰의 왼쪽에 배치합니다.
`TableView.AlignHCenter`	뷰의 가로 중앙에 셀을 배치합니다.
`TableView.AlignRight`	뷰의 오른쪽에 셀을 배치합니다.
`TableView.AlignTop`	뷰의 맨 위에 셀을 배치합니다.
`TableView.AlignVCenter`	뷰의 세로 중앙에 셀을 배치합니다.
`TableView.AlignBottom`	뷰의 맨 아래에 셀을 배치합니다.
`TableView.AlignCenter`	(TableView.AlignHCenter \| TableView.AlignVCenter)와 동일합니다.
`TableView.Visible`	셀의 일부가 표시되면 아무 작업도 수행하지 않습니다. 그렇지 않으면 셀 전체가 보이도록 콘텐츠 항목을 이동합니다.
`TableView.Contain`	셀 전체가 표시되면 아무 조치도 취하지 않습니다. 그렇지 않으면 셀 전체가 보이도록 콘텐츠 항목을 이동합니다. 셀이 보기보다 큰 경우 셀의 왼쪽 위쪽이 선호됩니다.

세로 정렬을 지정하지 않으면 세로 위치가 무시됩니다. 가로 정렬도 마찬가지입니다.

선택적으로 offset 을 지정하여 콘텐츠X 및 콘텐츠Y를 대상 맞춤에서 픽셀 수만큼 더 이동시킬 수 있습니다. 예를 들어 셀 [10, 10]이 왼쪽 상단 모서리에 5px 여백을 두도록 뷰를 배치하려는 경우 이렇게 할 수 있습니다:

positionViewAtCell(Qt.point(10, 10), TableView.AlignLeft | TableView.AlignTop, Qt.point(-5, -5))

Qt 6.4부터는 전체 셀의 경계 사각형이 아닌 cell 내부의 사각형에 위치하도록 subRect 을 지정할 수 있습니다. 셀이 뷰보다 커서 특정 부분만 보이도록 하려는 경우 유용할 수 있습니다. subRect 은 valid 이 되어야 합니다.

참고: 특정 셀에 뷰를 배치하기 위해 contentX 또는 contentY를 사용하는 것은 권장하지 않습니다. 표의 시작 부분에서 항목을 제거해도 다른 모든 항목의 위치가 변경되지 않으므로 신뢰할 수 없습니다. TableView 또한 속도를 최적화하기 위해 행과 열을 대략적인 위치에 배치할 수 있습니다. 유일한 예외는 셀이 뷰에 이미 표시되어 있는 경우이며, 이 경우 itemAtCell()를 호출하여 미리 확인할 수 있습니다.

메서드는 컴포넌트가 완료된 후에만 호출해야 합니다. 시작 시 뷰의 위치를 지정하려면 이 메서드를 Component.onCompleted에서 호출해야 합니다. 예를 들어 뷰를 끝에 배치하려면 이 메서드를 호출해야 합니다:

Component.onCompleted: positionViewAtCell(Qt.point(columns - 1, rows - 1), TableView.AlignRight | TableView.AlignBottom)

참고: 이 함수의 두 번째 인수는 예전에는 Qt.Alignment였습니다. 이전 버전과의 호환성을 위해 해당 열거형을 계속 사용할 수 있습니다. PositionMode를 사용하도록 변경된 것은 Qt 6.4에서 이루어졌습니다.

animate 를참조하십시오 .

positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)

column 가 mode, offset 및 subRect 에 지정된 위치에 있도록 {Flickable::}{contentX} 를 위치시킵니다.

호출에 편리한 메서드

positionViewAtCell(Qt.point(column, 0), mode & Qt.AlignHorizontal_Mask, offset, subRect)

[since 6.5] positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect)

index 이 mode, offset 및 subRect 에서 지정한 위치에 위치하도록 뷰를 배치합니다.

편리한 호출 메서드

positionViewAtRow(rowAtIndex(index), mode & Qt.AlignVertical_Mask, offset.y, subRect)
positionViewAtColumn(columnAtIndex(index), mode & Qt.AlignVertical_Mask, offset.x, subRect)

이 메서드는 Qt 6.5에 도입되었습니다.

positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)

row 가 mode, offset 및 subRect 에 의해 지정된 위치에 위치하도록 {Flickable::}{contentY} 를 배치합니다.

호출을 위한 편리한 메서드

positionViewAtCell(Qt.point(0, row), mode & Qt.AlignVertical_Mask, offset, subRect)

[since 6.4] int rowAtIndex(QModelIndex modelIndex)

모델에서 modelIndex 에 매핑되는 뷰의 행을 반환합니다.

이 메서드는 Qt 6.4에 도입되었습니다.

columnAtIndex() 및 index()도 참조하십시오 .

[since 6.2] real rowHeight(int row)

주어진 row 의 높이를 반환합니다. 행이 로드되지 않아서 보이지 않는 경우 반환값은 -1 입니다.

이 메서드는 Qt 6.2에 도입되었습니다.

setRowHeight(), rowHeightProvider, implicitRowHeight(), isRowLoaded() 및 Row heights and column widths도 참조하십시오 .

setColumnWidth(int column, real size)

column 열의 명시적 열 너비를 size 로 설정합니다.

이 함수로 설정한 값을 다시 읽으려면 explicitColumnWidth()를 사용해야 합니다. columnWidth()는 열의 실제 크기를 반환하며, columnWidthProvider 가 설정된 경우 이 값은 달라질 수 있습니다.

TableView 에서 column 의 너비를 확인해야 하는 경우 먼저 columnWidthProvider 를 호출하려고 시도합니다. 공급자가 설정되지 않은 경우에만 이 함수로 설정한 너비가 기본적으로 사용됩니다. 그러나 공급자 내에서 explicitColumnWidth()를 호출할 수 있으며, 필요한 경우 항상 특정 간격 내에 있도록 값을 조정할 수 있습니다. 다음 스니펫은 이를 수행하는 방법에 대한 예시를 보여줍니다:

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return Math.max(100, w);
    return implicitColumnWidth(column)
}

size 이 0 과 같으면 열이 숨겨집니다. size 이 -1 과 같으면 열이 implicitColumnWidth()을 사용하도록 다시 설정됩니다. 모델 크기를 벗어나는 열에 대해 열 크기를 지정할 수 있습니다.

참고: model 을 변경하면 설정한 크기는 지워지지 않습니다. 크기를 지우려면 clearColumnWidths()을 명시적으로 호출해야 합니다.

참고: syncView 이 설정된 경우 Qt.Horizontal syncDirection 과 함께 동기화 보기가 열 너비를 제어합니다. 따라서 이 경우 이 함수에 대한 모든 호출은 동기화 보기로 대신 전달됩니다.

참고: 열이 많은 모델의 경우 시작 시 모든 열의 너비를 설정하기 위해 setColumnWidth()를 사용하는 것은 차선책이 될 수 있습니다. 이렇게 하면 시작 시간과 메모리(모든 너비를 저장하는 데 사용)가 소모됩니다. 보다 확장 가능한 접근 방식은 columnWidthProvider 를 대신 사용하거나 델리게이트의 암시적 너비에 의존하는 것입니다. columnWidthProvider 은 필요할 때만 호출되며 모델의 크기에 영향을 받지 않습니다.

columnWidth(), explicitColumnWidth(), setRowHeight(), clearColumnWidths() 및 Row heights and column widths 를참조하세요 .

setRowHeight(int row, real size)

row 행의 명시적 행 높이를 size 으로 설정합니다.

이 함수로 설정한 값을 다시 읽으려면 explicitRowHeight()를 사용해야 합니다. rowHeight()는 행의 실제 높이를 반환하며, rowHeightProvider 가 설정된 경우 이 값은 달라질 수 있습니다.

TableView 에서 row 의 높이를 확인해야 하는 경우 먼저 rowHeightProvider 를 호출하려고 시도합니다. 공급자가 설정되지 않은 경우에만 이 함수로 설정한 높이가 기본적으로 사용됩니다. 그러나 공급자 내에서 explicitRowHeight()를 호출할 수 있으며, 필요한 경우 항상 특정 간격 내에 있도록 값을 조정할 수 있습니다. 다음 스니펫은 이를 수행하는 방법에 대한 예시를 보여줍니다:

rowHeightProvider: function(row) {
    let h = explicitRowHeight(row)
    if (h >= 0)
        return Math.max(100, h);
    return implicitRowHeight(row)
}

size 이 0 과 같으면 행이 숨겨집니다. size 이 -1 과 같으면 행이 implicitRowHeight()를 사용하도록 다시 설정됩니다. 모델 크기를 벗어나는 행에 대해 행 크기를 지정할 수 있습니다.

참고: model 을 변경하면 설정한 크기는 지워지지 않습니다. 크기를 지우려면 clearRowHeights()을 명시적으로 호출해야 합니다.

참고: syncView 이 설정된 경우 Qt.Vertical syncDirection 과 함께 동기화 보기가 행 높이를 제어합니다. 따라서 이 경우 이 함수에 대한 모든 호출은 동기화 보기로 대신 전달됩니다.

참고: 행이 많은 모델의 경우 시작 시 모든 행의 높이를 설정하기 위해 setRowHeight()를 사용하는 것은 차선책일 수 있습니다. 이렇게 하면 시작 시간과 메모리(모든 높이를 저장하는 데 사용)가 소모됩니다. 보다 확장 가능한 접근 방식은 rowHeightProvider 를 대신 사용하거나 델리게이트의 암시적 높이에 의존하는 것입니다. rowHeightProvider 은 필요할 때만 호출되며 모델의 크기에 영향을 받지 않습니다.

rowHeight(), explicitRowHeight(), setColumnWidth() 및 Row heights and column widths 을참조하세요 .

© 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.