Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

TableModel QML Type

간단한 테이블 모델을 캡슐화합니다. 더 보기...

Import Statement: import Qt.labs.qmlmodels

속성

방법

  • void appendRow(var row)
  • void clear()
  • variant data(QModelIndex index, string role)
  • var getRow(int rowIndex)
  • QModelIndex index(int row, int column)
  • void insertRow(int rowIndex, var row)
  • void moveRow(int fromRowIndex, int toRowIndex, int rows)
  • void removeRow(int rowIndex, int rows)
  • bool setData(QModelIndex index, variant value, string role)
  • void setRow(int rowIndex, var row)

상세 설명

TableModel 유형은 TableView 와 함께 사용할 수 있는 테이블 모델의 데이터로 JavaScript/JSON 객체를 저장합니다. 이 유형은 C++에서 사용자 정의 QAbstractTableModel 서브클래스를 생성할 필요 없이 매우 간단한 모델을 지원하기 위해 고안되었습니다.

import QtQuick
import QtQuick.Window
import Qt.labs.qmlmodels

Window {
    width: 400
    height: 400
    visible: true

    TableView {
        anchors.fill: parent
        columnSpacing: 1
        rowSpacing: 1
        boundsBehavior: Flickable.StopAtBounds

        model: TableModel {
            TableModelColumn { display: "checked" }
            TableModelColumn { display: "amount" }
            TableModelColumn { display: "fruitType" }
            TableModelColumn { display: "fruitName" }
            TableModelColumn { display: "fruitPrice" }

            // Each row is one type of fruit that can be ordered
            rows: [
                {
                    // Each property is one cell/column.
                    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
                }
            ]
        }
        delegate:  TextInput {
            text: model.display
            padding: 12
            selectByMouse: true

            onAccepted: model.display = text

            Rectangle {
                anchors.fill: parent
                color: "#efefef"
                z: -1
            }
        }
    }
}

모델의 초기 행 데이터는 rows 속성을 사용하거나 appendRow()를 호출하여 설정됩니다. 모델의 각 열은 TableModelColumn 인스턴스를 선언하여 지정되며, 각 인스턴스의 순서가 해당 열의 인덱스를 결정합니다. 모델의 Component::completed() 신호가 발산되면 열과 역할이 확정되며, 이후 모델의 수명 기간 동안 고정됩니다.

특정 행에 접근하려면 getRow() 함수를 사용할 수 있습니다. 또한 rows 속성을 통해 모델의 JavaScript 데이터에 직접 접근할 수도 있지만, 이 방법으로 모델 데이터를 수정할 수는 없습니다.

새 행을 추가하려면 appendRow() 및 insertRow()을 사용합니다. 기존 행을 수정하려면 setRow(), moveRow(), removeRow() 및 clear()을 사용합니다.

또한 위의 예제에서 볼 수 있듯이, 델리게이트를 통해 모델의 데이터를 수정할 수도 있습니다:

        delegate:  TextInput {
            text: model.display
            padding: 12
            selectByMouse: true

            onAccepted: model.display = text

            Rectangle {
                anchors.fill: parent
                color: "#efefef"
                z: -1
            }
        }

수정 대상의 데이터 유형이 설정된 데이터의 유형과 일치하지 않는 경우, QVariant 를 통해 자동으로 변환됩니다.

지원되는 행 데이터 구조

TableModel은 JavaScript/JSON 데이터와 연동되도록 설계되었으며, 각 행은 간단한 키-값 쌍의 목록으로 구성됩니다:

{
    // Each property is one cell/column.
    checked: false,
    amount: 1,
    fruitType: "Apple",
    fruitName: "Granny Smith",
    fruitPrice: 1.50
},
// ...

Qt에서 모델 조작은 행 및 열 인덱스를 통해 이루어지며, 객체 키는 순서가 정해져 있지 않기 때문에 각 열은 ` TableModelColumn`을 통해 명시해야 합니다. 이를 통해 Qt의 내장 역할을 각 행 객체의 임의 속성에 매핑할 수 있습니다.

복잡한 행 구조도 지원되지만, 기능은 제한적입니다. TableModel은 각 행의 구조를 파악할 방법이 없으므로 이를 조작할 수 없습니다. 그 결과, TableModel이 ` rows `에 저장한 모델 데이터의 복사본은 QML에서 설정된 소스 데이터와 동기화되지 않습니다. 이러한 이유로 데이터 조작은 지원되지 않습니다.

예를 들어, 각 행이 배열이고 각 셀이 객체인 데이터 소스를 사용하고자 한다고 가정해 봅시다. 이 데이터 소스를 TableModel과 함께 사용하려면 다음과 같이 게터(getter)를 정의합니다.

TableModel {
    TableModelColumn {
        display: function(modelIndex) { return rows[modelIndex.row][0].checked }
    }
    // ...

    rows: [
        [
            { checked: false, checkable: true },
            { amount: 1 },
            { fruitType: "Apple" },
            { fruitName: "Granny Smith" },
            { fruitPrice: 1.50 }
        ]
        // ...
    ]
}

위의 행은 복잡한 행의 한 예시입니다.

참고: 복합 행을 사용할 때는 appendRow(), removeRow() 등과 같은행 조작 함수가 지원되지 않습니다.

TableModel에서 DelegateChooser 사용

대부분의 실제 사용 사례에서는 TableModel을 사용하는 TableView 의 델리게이트로 DelegateChooser 를 사용하는 것이 권장됩니다. 이렇게 하면 관련 델리게이트에서 특정 역할을 사용할 수 있습니다. 예를 들어, 위의 코드 조각은 다음과 같이 DelegateChooser 를 사용하도록 재작성할 수 있습니다:

import QtQuick
import QtQuick.Controls
import Qt.labs.qmlmodels

ApplicationWindow {
    width: 400
    height: 400
    visible: true

    TableView {
        anchors.fill: parent
        columnSpacing: 1
        rowSpacing: 1
        boundsBehavior: Flickable.StopAtBounds

        model: TableModel {
            TableModelColumn { display: "checked" }
            TableModelColumn { display: "amount" }
            TableModelColumn { display: "fruitType" }
            TableModelColumn { display: "fruitName" }
            TableModelColumn { display: "fruitPrice" }

            // Each row is one type of fruit that can be ordered
            rows: [
                {
                    // Each property is one cell/column.
                    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
                }
            ]
        }
        delegate: DelegateChooser {
            DelegateChoice {
                column: 0
                delegate: CheckBox {
                    checked: model.display
                    onToggled: model.display = checked
                }
            }
            DelegateChoice {
                column: 1
                delegate: SpinBox {
                    value: model.display
                    onValueModified: model.display = value
                }
            }
            DelegateChoice {
                delegate: TextField {
                    text: model.display
                    selectByMouse: true
                    implicitWidth: 140
                    onAccepted: model.display = text
                }
            }
        }
    }
}

가장 구체적인 델리게이트가 먼저 선언됩니다. 인덱스 0 및 1 에 위치한 열은 bool 및 integer 데이터형을 가지므로, 각각 CheckBox 및 SpinBox 를 사용합니다. 나머지 열은 간단히 TextField 를 사용할 수 있으므로, 해당 델리게이트는 대체용으로 마지막에 선언됩니다.

외부 JSON 소스와 함께 TableModel 사용하기

JSON 객체 내 데이터의 구조가 TableModel에 정의된 구조와 일치하는 경우, rows 속성을 사용하여 해당 데이터를 모델에 직접 할당할 수 있습니다. 데이터의 모든 행은 모델에 정의된 열과 일치해야 합니다.

예를 들어, 모델이 다음과 같이 정의되어 있다고 가정해 보겠습니다.

            model: TableModel {
                TableModelColumn { display: "driverId" }
                TableModelColumn { display: "code" }
                TableModelColumn { display: "url" }
                TableModelColumn { display: "givenName" }
                TableModelColumn { display: "familyName" }
                TableModelColumn { display: "dateOfBirth" }
                TableModelColumn { display: "nationality" }
            }

소스에 필요한 데이터는 있지만 반드시 요구되는 구조를 따르는 것은 아닐 경우, 데이터를 다운로드하여 모델이 정의한 구조에 부합하는 형태로 파싱한 후 그 결과를 직접 할당할 수 있습니다.

    function requestJson() {
        let doc = new XMLHttpRequest()
        doc.onreadystatechange = function() {
            if (doc.readyState === XMLHttpRequest.DONE) {
                var root = JSON.parse(doc.responseText)
                var race = root.MRData.RaceTable.Races[0]
                var raceResults = race.Results
                var drivers = []
                for (let i = 0; i < raceResults.length; ++i) {
                    drivers.push(raceResults[i].Driver)
                }
                tableView.model.rows = drivers
                print(JSON.stringify(drivers))
            }
        }

        doc.open("GET", "https://api.jolpi.ca/ergast/f1/2005/1/results.json")
        doc.send()
    }

그리고 그 결과를 직접 할당할 수 있습니다

    Component.onCompleted: requestJson()

JavaScript 파일을 모듈로 가져와 JSON 객체를 제공할 수도 있습니다. 이에 대한 예제는 TreeModel 문서를 참조하십시오.

경고: JSON 데이터가 신뢰할 수 있는 출처에서 제공되는지반드시 확인하십시오 . 모델은 입력에 따라 행을 동적으로 채우므로, 형식이 잘못되었거나 신뢰할 수 없는 JSON은 예기치 않은 동작이나 성능 문제를 일으킬 수 있습니다.

관련 항목: TableModelColumn, TableView 및 QAbstractTableModel.

속성 문서

columnCount : int [read-only]

이 읽기 전용 속성은 모델의 열 수를 나타냅니다.

rows 속성이 설정되거나 appendRow()이 처음 호출된 후, 모델의 수명 기간 동안 열 수는 고정됩니다.

rowCount : int [read-only]

이 읽기 전용 속성은 모델에 포함된 행의 수를 나타냅니다.

이 값은 모델에 행이 추가되거나 제거될 때마다 변경됩니다.

rows : var

이 속성은 모델 데이터를 행의 배열 형태로 저장합니다:

            rows: [
                {
                    // Each property is one cell/column.
                    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
                }
            ]

getRow(), setRow(), moveRow(), appendRow(), insertRow(), clear(), rowCount 및 columnCount도 참조하십시오 .

메서드 문서

void appendRow(var row)

row 에 있는 값(셀)을 사용하여 모델의 끝에 새 행을 추가합니다.

model.appendRow({
    checkable: true,
    amount: 1,
    fruitType: "Pear",
    fruitName: "Williams",
    fruitPrice: 1.50,
})

insertRow(), setRow(), removeRow()도 참조하십시오 .

void clear()

모델에서 모든 행을 제거합니다.

removeRow()도 참조하십시오 .

variant data(QModelIndex index, string role)

지정된 index 에 위치한 테이블 셀의 데이터를, 지정된 role 에 속하는 값으로 반환합니다.

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

var getRow(int rowIndex)

모델 내의 rowIndex 위치에 있는 행을 반환합니다.

이는 rows 속성을 통해 행에 직접 접근하는 것과 동일하다는 점에 유의하십시오:

Component.onCompleted: {
    // These two lines are equivalent.
    console.log(model.getRow(0).display);
    console.log(model.rows[0].fruitName);
}

참고: 반환된객체를 사용하여 모델의 내용을 수정할 수는 없습니다. 대신 setRow()을 사용하십시오.

setRow(), appendRow(), insertRow(), removeRow(), moveRow()도 참조하십시오 .

QModelIndex index(int row, int column)

주어진 ` row ` 및 ` column`을 참조하는 ` QModelIndex ` 객체를 반환합니다. 이 객체는 ` data()` 함수에 전달하여 해당 셀의 데이터를 가져오거나, ` setData()` 함수에 전달하여 해당 셀의 내용을 편집하는 데 사용할 수 있습니다.

import QtQml 2.14
import Qt.labs.qmlmodels 1.0

TableModel {
    id: model

    TableModelColumn { display: "fruitType" }
    TableModelColumn { display: "fruitPrice" }

    rows: [
        { fruitType: "Apple", fruitPrice: 1.50 },
        { fruitType: "Orange", fruitPrice: 2.50 }
    ]

    Component.onCompleted: {
        for (var r = 0; r < model.rowCount; ++r) {
            console.log("An " + model.data(model.index(r, 0)).display +
                        " costs " + model.data(model.index(r, 1)).display.toFixed(2))
        }
    }
}

QModelIndex 및 QML의 관련 클래스와 data()도 참조하십시오 .

void insertRow(int rowIndex, var row)

rowIndex 위치에 row 에 있는 값(셀)을 사용하여 모델에 새 행을 추가합니다.

model.insertRow(2, {
    checkable: true, checked: false,
    amount: 1,
    fruitType: "Pear",
    fruitName: "Williams",
    fruitPrice: 1.50,
})

rowIndex 는 테이블 내의 기존 항목을 가리키거나, 테이블 끝을 넘어선 위치를 가리켜야 합니다(이는 appendRow()와 동일합니다).

appendRow(), setRow(), removeRow(), rowCount도 참조하십시오 .

void moveRow(int fromRowIndex, int toRowIndex, int rows)

rows 를 fromRowIndex 인덱스에서 toRowIndex 인덱스로 이동합니다.

'from' 및 'to' 범위는 반드시 존재해야 합니다. 예를 들어, 목록의 처음 3개 항목을 목록 끝으로 이동하려면:

model.moveRow(0, model.rowCount - 3, 3)

appendRow(), insertRow(), removeRow(), rowCount도 참조하십시오 .

void removeRow(int rowIndex, int rows = 1)

rowIndex 에 있는 여러 개의 rows 를 모델에서 제거합니다.

clear() 및 rowCount도 참조하십시오 .

bool setData(QModelIndex index, variant value, string role)

role 로 지정된 데이터 필드를, index 에서 지정한 테이블 셀에 value 로 삽입하거나 업데이트합니다. 성공하면 true를, 실패하면 false를 반환합니다.

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

void setRow(int rowIndex, var row)

모델 내 rowIndex 에 있는 행을 row 로 변경합니다.

모든 열/셀은 row 에 포함되어 있어야 하며, 올바른 순서로 정렬되어야 합니다.

model.setRow(0, {
    checkable: true,
    amount: 1,
    fruitType: "Pear",
    fruitName: "Williams",
    fruitPrice: 1.50,
})

rowIndex 가 rowCount() 와 동일할 경우, 모델에 새로운 행이 추가됩니다. 그렇지 않은 경우, rowIndex 는 모델 내의 기존 행을 가리켜야 합니다.

appendRow(), insertRow(), rowCount도 참조하십시오 .

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