qt-qml

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QML and Qt Quick

QML与Qt Quick

QML vs Widgets: When to Choose QML

QML与Widgets：何时选择QML

Use QML when...	Use Widgets when...
Building modern, animated, fluid UIs	Building traditional desktop tools
Targeting mobile or embedded	Heavy data tables and forms
Designers are involved in the UI	Rich text editing required
GPU-accelerated rendering needed	Complex platform widget integration
Writing a new app from scratch	Extending an existing widget app

For new Python/PySide6 desktop applications, QML offers better visual results with less code. For data-heavy enterprise tools, widgets remain the pragmatic choice.

Bootstrap and architecture — see references/qml-architecture.md

选择QML的场景...	选择Widgets的场景...
构建现代化、带动画的流畅UI	构建传统桌面工具
面向移动或嵌入式平台	处理大量数据的表格和表单
UI设计有设计师参与	需要富文本编辑功能
需要GPU加速渲染	复杂平台组件集成
从零开始开发新应用	扩展现有widget应用

对于全新的Python/PySide6桌面应用，QML能用更少的代码实现更好的视觉效果。对于数据密集型的企业工具，Widgets仍是务实之选。

启动与架构 —— 详见references/qml-architecture.md

Official Best Practices (Qt Quick)

Qt Quick官方最佳实践

1. Type-safe property declarations — Always use explicit types, not

var

qml

// WRONG — prevents static analysis, unclear errors
property var name

// CORRECT
property string name
property int count
property MyModel optionsModel

2. Prefer declarative bindings over imperative assignments:

qml

// WRONG — imperative assignment overwrites bindings, breaks Qt Design Studio
Rectangle {
    Component.onCompleted: color = "red"
}

// CORRECT — declarative binding, evaluates once at load
Rectangle {
    color: "red"
}

3. Interaction signals over value-change signals:

qml

// WRONG — valueChanged fires on clamping/rounding, causes event cascades
Slider { onValueChanged: model.update(value) }

// CORRECT — moved only fires on user interaction
Slider { onMoved: model.update(value) }

4. Don't anchor the immediate children of Layouts:

qml

// WRONG — anchors on direct Layout children cause binding loops
RowLayout {
    Rectangle { anchors.fill: parent }
}

// CORRECT — use Layout attached properties
RowLayout {
    Rectangle {
        Layout.fillWidth: true
        Layout.preferredHeight: 40
    }
}

5. Don't customize native styles — Windows and macOS native styles ignore QSS. Base all custom styling on cross-platform styles:

Basic

Fusion

Material

, or

Universal

qml

// In main() — must be set before QGuiApplication
QQuickStyle.setStyle("Material")

6. Make all user-visible strings translatable from the start:

qml

Label { text: qsTr("Save File") }
Button { text: qsTr("Cancel") }

1. 类型安全的属性声明 —— 始终使用显式类型，而非

var

qml

// WRONG — prevents static analysis, unclear errors
property var name

// CORRECT
property string name
property int count
property MyModel optionsModel

2. 优先使用声明式绑定而非命令式赋值：

qml

// WRONG — imperative assignment overwrites bindings, breaks Qt Design Studio
Rectangle {
    Component.onCompleted: color = "red"
}

// CORRECT — declarative binding, evaluates once at load
Rectangle {
    color: "red"
}

3. 使用交互信号而非值变更信号：

qml

// WRONG — valueChanged fires on clamping/rounding, causes event cascades
Slider { onValueChanged: model.update(value) }

// CORRECT — moved only fires on user interaction
Slider { onMoved: model.update(value) }

4. 不要对Layout的直接子元素设置锚点：

qml

// WRONG — anchors on direct Layout children cause binding loops
RowLayout {
    Rectangle { anchors.fill: parent }
}

// CORRECT — use Layout attached properties
RowLayout {
    Rectangle {
        Layout.fillWidth: true
        Layout.preferredHeight: 40
    }
}

5. 不要自定义原生样式 —— Windows和macOS的原生样式会忽略QSS。所有自定义样式都应基于跨平台样式：

Basic

、

Fusion

、

Material

或

Universal

qml

// In main() — must be set before QGuiApplication
QQuickStyle.setStyle("Material")

6. 从一开始就让所有用户可见的字符串支持翻译：

qml

Label { text: qsTr("Save File") }
Button { text: qsTr("Cancel") }

Exposing Python Objects to QML

将Python对象暴露给QML

Three methods: Required Properties (preferred), Context Property, Registered QML Type.

Key rule:
@Slot
is mandatory for any Python method callable from QML. Missing it causes

TypeError

at runtime.

Full patterns — see references/qml-pyside6.md

三种方法：Required Properties（推荐）、Context Property、已注册QML类型。

核心规则：任何可从QML调用的Python方法都必须使用
@Slot
装饰器。缺少它会在运行时引发

TypeError

。

完整实现模式 —— 详见references/qml-pyside6.md

QML Signals and Connections

QML信号与连接

Full patterns — see references/qml-signals-properties.md

完整实现模式 —— 详见references/qml-signals-properties.md

Common QtQuick.Controls Components

常用QtQuick.Controls组件

Full component reference — see references/qml-components.md

完整组件参考 —— 详见references/qml-components.md