学习笔记（二十九）：ArkUi-@ohos.promptAction (弹窗)

概述：

创建并显示文本提示框、对话框和操作菜单。

注意：

1、本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用

2、该模块不支持在UIAbility的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。

一、导入模块

import { promptAction } from '@kit.ArkUI';

 

二、promptAction.showToast

showToast(options: ShowToastOptions): void

创建并显示文本提示框

1、简单使用：

// @ohos.promptAction (弹窗) 使用示例
import { promptAction } from '@kit.ArkUI';

@Entry
@Component
struct PromptActionExample {
  @State message: string = 'Hello World'

  build() {
    Row() {
      Column() {
        Button('toast')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .onClick(()=>{
            promptAction.showToast({
              message:'提示内容'
            })
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

2、ShowToastOptions，文本提示框的选项

1、message，必填

string | Resource类型，显示的文本信息

说明：默认字体为'Harmony Sans'，不支持设置其他字体。

2、duration，非必填

number类型，显示时长（毫秒）

说明：默认值1500ms，取值区间：1500ms-10000ms。若小于1500ms则取默认值，若大于10000ms则取上限值10000ms。

3、bottom，非必填

string | number类型，设置弹窗底部边框距离导航条的高度

说明：默认值：80vp；ToastShowMode.TOP_MOST模式下，软键盘拉起时，如果bottom值过小，toast要被软键盘遮挡时，会自动避让至距离软键盘80vp处。ToastShowMode.DEFAULT模式下，软键盘拉起时，会上移软键盘的高度。

4、showMode，非必填

ToastShowMode类型，设置弹窗是否显示在应用之上。

说明：默认值：ToastShowMode.DEFAULT，默认显示在应用内。

5、alignment，非必填

Aligment类型，对齐方式。

说明：默认值：undefined，默认底部偏上位置。

6、offset，非必填

Offset类型，在对齐方式上的偏移。

说明：默认值：{dx:0, dy:0}，默认没有偏移。

7、backgroundColor ，非必填

ResourceColor类型，文本提示框背板颜色

说明：默认值：Color.Transparent；当设置了backgroundColor为非透明色时，backgroundBlurStyle需要设置为BlurStyle.NONE，否则颜色显示将不符合预期效果。

8、textColor ，非必填

ResourcseColor类型，文本提示框文本颜色

说明：默认值：Color.Black

9、backgroundBlurStyle，非必填

BlurStyle类型，文本提示框背板模糊材质

说明：

默认值：BlurStyle.COMPONENT_ULTRA_THICK

设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时，则不要设置backgroundColor，否则颜色显示将不符合预期效果。

10、shadow，非必填

ShadowOptions | ShadowStyle 类型，文本提示框背板阴影

说明：默认值：ShadowStyle.OuterDefaultMD

 

三、promptAction.showDialog

不常用，参考文档

 

四、promptAction.showActionMenu

不常用，参考文档

 

五、promptAction.openCustomDialog

打开自定义弹窗。

注意：

1、暂不支持isModal = true与showInSubWindow = true同时使用。

2、弹窗宽度在设备竖屏时默认为 所在窗口宽度 - 左右margin（16vp，设备为2in1时为40vp），最大默认宽度为400vp。

使用示例：

1、定义一个自定义构建函数组件

@Builder
  customDialogComponent() {
    Column() {
      Text('弹窗').fontSize(30)
      Row({ space: 50 }) {
        Button("取消").onClick(() => {
          // 关闭指定id弹窗组件
          promptAction.closeCustomDialog(this.customDialogComponentId)
        })
        Button("确认").onClick(() => {
          promptAction.closeCustomDialog(this.customDialogComponentId)
        })
      }
    }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween)
  }

2、打开弹框

@Entry
@Component
struct PromptActionExample {
  private customDialogComponentId: number = 0

  build() {
    Row() {
      Column() {
        Button('toast')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            promptAction.openCustomDialog({
              builder: () => this.customDialogComponent()
            })
              .then((dialogId: number) => {
                // 设置当前弹窗id
                this.customDialogComponentId = dialogId
              })
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

 

 

// @ohos.promptAction (弹窗) 使用示例
import { promptAction } from '@kit.ArkUI';

@Entry
@Component
struct PromptActionExample {
  private customDialogComponentId: number = 0

  build() {
    Row() {
      Column() {
        Button('toast')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            promptAction.openCustomDialog({
              builder: () => this.customDialogComponent()
            })
              .then((dialogId: number) => {
                // 设置当前弹窗id
                this.customDialogComponentId = dialogId
              })
          })
      }
      .width('100%')
    }
    .height('100%')
  }

  @Builder
  customDialogComponent() {
    Column() {
      Text('弹窗').fontSize(30)
      Row({ space: 50 }) {
        Button("取消").onClick(() => {
          // 关闭指定id弹窗组件
          promptAction.closeCustomDialog(this.customDialogComponentId)
        })
        Button("确认").onClick(() => {
          promptAction.closeCustomDialog(this.customDialogComponentId)
        })
      }
    }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween)
  }
}

 

CustomDialogOptions，自定义弹窗的内容

1、builder，必填

CustomBuilder类型，设置自定义弹窗的内容。

说明：

builder需要赋值为箭头函数，格式如下：() => { this.XXX() }，其中XXX是内部builder名。

如果是全局builder需要在组件内部创建一个builder，在内部builder中调用全局builder。

builder根节点宽高百分比相对弹框容器大小。

builder非根节点宽高百分比相对父节点大小。

2、backgroundColor，非必填

ResourceColor，设置弹窗背板颜色。

说明：

默认值：Color.Transparent

当设置了backgroundColor为非透明色时，backgroundBlurStyle需要设置为BlurStyle.NONE，否则颜色显示将不符合预期效果。

3、cornerRadius，非必填

Dimension|BorderRadiuses类型，设置背板的圆角半径。

说明：

可分别设置4个圆角的半径。

默认值：{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }。

圆角大小受组件尺寸限制，最大值为组件宽或高的一半，若值为负，则按照默认值处理。

百分比参数方式：以父元素弹窗宽和高的百分比来设置弹窗的圆角

4、borderWidth；borderColor；borderStyle

设置弹窗背板的边框宽度，颜色，样式

5、width；height

设置弹窗背板的宽度，高度

说明：

说明：

- 弹窗宽度默认最大值：400vp。

- 百分比参数方式：弹窗参考宽度为所在窗口的宽度，在此基础上调小或调大。

- 弹窗高度默认最大值：0.9 *（窗口高度 - 安全区域）。

- 百分比参数方式：弹窗参考高度为（窗口高度 - 安全区域），在此基础上调小或调大。