桌面应用 / 系统课时

声明属性并设置默认值

声明属性并设置默认值

QML 组件需要通过属性保存状态,并向外部提供可配置入口。本节学习使用 property 声明不同类型的数据,为组件创建字符串、数字、布尔值、颜色以及对象引用等默认状态。

学习目标

  • 掌握 QML 自定义属性的声明方式。
  • 理解属性默认值和类型约束的作用。
  • 学会使用属性让组件具备可复用配置能力。

使用 property 声明组件状态

QML 对象除了内置属性外,还可以通过 property 创建自定义属性。属性声明后,可以像内置属性一样参与绑定和赋值。

基本语法如下:

qml
property 类型 属性名: 默认值

例如创建一个带状态的提示组件:

qml
import QtQuick

Item {
    width: 300
    height: 100

    property string title: "默认标题"
    property int count: 0
    property bool enabled: true
    property color backgroundColor: "lightgray"

    Rectangle {
        anchors.fill: parent
        color: backgroundColor

        Text {
            anchors.centerIn: parent
            text: title + " " + count
            visible: enabled
        }
    }
}

预期结果

text
组件显示灰色背景区域,默认显示“默认标题 0”。
当修改 title、count 或 enabled 属性时,界面会根据绑定自动更新。

声明不同类型的属性

QML 支持多种常用属性类型,不同类型会影响赋值方式和运行时检查。

类型 示例 用途
string property string name: "Qt" 文本状态
int property int size: 16 整数配置
real property real opacityValue: 0.5 小数配置
bool property bool active: true 开关状态
color property color themeColor: "blue" 颜色配置
var property var data: ({}) 灵活数据对象

明确声明类型可以减少错误。例如颜色属性不应该传入数字,布尔属性也不应该保存字符串。

使用属性引用对象

除了基础类型,属性还可以保存对象引用。这种方式常用于组件之间传递对象。

qml
import QtQuick

Item {
    property Item targetItem: null

    Rectangle {
        id: box
        width: 100
        height: 100
    }

    Component.onCompleted: {
        targetItem = box
    }
}

预期结果

text
组件加载完成后,targetItem 保存 Rectangle 对象引用,可以通过该属性访问目标对象。

对象引用属性需要注意生命周期,避免保存已经销毁对象的引用。

让组件通过属性提供配置入口

自定义属性的主要价值是隐藏内部实现,同时提供稳定接口。

例如一个按钮组件不应该要求使用者修改内部文本对象的 id,而应该提供:

qml
property string labelText: "确认"

外部只需要设置:

qml
MyButton {
    labelText: "提交"
}

组件内部如何展示文字可以自由调整,而调用方只依赖公开属性。

属性默认值的边界

默认值用于组件初始化,但不是固定值。属性绑定、外部赋值和状态变化都可以覆盖它。

设计组件时,应为常用场景提供合理默认值,同时通过属性开放需要变化的部分。过多暴露内部状态会增加组件耦合,使维护成本上升。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

声明属性并设置默认值

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通