Back to Qt.io
Contact Us Blog Download Qt

Dialog QML Type

带有标准按钮和标题的弹出式对话框，用于与用户进行短期交互。更多

Import Statement: import QtQuick.Controls
Inherits:

Popup

属性

信号

方法

  • void accept()
  • void done(int result) (since QtQuick.Controls 2.3 (Qt 5.10))
  • void reject()
  • AbstractButton standardButton(StandardButton button) (since QtQuick.Controls 2.3 (Qt 5.10))

详细说明

对话框是一种弹出式窗口，主要用于短期任务和与用户的简短交流。与ApplicationWindow 和Page 类似，对话框也分为三个部分：header、contentItem 和footer 。

padding 属性只影响 contentItem。使用spacing 属性可影响页眉、contentItem 和页脚之间的空间。

默认情况下，对话框有focus 。

对话框标题和按钮

对话框的title 由特定样式的标题栏显示，默认情况下标题栏被分配为对话框header 。

对话框的标准按钮由DialogButtonBox 管理，默认情况下该按钮被指定为对话框footer 。对话框的standardButtons 属性被转发到按钮框的相应属性。此外，按钮框的accepted() 和rejected() 信号与对话框中的相应信号相连。

Dialog {
    id: dialog
    title: "Title"
    standardButtons: Dialog.Ok | Dialog.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}

modal 对话框会阻止对对话框下方其他内容的输入。打开模式对话框后，用户必须完成与对话框的交互并关闭对话框，然后才能访问同一窗口中的其他内容。

Dialog {
    id: dialog
    modal: true
    standardButtons: Dialog.Ok
}

无模式对话框

无模式对话框是一种独立于对话框周围其他内容运行的对话框。打开无模式对话框时，允许用户与对话框和同一窗口中的其他内容进行交互。

Dialog {
    id: dialog
    modal: false
    standardButtons: Dialog.Ok
}

另请参阅 DialogButtonBox 和弹出控件。

属性文档

该属性用于保存对话框页脚项。页脚项位于底部，并根据对话框的宽度调整大小。默认值为null 。

注： 将DialogButtonBox 指定为对话框页脚会自动将其accepted() 和rejected() 信号连接到对话框中的相应信号。

注： 将DialogButtonBox 、ToolBar 或TabBar 指定为对话框页脚会自动将相应的DialogButtonBox::position 、ToolBar::position 或TabBar::position 属性设置为Footer 。

另请参阅 header 。


header : Item

该属性包含对话框页眉项。页眉项位于顶部，并根据对话框的宽度调整大小。默认值为null 。

注： 将DialogButtonBox 指定为对话框页眉会自动将其accepted() 和rejected() 信号连接到对话框中的相应信号。

注： 将DialogButtonBox 、ToolBar 或TabBar 指定为对话框页眉会自动将相应的DialogButtonBox::position 、ToolBar::position 或TabBar::position 属性设置为Header 。

另请参阅 footer 。


implicitFooterHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

该属性包含隐式页脚高度。

其值等于footer && footer.visible ? footer.implicitHeight : 0 。

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

另请参阅 implicitFooterWidth 和implicitHeaderHeight 。


implicitFooterWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

该属性保存隐式页脚宽度。

其值等于footer && footer.visible ? footer.implicitWidth : 0 。

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

另请参阅 implicitFooterHeight 和implicitHeaderWidth 。


implicitHeaderHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

该属性保存隐式页眉高度。

其值等于header && header.visible ? header.implicitHeight : 0 。

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

另请参阅 implicitHeaderWidth 和implicitFooterHeight 。


implicitHeaderWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

该属性用于保存隐式标题宽度。

其值等于header && header.visible ? header.implicitWidth : 0 。

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

另请参阅 implicitHeaderHeight 和implicitFooterWidth 。


result : int [since QtQuick.Controls 2.3 (Qt 5.10)]

该属性用于保存结果代码。

标准结果代码：

常量说明
Dialog.Accepted对话已被接受。
Dialog.Rejected对话框被拒绝。

此属性在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

另请参阅 accept(),reject() 和done() 。


standardButtons : enumeration

该属性包含对话框使用的标准按钮组合。

Dialog {
    id: dialog
    title: "Title"
    standardButtons: Dialog.Ok | Dialog.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}

这些按钮将按照用户平台的适当顺序定位。

可能的标志：

常量说明
Dialog.Ok通过AcceptRole 定义的 "确定 "按钮。
Dialog.Open通过AcceptRole 定义的 "打开 "按钮。
Dialog.Save通过AcceptRole 定义的 "保存 "按钮。
Dialog.Cancel通过RejectRole 定义的 "取消 "按钮。
Dialog.Close通过RejectRole 定义的 "关闭 "按钮。
Dialog.Discard通过DestructiveRole 定义的 "丢弃 "或 "不保存 "按钮（取决于平台）。
Dialog.Apply通过ApplyRole 定义的 "应用 "按钮。
Dialog.Reset通过ResetRole 定义的 "重置 "按钮。
Dialog.RestoreDefaults通过ResetRole 定义的 "恢复默认值 "按钮。
Dialog.Help通过HelpRole 定义的 "帮助 "按钮。
Dialog.SaveAll通过AcceptRole 定义的 "全部保存 "按钮。
Dialog.Yes通过YesRole 定义的 "是 "按钮。
Dialog.YesToAll通过YesRole 定义的 "是全部 "按钮。
Dialog.No通过NoRole 定义的 "否 "按钮。
Dialog.NoToAll通过NoRole 定义的 "否全部 "按钮。
Dialog.Abort通过RejectRole 定义的 "放弃 "按钮。
Dialog.Retry通过AcceptRole 定义的 "重试 "按钮。
Dialog.Ignore通过AcceptRole 定义的 "忽略 "按钮。
Dialog.NoButton无效按钮。

另请参阅 DialogButtonBox 。


title : string

该属性包含对话框标题。

标题显示在对话框标题中。

Dialog {
    title: qsTr("About")

    Label {
        text: "Lorem ipsum..."
    }
}

信号文档

accepted()

当以交互方式或通过调用accept() 接受对话框时，将发出此信号。

注： 使用close() 关闭对话框或将visible 设置为false 时不会发出此信号。

注： 相应的处理程序是onAccepted 。

另请参阅 rejected()。


[since QtQuick.Controls 2.3 (Qt 5.10)] applied()

点击Dialog.Apply 标准按钮时发出该信号。

注： 相应的处理程序是onApplied 。

该信号在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

另请参阅 discarded() 和reset() 。


[since QtQuick.Controls 2.3 (Qt 5.10)] discarded()

点击Dialog.Discard 标准按钮时发出该信号。

注： 相应的处理程序是onDiscarded 。

该信号在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

另请参阅 reset() 和applied() 。


[since QtQuick.Controls 2.3 (Qt 5.10)] helpRequested()

点击Dialog.Help 标准按钮时发出该信号。

注： 相应的处理程序是onHelpRequested 。

该信号在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

另请参阅 accepted() 和rejected() 。


rejected()

当以交互方式或调用reject() 拒绝对话框时，将发出该信号。

注： 使用close() 关闭对话框或将visible 设置为false 时，不会发出此信号。

注： 相应的处理程序是onRejected 。

另请参阅 accepted()。


[since QtQuick.Controls 2.3 (Qt 5.10)] reset()

点击Dialog.Reset 标准按钮时发出该信号。

注： 相应的处理程序是onReset 。

该信号在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

另请参阅 discarded() 和applied() 。


方法文档

void accept()

发出accepted() 信号并关闭对话框。

另请参阅 reject() 和done()。


[since QtQuick.Controls 2.3 (Qt 5.10)] void done(int result)

  1. 设置result 。
  2. 根据结果是Dialog.Accepted 还是Dialog.Rejected ，分别输出accepted() 或rejected() 。
  3. 发射closed() 。

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

另请参阅 accept(),reject() 和result 。


void reject()

发出rejected() 信号并关闭对话框。

另请参阅 accept() 和done() 。


[since QtQuick.Controls 2.3 (Qt 5.10)] AbstractButton standardButton(StandardButton button)

返回指定的标准button ，如果不存在则返回null 。

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

另请参阅 standardButtons 。


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