HarmonyOS 6 Popup 气泡弹窗组件使用文档
文章目录
- 概述
- 导入模块
- 核心结构
- 配置类型
- 1. PopupIconOptions 图标配置
- 2. PopupTextOptions 文本配置（标题/正文通用）
- 3. PopupButtonOptions 按钮配置
- 4. Popup 全局常用属性
- 示例代码
- 代码逐段解析
- 1. 外层容器
- 2. 图标配置
- 3. 标题配置
- 4. 正文配置
- 5. 关闭按钮控制
- 6. 底部双按钮
- 总结
概述
Popup 是 HarmonyOS ArkUI 提供高级气泡弹窗组件。
可自定义图标、标题、正文、关闭按钮、底部双按钮，支持样式定制、点击回调、最大宽度设置、布局镜像等能力，常用于提示弹窗、确认弹窗、功能气泡提示等业务场景。
导入模块
使用 Popup 必须先导入对应 ArkUI 类型：
import { Popup, PopupTextOptions, PopupButtonOptions, PopupIconOptions } from '@kit.ArkUI';核心结构
- icon：弹窗顶部图标（PopupIconOptions）
- title：弹窗标题文本（PopupTextOptions）
- message：弹窗内容描述文本（PopupTextOptions）
- showClose / onClose：关闭按钮与关闭回调
- buttons：底部确认/取消双按钮（最多支持两个）
配置类型
1. PopupIconOptions 图标配置
| 属性 | 说明 |
|---|---|
| image | 图标资源，支持本地app.media资源 |
| width / height | 图标宽高尺寸 |
| fillColor | SVG 图标填充色 |
| borderRadius | 图标圆角 |
2. PopupTextOptions 文本配置（标题/正文通用）
| 属性 | 说明 |
|---|---|
| text | 显示文本内容 |
| fontSize | 字体大小 |
| fontColor | 字体颜色 |
| fontWeight | 字体粗细 |
注意：message 文本不支持设置 fontWeight。
3. PopupButtonOptions 按钮配置
| 属性 | 说明 |
|---|---|
| text | 按钮文字 |
| action | 点击回调事件 |
| fontSize | 按钮文字大小 |
| fontColor | 按钮文字颜色 |
4. Popup 全局常用属性
| 属性 | 说明 |
|---|---|
| showClose | 是否显示右上角关闭按钮，示例设为 false 隐藏 |
| onClose | 关闭按钮点击回调 |
| buttons | 底部操作按钮数组，最多 2 个 |
示例代码
// 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', 点击打印取消日志 } ]最多支持两个按钮，分别绑定点击业务回调，适合确认弹窗场景。
总结
- 图标资源
$r('app.media.start')需要开发者自行替换项目内图片资源； - buttons 最多只能传2 个，超出无效；
- message 文本不支持
fontWeight设置； - 该组件不支持穿戴设备，在手机、平板、PC、大屏可正常使用；
- 支持 API 11 及以上，元服务从 API 12 开始支持。
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力