即时反馈（Toast）
===========

即时反馈（Toast）是一种临时性的消息提示框，用于向用户显示简短的操作反馈或状态信息。​它通常在屏幕的底部或顶部短暂弹出，随后在一段时间后自动消失。即时反馈的主要目的是提供简洁、不打扰的信息反馈，避免干扰用户当前的操作流程。

可以通过使用[UIContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext)中的[getPromptAction](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext#getpromptaction)方法获取当前UI上下文关联的[PromptAction](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-promptaction)对象，再通过该对象调用[showToast](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-promptaction#showtoast)创建并显示文本提示框。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/87/v3/51dE54q6RnKXwRkRVNJQKg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132304Z&HW-CC-Expire=86400&HW-CC-Sign=F963E08DB94D87B1D2EC1BBBDD71EF0FD8284C099B2AFA3CE93836E8FB12DF31)

为了安全考虑，例如Toast恶意遮挡其他页面，Toast只能显示在当前的UI实例中，应用退出后，不会单独显示在桌面上。

#### 使用建议

*   合理使用弹出场景，避免过度提醒用户。
    
    可以针对以下常用场景使用即时反馈操作，例如，当用户执行某个操作时及时结果反馈，用来提示用户操作是否成功或失败；或是当应用程序的状态发生变化时提供状态更新等。
    
*   注意文本的信息密度，即时反馈展示时间有限，应当避免长文本的出现。
    
    Toast控件的文本应该清晰可读，字体大小和颜色应该与应用程序的主题相符。除此之外，即时反馈控件本身不应该包含任何可交互的元素，如按钮或链接。
    
*   杜绝强制占位和密集弹出的提示。
    
    即时反馈作为应用内的轻量通知，应当避免内容布局占用界面内的其他元素信息，如遮盖弹出框的展示内容，从而迷惑用户弹出的内容是否属于弹出框。再或者频繁性的弹出信息内容，且每次弹出之间无时间间隔，影响用户的正常使用。也不要在短时间内频繁弹出新的即时反馈替代上一个。即时反馈的单次显示时长不要超过 3 秒钟，避免影响用户正常的行为操作。
    
*   遵从系统默认弹出位置。
    
    即时反馈在系统中默认从界面底部弹出，距离底部有一定的安全间距，作为系统性的应用内提示反馈，请遵从系统默认效果，避免与其他弹出类组件内容重叠。特殊场景下可对内容布局进行规避。
    
*   弹框字体最大放大倍数限制。
    
    即时反馈中，字体的最大放大倍数为2。
    

#### 即时反馈模式对比

即时反馈提供了两种显示模式，分别为DEFAULT（显示在应用内）、TOP\_MOST（显示在应用之上）。

在TOP\_MOST类型的Toast显示前，会创建一个全屏大小的子窗（手机上子窗大小和主窗大小一致），然后在该子窗上计算Toast的布局位置，最后显示在该子窗上。具体和DEFAULT模式Toast的差异如下：

| 差异点 | DEFAULT | TOP\_MOST |
| :-- | :-- | :-- |
| 是否创建子窗 | 否 | 是 |
| 层级 | 显示在主窗内，层级和主窗一致，一般比较低 | 显示在子窗中，一般比主窗层级高，比其他弹窗类组件层级高，比软键盘和权限弹窗层级低 |
| 是否避让软键盘 | 软键盘抬起时，必定上移软键盘的高度 | 软键盘抬起时，只有toast被遮挡时，才会避让，且避让后toast底部距离软键盘高度为80vp |
| UIExtension内布局 | 以UIExtension为主窗中布局，对齐方式与UIExtension对齐 | 以宿主窗口为主窗中布局，对齐方式与宿主窗口对齐 |

import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '\[Sample\_dialogproject\]';
const DOMAIN: number = 0xFF00;

@Entry
@Component
export struct DefaultAndTopToastExample {
  build() {
    // ...
      Column({ space: 10 }) {
        TextInput()
        Button('Toast of the DEFAULT type')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .onClick(() => {
          try {
            this.getUIContext().getPromptAction().showToast({
              message: 'ok, I am DEFAULT toast',
              duration: 2000,
              showMode: promptAction.ToastShowMode.DEFAULT,
              bottom: 80
            });
          } catch (error) {
            let message = (error as BusinessError).message;
            let code = (error as BusinessError).code;
            hilog.error(DOMAIN, TAG, '%{public}s', 'showToast args error code is $\\{code}, message is $\\{message}');
          }
        })

        Button('Toast of the TOPMOST type')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .onClick(() => {
          try {
            this.getUIContext().getPromptAction().showToast({
              message: 'ok, I am TOP\_MOST toast',
              duration: 2000,
              showMode: promptAction.ToastShowMode.TOP\_MOST,
              bottom: 85
            });
          }  catch (error) {
            let message = (error as BusinessError).message;
            let code = (error as BusinessError).code;
            hilog.error(DOMAIN, TAG, '%{public}s', 'showToast args error code is $\\{code}, message is $\\{message}');
          }
        })
      }
      // ...
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/23/v3/fO8qFw49SVGqTQVkM0zXLw/zh-cn_image_0000002634008526.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132304Z&HW-CC-Expire=86400&HW-CC-Sign=0392ACD27D1339E56E3FE175810A79500B6D1E7227C6DF79F8F74CAE01E09FD3)

#### 创建即时反馈

适用于短时间内提示框自动消失的场景。

import { PromptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '\[Sample\_dialogproject\]';
const DOMAIN: number = 0xFF00;

@Entry
@Component
export struct CreateToastExample {
  private uiContext: UIContext = this.getUIContext();
  private promptAction: PromptAction = this.uiContext.getPromptAction();
  build() {
    // ...
      Column() {
        Button('Show toast').fontSize(20)
          .onClick(() => {
            try {
              this.promptAction.showToast({
                message: 'Hello World',
                duration: 2000
              });
            } catch (error) {
              let message = (error as BusinessError).message;
              let code = (error as BusinessError).code;
              hilog.error(DOMAIN, TAG, '%{public}s', 'showToast args error code is $\\{code}, message is $\\{message}');
            }
          })
      }.height('100%').width('100%').justifyContent(FlexAlign.Center)
      // ...
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7c/v3/oxbeYgOES36ELn9UIDsX8w/zh-cn_image_0000002664207673.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132304Z&HW-CC-Expire=86400&HW-CC-Sign=211719B00BE7B27F638E0252F42C49516AFB7ECEFC82298159D047FFF47C9277)

#### 显示和关闭即时反馈

适用于提示框停留时间较长，用户操作可以提前关闭提示框的场景。

import { PromptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '\[Sample\_dialogproject\]';
const DOMAIN: number = 0xFF00;

@Entry
@Component
export struct OpenCloseToastExample {
  @State toastId: number = 0;
  private uiContext: UIContext = this.getUIContext();
  private promptAction: PromptAction = this.uiContext.getPromptAction();

  build() {
    // ...
      Column() {
        Button('Open Toast')
          .height(100)
          .type(ButtonType.Capsule)
          .onClick(() => {
            try {
              this.promptAction.openToast({
                message: 'Toast Message',
                duration: 10000,
              }).then((toastId: number) => {
                this.toastId = toastId;
              });
            } catch (error) {
              let message = (error as BusinessError).message;
              let code = (error as BusinessError).code;
              hilog.error(DOMAIN, TAG, '%{public}s', 'OpenToast error code is $\\{code}, message is $\\{message}');
            }
          })
        Blank().height(50);
        Button('Close Toast')
          .height(100)
          .type(ButtonType.Capsule)
          .onClick(() => {
            try {
              this.promptAction.closeToast(this.toastId);
            } catch (error) {
              let message = (error as BusinessError).message;
              let code = (error as BusinessError).code;
              hilog.error(DOMAIN, TAG, '%{public}s', 'CloseToast error code is $\\{code}, message is $\\{message}');
            }
          })
      }.height('100%').width('100%').justifyContent(FlexAlign.Center)
      // ...
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/fd/v3/3_QaNEDtTAqZ9_b5L7x-fQ/zh-cn_image_0000002664327733.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132304Z&HW-CC-Expire=86400&HW-CC-Sign=9630C00C68468D761157F1AD4B606D079F626AE4A68E2853DB228F76472DD8AE)