当前位置：首页 > news >正文

HarmonyOS 6 ActionSheet 自定义背景效果使用文档

news 2026/6/5 14:47:15

文章目录

- 完整代码
- 核心参数详解
- - 1. 基础文本配置
  - 2. 弹窗位置
  - 3. 背景效果（API19+）
  - 4. 选项列表 sheets
- 总结

完整代码

@Entry @Component struct ActionSheetExample { build() { Stack({ alignContent: Alignment.Top }) { Image($r('app.media.bg')) Column() { Button("ActionSheet") .margin(20) .onClick(() => { this.getUIContext().showActionSheet({ title: 'ActionSheet Title', subtitle: 'ActionSheet Subtitle', message: 'ActionSheet Text', sheets: [ { title: 'Apples', action: () => { console.info('apples'); } }, { title: 'Bananas', action: () => { console.info('bananas'); } }, { title: 'Pears', action: () => { console.info('pears'); } } ], alignment: DialogAlignment.Center, backgroundColor: undefined, backgroundBlurStyle: BlurStyle.Thin, backgroundEffect: { radius: 60, saturation: 0, brightness: 1, color: Color.White, blurOptions: { grayscale: [20, 20] } }, }); }) }.width('100%') } } }

运行效果如图：

核心参数详解

1. 基础文本配置

参数	类型	说明
title	string	弹窗主标题
subtitle	string	弹窗副标题（API10+）
message	string	弹窗内容描述

2. 弹窗位置

参数	取值	说明
alignment	DialogAlignment.Center	弹窗在屏幕居中显示（默认 Bottom）

3. 背景效果（API19+）

参数	作用
backgroundColor: undefined	不设置纯色背景，让模糊效果生效
backgroundBlurStyle: BlurStyle.Thin	轻度系统模糊
backgroundEffect	自定义背景效果（半径、饱和度、亮度、颜色、灰度）
radius: 60	模糊半径
saturation: 0	去色（黑白效果）
brightness: 1	亮度正常
color: Color.White	磨砂底色
blurOptions: { grayscale: [20,20] }	灰度强度

4. 选项列表 sheets

必传数组，每一项为一个操作选项
包含title（文本）和action（点击回调）
支持添加icon字段设置选项图标

总结

调用方式
从 API18 开始，ActionSheet.show()已废弃，必须使用getUIContext().showActionSheet()。
backgroundEffect 要求
仅支持API 19+，低版本运行会报错。
背景设置规则
开启backgroundBlurStyle时，建议将backgroundColor设为undefined，避免颜色冲突。
生命周期
ActionSheet 跟随 UIContext 生命周期，页面销毁时自动回收，无需手动关闭。
遮罩与关闭
默认点击遮罩层自动关闭；可通过autoCancel: false禁止。