鸿蒙5.0开发进阶：ArkTS组件-弹出框 (Dialog)

原创 于 2025-02-13 15:21:36 发布 · 930 阅读 · 30 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #华为 #android #前端 #ArkUI #ArkTS #鸿蒙系统

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

弹出框 (Dialog)

弹出框是一种模态窗口，通常用于在保持当前的上下文环境时，临时展示用户需关注的信息或待处理的操作，用户在模态弹出框内完成上述交互任务。模态弹出框需要用户进行交互才能够退出模态模式。

说明

该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

导入模块

import { TipsDialog, SelectDialog, ConfirmDialog, AlertDialog, LoadingDialog, CustomContentDialog } from '@kit.ArkUI'

子组件

无

属性

不支持通用属性

TipsDialog

TipsDialog({controller: CustomDialogController, imageRes: Resource, imageSize?: SizeOptions, title?: ResourceStr, content?: ResourceStr, checkTips?: ResourceStr, ischecked?: boolean, checkAction?: (isChecked: boolean) => void, primaryButton?: ButtonOptions, secondaryButton?: ButtonOptions})

提示弹出框，即为带图形确认框，必要时可通过图形化方式展现确认框。

装饰器类型：@CustomDialog

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

参数：

名称参数类型必填装饰器类型说明
controllerCustomDialogController否-

提示弹出框控制器。

说明： 未使用@Require装饰，构造时不强制校验参数。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

imageResResourceStr12+ | PixelMap12+是-

展示的图片。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

imageSizeSizeOptions否-

自定义图片尺寸。

默认值：64*64vp

元服务API： 从API version 11开始，该接口支持在元服务中使用。

titleResourceStr否-

提示弹出框标题。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

contentResourceStr否-

提示弹出框内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

checkTipsResourceStr否-

checkbox的提示内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

isCheckedboolean否@Prop

value为true时，表示checkbox已选中，value为false时，表示未选中。

默认值：false

元服务API： 从API version 11开始，该接口支持在元服务中使用。

checkAction12+(isChecked: boolean) => void否-

现推荐使用 onCheckedChange12+。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

onCheckedChange12+Callback<boolean>否-

checkbox的选中状态改变事件。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

primaryButtonButtonOptions否-

提示框左侧按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

secondaryButtonButtonOptions否-

提示框右侧按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

theme12+Theme | CustomTheme否-

主题信息，可以是CustomTheme或从onWillApplyTheme中获取的Theme实例。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

themeColorMode12+ThemeColorMode否-

自定义弹窗深浅色模式。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

SelectDialog

SelectDialog({controller: CustomDialogController, title: ResourceStr, content?: ResourceStr, selectedIndex?: number, confirm?: ButtonOptions, radioContent: Array<SheetInfo>})

选择类弹出框，弹框中以列表或网格的形式提供可选的内容。

装饰器类型：@CustomDialog

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

参数：

名称参数类型必填说明
controllerCustomDialogController否

选择弹出框控制器。

说明： 未使用@Require装饰，构造时不强制校验参数。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

titleResourceStr是

选择弹出框标题。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

contentResourceStr否

选择弹出框内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

selectedIndexnumber否

选择弹出框的选中项。

默认值：-1

元服务API： 从API version 11开始，该接口支持在元服务中使用。

confirmButtonOptions否

选择弹出框底部按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

radioContentArray<SheetInfo>是

选择弹出框的子项内容列表，每个选择项支持设置文本和选中的回调事件。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

theme12+Theme | CustomTheme否

主题信息，可以是CustomTheme或从onWillApplyTheme中获取的Theme实例。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

themeColorMode12+ThemeColorMode否

自定义弹窗深浅色模式。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

ConfirmDialog

ConfirmDialog({controller: CustomDialogController, title: ResourceStr, content?: ResourceStr, checkTips?: ResourceStr, ischecked?: boolean, primaryButton?: ButtonOptions, secondaryButton?: ButtonOptions})

信息确认类弹出框，操作未正确执行（如网络错误、电池电量过低），或未正确操作时（如指纹录入），反馈的错误或提示信息。

装饰器类型：@CustomDialog

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

参数：

名称参数类型必填装饰器类型说明
controllerCustomDialogController否-

确认弹出框控制器。

说明： 未使用@Require装饰，构造时不强制校验参数。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

titleResourceStr是-

确认弹出框标题。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

contentResourceStr否-

确认弹出框内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

checkTipsResourceStr否-

checkbox的提示内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

isCheckedboolean否@Prop

value为true时，表示checkbox已选中，value为false时，表示未选中。

默认值：false

元服务API： 从API version 11开始，该接口支持在元服务中使用。

onCheckedChange12+Callback<boolean>否-

checkbox的选中状态改变事件。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

primaryButtonButtonOptions否-

确认框左侧按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

secondaryButtonButtonOptions否-

确认框右侧按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

theme12+Theme| CustomTheme否-

主题信息，可以是CustomTheme或从onWillApplyTheme中获取的Theme实例。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

themeColorMode12+ThemeColorMode否-

自定义弹窗深浅色模式。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

AlertDialog

AlertDialog({controller: CustomDialogController, primaryTitle?: ResourceStr, secondaryTitle?: ResourceStr, content: ResourceStr, primaryButton?: ButtonOptions, secondaryButton?: ButtonOptions})

操作确认类弹出框，触发一个将产生严重后果的不可逆操作时，如删除、重置、取消编辑、停止等。

装饰器类型：@CustomDialog

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

参数：

名称参数类型必填说明
controllerCustomDialogController否

确认弹出框控制器。

说明： 未使用@Require装饰，构造时不强制校验参数。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

primaryTitle12+ResourceStr否

确认框一级标题。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

secondaryTitle12+ResourceStr否

确认框二级标题。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

contentResourceStr是

确认弹出框内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

primaryButtonButtonOptions否

确认框左侧按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

secondaryButtonButtonOptions否

确认框右侧按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

theme12+Theme | CustomTheme否

主题信息，可以是CustomTheme或从onWillApplyTheme中获取的Theme实例。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

themeColorMode12+ThemeColorMode否

自定义弹窗深浅色模式。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

LoadingDialog

LoadingDialog({controller: CustomDialogController, content?: ResourceStr})

进度加载类弹出框，操作正在执行时的提示信息。

装饰器类型：@CustomDialog

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

参数：

名称参数类型必填说明
controllerCustomDialogController否

加载弹出框控制器。

说明： 未使用@Require装饰，构造时不强制校验参数。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

contentResourceStr否

加载弹出框内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

theme12+Theme| CustomTheme否

主题信息，可以是CustomTheme或从onWillApplyTheme中获取的Theme实例。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

themeColorMode12+ThemeColorMode否

自定义弹窗深浅色模式。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

CustomContentDialog12+

CustomContentDialog({controller: CustomDialogController, contentBuilder: () => void, primaryTitle?: ResourceStr, secondaryTitle?: ResourceStr, contentAreaPadding?: Padding, buttons?: ButtonOptions[]})

自定义内容区弹出框，同时支持定义操作区按钮样式。

装饰器类型：@CustomDialog

元服务API： 从API version 12开始，该接口支持在元服务中使用。

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

参数：

名称参数类型必填说明
controllerCustomDialogController否

弹出框控制器。

说明： 未使用@Require装饰，构造时不强制校验参数。

contentBuilder() => void是弹出框内容。
primaryTitleResourceStr否弹出框标题。
secondaryTitleResourceStr否弹出框辅助文本。
localizedContentAreaPaddingLocalizedPadding否弹出框内容区内边距。
contentAreaPaddingPadding否弹出框内容区内边距。设置了localizedContentAreaPadding属性时该属性不生效。
buttonsArray<ButtonOptions>否弹出框操作区按钮，最多支持4个按钮。
themeTheme | CustomTheme否主题信息，可以是CustomTheme或从onWillApplyTheme中获取的Theme实例。
themeColorModeThemeColorMode否自定义弹窗深浅色模式。

ButtonOptions

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

名称类型必填说明
valueResourceStr是

按钮的内容。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

action() => void否

按钮的点击事件。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

backgroundResourceColor否

按钮的背景。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

fontColorResourceColor否

按钮的字体颜色。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

buttonStyle12+ButtonStyleMode否

按钮的样式。

默认值：2in1设备为ButtonStyleMode.NORMAL，其他设备为ButtonStyleMode.TEXTUAL。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

role12+ButtonRole否

按钮的角色。

默认值：ButtonRole.NORMAL。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

说明

buttonStyle和role优先级高于fontColor和background。如果buttonStyle和role设置的是默认值，那么fontColor和background可生效。

事件

不支持通用事件

示例

示例1（上图下文弹出框）

上图下文弹出框, 包含imageRes、content等内容。

import { TipsDialog } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct Index {
  @State pixelMap: PixelMap | undefined = undefined;
  isChecked = false;
  dialogControllerImage: CustomDialogController = new CustomDialogController({
    builder: TipsDialog({
      imageRes: $r('sys.media.ohos_ic_public_voice'),
      content: '想要卸载这个APP嘛?',
      primaryButton: {
        value: '取消',
        action: () => {
          console.info('Callback when the first button is clicked')
        },
      },
      secondaryButton: {
        value: '删除',
        role: ButtonRole.ERROR,
        action: () => {
          console.info('Callback when the second button is clicked')
        }
      },
      onCheckedChange: () => {
        console.info('Callback when the checkbox is clicked')
      }
    }),
  })

  build() {
    Row() {
      Stack() {
        Column(){
          Button("上图下文弹出框")
            .width(96)
            .height(40)
            .onClick(() => {
              this.dialogControllerImage.open()
            })
        }.margin({bottom: 300})
      }.align(Alignment.Bottom)
      .width('100%').height('100%')
    }
    .backgroundImageSize({ width: '100%', height: '100%' })
    .height('100%')
  }
  
  aboutToAppear(): void {
    this.getPixmapFromMedia($r('app.media.app_icon'));    
  }
  
  // 获取PixelMap格式的图片资源
  async getPixmapFromMedia(resource: Resource) {
    let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
      bundleName: resource.bundleName,
      moduleName: resource.moduleName,
      id: resource.id
    })
    let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
    this.pixelMap = await imageSource.createPixelMap({
      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
    })
    await imageSource.release()
    return this.pixelMap;
  }
}

示例2（纯列表弹出框）

纯列表弹出框，包含selectedIndex、radioContent等内容。

import { SelectDialog } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  // 设置默认选中radio的index
  radioIndex = 0;
  dialogControllerList: CustomDialogController = new CustomDialogController({
    builder: SelectDialog({
      title: '文本标题',
      selectedIndex: this.radioIndex,
      confirm: {
        value: '取消',
        action: () => {},
      },
      radioContent: [
        {
          title: '文本文本文本文本文本',
          action: () => {
            this.radioIndex = 0
          }
        },
        {
          title: '文本文本文本文本',
          action: () => {
            this.radioIndex = 1
          }
        },
        {
          title: '文本文本文本文本',
          action: () => {
            this.radioIndex = 2
          }
        },
      ]
    }),
  })

  build() {
    Row() {
      Stack() {
        Column() {
          Button("纯列表弹出框")
            .width(96)
            .height(40)
            .onClick(() => {
              this.dialogControllerList.open()
            })
        }.margin({ bottom: 300 })
      }
      .align(Alignment.Bottom)
      .width('100%')
      .height('100%')
    }
    .backgroundImageSize({ width: '100%', height: '100%' })
    .height('100%')
  }
}

示例3（文本与勾选弹出框）

文本与勾选弹出框，包含content、checkTips等内容。

import { ConfirmDialog } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  isChecked = false;
  dialogControllerCheckBox: CustomDialogController = new CustomDialogController({
    builder: ConfirmDialog({
      title: '文本标题',
      content: '文本文本文本文本文本文本文本文本文本文本文本文本文本文本文本文本文本文本文本',
      // 勾选框选中状态
      isChecked: this.isChecked,
      // 勾选框说明文本
      checkTips: '禁止后不再提示',
      primaryButton: {
        value: '禁止',
        action: () => {},
      },
      secondaryButton: {
        value: '允许',
        action: () => {
          this.isChecked = false
          console.info('Callback when the second button is clicked')
        }
      },
      onCheckedChange: () => {
        console.info('Callback when the checkbox is clicked')
      },
    }),
    autoCancel: true,
    alignment: DialogAlignment.Bottom
  })

  build() {
    Row() {
      Stack() {
        Column(){
          Button("文本+勾选弹出框")
            .width(96)
            .height(40)
            .onClick(() => {
              this.dialogControllerCheckBox.open()
            })
        }
        .margin({bottom: 300})
      }
      .align(Alignment.Bottom)
      .width('100%')
      .height('100%')
    }
    .backgroundImageSize({ width: '100%', height: '100%' })
    .height('100%')
  }
}

示例4（纯文本弹出框）

纯文本弹出框，包含primaryTitle、secondaryTitle、content等内容。

import { AlertDialog } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  dialogControllerConfirm: CustomDialogController = new CustomDialogController({
    builder: AlertDialog({
      primaryTitle: '弹框一级标题',
      secondaryTitle: '弹框二级标题',
      content: '文本文本文本文本文本',
      primaryButton: {
        value: '取消',
        action: () => {
        },
      },
      secondaryButton: {
        value: '确认',
        role: ButtonRole.ERROR,
        action: () => {
          console.info('Callback when the second button is clicked')
        }
      },
    }),
  })

  build() {
    Row() {
      Stack() {
        Column() {
          Button("纯文本弹出框")
            .width(96)
            .height(40)
            .onClick(() => {
              this.dialogControllerConfirm.open()
            })
        }
        .margin({ bottom: 300 })
      }
      .align(Alignment.Bottom)
      .width('100%')
      .height('100%')
    }
    .backgroundImageSize({ width: '100%', height: '100%' })
    .height('100%')
  }
}

示例5（进度条弹出框）

进度条弹出框，包含content等内容。

import { LoadingDialog } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  dialogControllerProgress: CustomDialogController = new CustomDialogController({
    builder: LoadingDialog({
      content: '文本文本文本文本文本...',
    }),
  })

  build() {
    Row() {
      Stack() {
        Column() {
          Button("进度条弹出框")
            .width(96)
            .height(40)
            .onClick(() => {
              this.dialogControllerProgress.open()
            })
        }
        .margin({ bottom: 300 })
      }
      .align(Alignment.Bottom)
      .width('100%')
      .height('100%')
    }
    .backgroundImageSize({ width: '100%', height: '100%' })
    .height('100%')
  }
}

示例6（自定义主题风格弹出框）

自定义主题风格弹出框，包含content、theme等内容。

import { CustomColors, CustomTheme, LoadingDialog } from '@kit.ArkUI'

class CustomThemeImpl implements CustomTheme {
  colors?: CustomColors;

  constructor(colors: CustomColors) {
    this.colors = colors;
  }
}

// 自定义内容文字及loading组件主题颜色
class CustomThemeColors implements CustomColors {
  fontPrimary = '#ffd0a300';
  iconSecondary = '#ffd000cd';
}

@Entry
@Component
struct Index {
  @State customTheme: CustomTheme = new CustomThemeImpl(new CustomThemeColors());
  dialogController: CustomDialogController = new CustomDialogController({
    builder: LoadingDialog({
      content: 'text',
      theme: this.customTheme,
    })
  });

  build() {
    Row() {
      Stack() {
        Column() {
          Button('dialog')
            .width(96)
            .height(40)
            .onClick(() => {
              this.dialogController.open();
            })
        }
        .margin({ bottom: 300 })
      }
      .align(Alignment.Bottom)
      .width('100%')
      .height('100%')
    }
    .backgroundImageSize({ width: '100%', height: '100%' })
    .height('100%')
  }
}

示例7（自定义深浅色模式弹出框）

自定义深浅色模式弹出框，包含content、themeColorMode等内容。

import { LoadingDialog } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  dialogController: CustomDialogController = new CustomDialogController({
    builder: LoadingDialog({
      content: 'Text',
      themeColorMode: ThemeColorMode.DARK, //设置弹窗深浅色模式为深色模式
    })
  });

  build() {
    Row() {
      Stack() {
        Column() {
          Button('Dialog')
            .width(96)
            .height(40)
            .onClick(() => {
              this.dialogController.open();
            })
        }
        .margin({ bottom: 300 })
      }
      .align(Alignment.Bottom)
      .width('100%')
      .height('100%')
    }
    .backgroundImageSize({ width: '100%', height: '100%' })
    .height('100%')
  }
}

示例8（自定义内容弹出框）

支持自定义内容弹出框，包含contentBuilder、buttons等内容。

import { CustomContentDialog } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  dialogController: CustomDialogController = new CustomDialogController({
    builder: CustomContentDialog({
      primaryTitle: '标题',
      secondaryTitle: '辅助文本',
      contentBuilder: () => {
        this.buildContent();
      },
      buttons: [
        { 
          value: '按钮1',
          buttonStyle: ButtonStyleMode.TEXTUAL, 
          action: () => {
            console.info('Callback when the button is clicked')
          }
        },
        {
          value: '按钮2',
          buttonStyle: ButtonStyleMode.TEXTUAL,
          role: ButtonRole.ERROR
        }
      ],
    }),
  });

  build() {
    Column() {
      Button("支持自定义内容弹出框")
        .onClick(() => {
          this.dialogController.open()
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
  
  // 自定义弹出框的内容区
  @Builder
  buildContent(): void {
    Column() {
      Text('内容区')
    }
    .width('100%')
  }
}

评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值