名称	类型	只读	可选	说明
wordBreak	WordBreak	否	是	设置分词类型。默认值：WordBreak.BREAK_ALL

名称	类型	只读	可选	说明
value	ResourceStr	否	否	按钮的文本内容。
fontColor	ResourceColor	否	是	按钮文字颜色。默认值：跟随系统主题。
backgroundColor	ResourceColor	否	是	按钮背景色。默认值：跟随系统主题。
enabled	boolean	否	是	点击按钮时是否响应。值为true表示响应，值为false表示不响应。默认值：true
primary	boolean	否	是	定义按钮是否默认响应回车/空格键。值为true表示默认响应，值为false表示不默认响应。默认值：false
style	DialogButtonStyle	否	是	按钮的样式。默认值：DialogButtonStyle.DEFAULT
action	VoidCallback	否	否	点击按钮时执行的回调。

DialogSheet

弹出框列表配置项，用于ActionSheet样式的弹出框。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
title	ResourceStr	否	否	标题内容。
icon	ResourceStr	否	是	图标内容。默认值：空
action	VoidCallback	否	否	单击选项时执行的回调。

名称

类型

只读

可选

说明

title

ResourceStr

否

标题内容。

icon

ResourceStr

否

是

图标内容。

默认值：空

action

VoidCallback

否

单击选项时执行的回调。

DialogBaseOptions

所有弹出框共享的基本选项，定义弹出框的背景、边框、对齐、蒙层、避让等通用属性。DialogStyleOptions与DialogCustomOptions均继承自本接口。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
controller	DialogBaseController	否	是	Dialog控制器。
width	Dimension	否	是	弹出框的宽度。默认值：根据内容自适应。
height	Dimension	否	是	弹出框的高度。默认值：根据内容自适应。
backgroundColor	ResourceColor	否	是	弹出框的背景颜色。默认值：Color.Transparent 说明：当backgroundColor设置为非透明色时，backgroundBlurStyle必须设置为BlurStyle.NONE。
backgroundBlurStyle	BlurStyle	否	是	弹出框的背景模糊样式。默认值：BlurStyle.COMPONENT_ULTRA_THICK 说明：设置为BlurStyle.NONE即可关闭背景模糊。当设置了backgroundBlurStyle为非NONE值时，则不要设置backgroundColor，否则颜色显示将不符合预期效果。当设置系统材质systemMaterial时，backgroundBlurStyle不生效。
backgroundBlurStyleOptions	BackgroundBlurStyleOptions	否	是	带选项的背景模糊样式。默认值与BackgroundBlurStyleOptions类型说明中的默认值一致。
backgroundEffect	BackgroundEffectOptions	否	是	带选项的背景效果。默认值与BackgroundEffectOptions类型说明中的默认值一致。
borderRadius	Dimension \| BorderRadiuses \| LocalizedBorderRadiuses	否	是	背景的边框圆角半径。默认值：{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }
borderWidth	Dimension \| EdgeWidths \| LocalizedEdgeWidths	否	是	弹出框边框宽度。默认值：0
borderColor	ResourceColor \| EdgeColors \| LocalizedEdgeColors	否	是	弹出框的边框颜色。默认值：Color.Black
borderStyle	BorderStyle \| EdgeStyles	否	是	弹出框边框样式。默认值：BorderStyle.Solid
shadow	ShadowOptions \| ShadowStyle	否	是	弹出框的阴影。当设备为PC/2in1时，默认场景下获焦阴影值为ShadowStyle.OUTER_FLOATING_MD，失焦为ShadowStyle.OUTER_FLOATING_SM。其他设备默认无阴影。
alignment	DialogBaseAlignment	否	是	弹出框的对齐模式。默认值：DialogBaseAlignment.DEFAULT
offset	Offset	否	是	弹出框相对于对齐位置的偏移。默认值：{ dx: 0, dy: 0 }
maskRect	Rectangle	否	是	弹出框的蒙层区域。默认值：{ x: 0, y: 0, width: '100%', height: '100%' }
maskColor	ResourceColor	否	是	弹出框的蒙层颜色。默认值：跟随系统主题的默认蒙层颜色。
isModal	boolean	否	是	弹出框是否为模态。值为true表示为模态且有蒙层，值为false表示为非模态且无蒙层。默认值：true
showInSubWindow	boolean	否	是	是否在子窗口中显示。值为true表示在子窗口中显示，值为false表示在应用内显示。默认值：false 说明： isModal为true和showInSubWindow为true不能同时使用。
displayModeInSubWindow	DialogDisplayMode	否	是	定义在子窗口中显示时的弹出框显示模式。默认值：DialogDisplayMode.SCREEN_BASED
autoCancel	boolean	否	是	是否允许通过触摸蒙层或按返回键退出。值为true表示允许退出，值为false表示不允许退出。默认值：true
focusable	boolean	否	是	弹出框是否可以获得焦点。值为true表示可以获得焦点，值为false表示不可以获得焦点。默认值：true
dialogTransition	TransitionEffect	否	是	用于打开/关闭弹出框内容区域的弹出框过渡动效参数。默认值：系统默认过渡动效。
maskTransition	TransitionEffect	否	是	用于打开/关闭遮罩的蒙层过渡动效参数。默认值：系统默认蒙层过渡动效。
keyboardAvoidMode	KeyboardAvoidMode	否	是	键盘避让模式。默认值：KeyboardAvoidMode.DEFAULT
keyboardAvoidDistance	LengthMetrics	否	是	弹出框与系统键盘之间的距离。默认值：系统默认避让距离。
onWillAppear	VoidCallback	否	是	弹出框打开动画开始前的回调函数。
onDidAppear	VoidCallback	否	是	弹出框出现时的回调函数。
onWillDisappear	VoidCallback	否	是	弹出框关闭动画开始前的回调函数。
onDidDisappear	VoidCallback	否	是	弹出框消失时的回调函数。
onWillDismiss	Callback<DialogDismissal>	否	是	弹出框交互关闭的回调。说明：如果注册了此回调，则用户点击蒙层或返回按钮后弹出框不会立即关闭，回调中的reason参数用于判断是否可以关闭弹出框。
enableHoverMode	boolean	否	是	是否启用悬停模式。值为true表示启用，值为false表示不启用。默认值：false
hoverModeArea	HoverModeAreaType	否	是	悬停模式下弹出框的显示区域。默认值：HoverModeAreaType.BOTTOM_SCREEN
levelMode	LevelMode	否	是	弹出框的显示级别。默认值：LevelMode.OVERLAY
levelUniqueId	number	否	是	页面级弹出框显示层下节点的唯一标识。取值范围：大于等于0的整数。说明：该参数仅在levelMode为LevelMode.EMBEDDED时生效。
immersiveMode	ImmersiveMode	否	是	页面级弹出框蒙层效果。默认值：ImmersiveMode.DEFAULT 说明：该参数仅在levelMode为LevelMode.EMBEDDED时生效。
levelOrder	LevelOrder	否	是	弹出框的显示顺序。默认值：LevelOrder.clamp(0)返回的值。
systemMaterial	SystemUiMaterial	否	是	为弹出框设置系统材质，不同的材质有不同的效果，会影响背景色、边框、阴影和弹出框的其他视觉属性。说明： - 默认值：ImmersiveOptions的style为ImmersiveStyle.ULTRA_THICK的ImmersiveMaterial对象。设置undefined时与默认值保持一致。 - 该参数影响背景色backgroundColor、背景模糊backgroundBlurStyle、背景效果backgroundEffect、边框颜色borderColor、边框宽度borderWidth、阴影shadow，当设置系统材质时，上述属性不生效。

DialogMessage

弹出框的消息内容与文字样式，继承自DialogTextStyleOptions。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
content	ResourceStr	否	否	弹出框消息内容。

DialogStyleOptions

固定样式弹出框的选项，继承自DialogBaseOptions。具体用法可参考DialogPresenter的present接口示例。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
title	ResourceStr	否	是	弹出框标题。默认值：未设置时不显示标题。
subtitle	ResourceStr	否	是	弹出框的副标题。默认值：未设置时不显示副标题。
message	DialogMessage	否	是	弹出框的消息内容和文字样式。默认值：未设置时不显示消息内容。
buttons	Array<DialogButton>	否	是	弹出框中的按钮数组。提供时，弹出框显示为带有按钮的警报样式弹出框；与sheets一起使用时，按钮显示在工作表项列表下方。默认值：未设置时不显示按钮。
buttonDirection	DialogButtonOrientation	否	是	按钮的排列方式。默认值：DialogButtonOrientation.AUTO
sheets	Array<DialogSheet>	否	是	action-sheet样式的工作表项数组。提供时，弹出框将显示供用户选择的工作表项。默认值：未设置时不显示工作表项。
gridCount	number	否	是	弹出框中工作表项的网格列数，用于控制工作表项在网格中的分栏显示布局。默认值：4 取值范围：大于0的整数。

DialogCustomOptions

自定义样式弹出框的选项，继承自DialogBaseOptions。

弹出框的内容由DialogPresenter.present方法的第一个参数提供，不在此选项对象中。具体用法可参考DialogPresenter的present接口示例。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
customStyle	boolean	否	是	是否开启自定义样式。值为true表示开启自定义样式，值为false表示不开启。默认值：false

名称

类型

只读

可选

说明

customStyle

boolean

否

是

是否开启自定义样式。值为true表示开启自定义样式，值为false表示不开启。

默认值：false

DialogBaseController

用于控制弹出框的类，可通过DialogBaseOptions中的controller属性与弹出框绑定。具体用法可参考DialogPresenter的present接口示例。

[h2]constructor

constructor()

控制器的构造函数。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

[h2]close

close(): void

关闭相应的弹出框。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

[h2]getState

getState(): DialogState

获取弹出框的状态。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型	说明
DialogState	返回弹出框状态。

示例：

该示例通过DialogBaseController与弹出框绑定，展示了弹出弹出框，并通过控制器关闭以及获取弹出框状态的功能。

import { DialogBaseController, DialogPresenter, DialogState } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private ctx: UIContext = this.getUIContext();
  private dialogPresenter: DialogPresenter = this.ctx.getDialogPresenter();
  private controller: DialogBaseController = new DialogBaseController();
  @State dialogState: DialogState = DialogState.UNINITIALIZED;

  @Builder
  customDialogComponent() {
    Column() {
      Text('Dialog').fontSize(20)
      Column({ space: 10 }) {
        Button('Close dialog via controller').onClick(() => {
          try {
            this.controller.close();
          } catch (error) {
            let message = (error as BusinessError).message;
            let code = (error as BusinessError).code;
            console.error(`Failed to close dialog. Code: ${code}, message: ${message}`);
          }
        })
        Button('Get dialog state')
          .onClick(() => {
            this.dialogState = this.controller.getState();
            console.info('dialog state: ' + this.dialogState);
          })
      }
    }.height(150).padding(20).justifyContent(FlexAlign.SpaceBetween)
  }

  build() {
    Column({ space: 50 }) {
      Text(`Dialog state: ${this.dialogState}`)
      Button('Present dialog')
        .onClick(() => {
          this.dialogPresenter.present(() => { this.customDialogComponent() },
          {
            controller: this.controller,
          })
            .catch((error: BusinessError) => {
              console.error(`Failed to present dialog. Code: ${error.code}, message: ${error.message}`);
            })
        })
      Button('Get dialog state')
        .onClick(() => {
          this.dialogState = this.controller.getState();
          console.info('dialog state: ' + this.dialogState);
        })
    }.width('100%').height('100%').justifyContent(FlexAlign.Start)
  }
}

DialogResult

对话的响应结果。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
dialogId	number	否	否	弹出框的ID。取值范围：大于等于0的整数。

名称

类型

只读

可选

说明

dialogId

number

否

弹出框的ID。

取值范围：大于等于0的整数。

DialogDismissal

提供关闭弹出框操作的信息与关闭接口。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
dismiss	VoidCallback	否	否	关闭弹出框的回调。只有当需要退出弹出框时，才会调用此接口。
reason	DismissReason	否	否	触发弹出框关闭操作的原因类型。

DialogBaseAlignment

弹出框的对齐方式。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
TOP	0	垂直顶部对齐。
CENTER	1	垂直居中对齐。
BOTTOM	2	垂直底部对齐。
DEFAULT	3	默认对齐方式。
TOP_START	4	左上角对齐。
TOP_END	5	右上角对齐。
CENTER_START	6	左居中对齐。
CENTER_END	7	右居中对齐。
BOTTOM_START	8	左下角对齐。
BOTTOM_END	9	右下角对齐。

DialogButtonOrientation

弹出框中按钮的排列方式。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
AUTO	0	两个或两个以下的按钮水平排列，两个以上的按钮垂直排列。
HORIZONTAL	1	按钮水平排列。
VERTICAL	2	按钮垂直排列。

DialogState

Dialog状态的枚举。

起始版本： 26.0.1

元服务API： 从API版本26.0.1开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
UNINITIALIZED	0	表示未初始化。
INITIALIZED	1	表示已初始化。
APPEARING	2	表示正在出现。
APPEARED	3	表示已出现。
DISAPPEARING	4	表示正在消失。
DISAPPEARED	5	表示已消失。

目录

@ohos.arkui.dialog (弹出框)

导入模块

DialogTextStyleOptions

DialogButton

DialogSheet

DialogBaseOptions

DialogMessage

DialogStyleOptions

DialogCustomOptions

DialogBaseController

[h2]constructor

[h2]close

[h2]getState

DialogResult

DialogDismissal

DialogBaseAlignment

DialogButtonOrientation

DialogState