HarmonyOS 6 Popup 气泡弹窗组件使用文档

概述

Popup 是 HarmonyOS ArkUI 提供高级气泡弹窗组件。
可自定义图标、标题、正文、关闭按钮、底部双按钮，支持样式定制、点击回调、最大宽度设置、布局镜像等能力，常用于提示弹窗、确认弹窗、功能气泡提示等业务场景。

导入模块

使用 Popup 必须先导入对应 ArkUI 类型：

import { Popup, PopupTextOptions, PopupButtonOptions, PopupIconOptions } from '@kit.ArkUI';

核心结构

1. icon：弹窗顶部图标（PopupIconOptions）
2. title：弹窗标题文本（PopupTextOptions）
3. message：弹窗内容描述文本（PopupTextOptions）
4. showClose / onClose：关闭按钮与关闭回调
5. buttons：底部确认/取消双按钮（最多支持两个）

配置类型

1. PopupIconOptions 图标配置

2. PopupTextOptions 文本配置（标题/正文通用）

注意：message 文本不支持设置 fontWeight。

3. PopupButtonOptions 按钮配置

4. Popup 全局常用属性

示例代码

// xxx.ets import { Popup, PopupTextOptions, PopupButtonOptions, PopupIconOptions } from '@kit.ArkUI'; @Entry @Component struct PopupExample { build() { Row() { // 气泡弹窗组件 Popup({ // 顶部图标配置 icon: { image: $r('app.media.start'), width: 32, height: 32, fillColor: Color.White, borderRadius: 16 } as PopupIconOptions, // 弹窗标题 title: { text: 'This is a popup with PopupOptions', fontSize: 20, fontColor: Color.Black, fontWeight: FontWeight.Normal } as PopupTextOptions, // 弹窗正文内容 message: { text: 'This is the message', fontSize: 15, fontColor: Color.Black } as PopupTextOptions, // 隐藏关闭按钮 showClose: false, // 关闭按钮回调（隐藏仍可配置） onClose: () => { console.info('close Button click'); }, // 底部双按钮：确认 + 取消 buttons: [{ text: 'confirm', action: () => { console.info('confirm button click'); }, fontSize: 15, fontColor: Color.Black, }, { text: 'cancel', action: () => { console.info('cancel button click'); }, fontSize: 15, fontColor: Color.Black },] as [PopupButtonOptions?, PopupButtonOptions?] }) } .width(300) .height(200) .borderWidth(2) .justifyContent(FlexAlign.Center) } }

运行效果如图：

代码逐段解析

1. 外层容器

Row() .width(300) .height(200) .borderWidth(2) .justifyContent(FlexAlign.Center)

外层 Row 设置固定宽高、边框、居中，作为弹窗承载容器。

2. 图标配置

icon: { image: $r('app.media.start'), width: 32, height: 32, fillColor: Color.White, borderRadius: 16 } as PopupIconOptions

• 引用本地图标资源
• 固定 32×32 尺寸
• 设置白色填充、16px 圆角圆形图标

3. 标题配置

title: { text: 'This is a popup with PopupOptions', fontSize: 20, fontColor: Color.Black, fontWeight: FontWeight.Normal } as PopupTextOptions

自定义标题文字、字号、颜色、常规字重。

4. 正文配置

message: { text: 'This is the message', fontSize: 15, fontColor: Color.Black } as PopupTextOptions

设置弹窗描述文案，字号小于标题，层级区分明显。

5. 关闭按钮控制

showClose: false, onClose: () => { console.info('close Button click'); }

showClose: false隐藏右上角关闭按钮；
仍可保留 onClose 回调，后续改为 true 即可直接复用。

6. 底部双按钮

buttons: [ { text: 'confirm', 点击打印确认日志 }, { text: 'cancel', 点击打印取消日志 } ]

最多支持两个按钮，分别绑定点击业务回调，适合确认弹窗场景。

总结

1. 图标资源$r('app.media.start')需要开发者自行替换项目内图片资源；
2. buttons 最多只能传2 个，超出无效；
3. message 文本不支持fontWeight设置；
4. 该组件不支持穿戴设备，在手机、平板、PC、大屏可正常使用；
5. 支持 API 11 及以上，元服务从 API 12 开始支持。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力