1# 即时反馈（Toast）
2
3即时反馈（Toast）是一种临时性的消息提示框，用于向用户显示简短的操作反馈或状态信息。​它通常在屏幕的底部或顶部短暂弹出，随后在一段时间后自动消失。即时反馈的主要目的是提供简洁、不打扰的信息反馈，避免干扰用户当前的操作流程。
4
5
6可以通过使用[UIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext)中的[getPromptAction](../reference/apis-arkui/js-apis-arkui-UIContext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](../reference/apis-arkui/js-apis-arkui-UIContext.md#promptaction)对象，再通过该对象调用[showToast](../reference/apis-arkui/js-apis-arkui-UIContext.md#showtoast)创建并显示文本提示框。
7
8## 使用建议
9
10 - 合理使用弹出场景，而不是频繁的提醒用户。
11
12    可以针对以下常用场景使用即时反馈操作，例如，当用户执行某个操作时及时结果反馈，用来提示用户操作是否成功或失败；或是当应用程序的状态发生变化时提供状态更新等。
13
14 - 注意文本的信息密度，即时反馈展示时间有限，应当避免长文本的出现。
15
16   Toast控件的文本应该清晰可读，字体大小和颜色应该与应用程序的主题相符。除此之外，即时反馈控件本身不应该包含任何可交互的元素，如按钮或链接。
17
18 - 杜绝强制占位和密集弹出的提示。
19
20   即时反馈作为应用内的轻量通知，应当避免内容布局占用界面内的其他元素信息，如遮盖弹出框的展示内容，从而迷惑用户弹出的内容是否属于弹出框。再或者频繁性的弹出信息内容，且每次弹出之间无时间间隔，影响用户的正常使用。也不要在短时间内频繁弹出新的即时反馈替代上一个。即时反馈的单次显示时长不要超过 3 秒钟，避免影响用户正常的行为操作。
21
22 - 遵从系统默认弹出位置。
23
24   即时反馈在系统中默认从界面底部弹出，距离底部有一定的安全间距，作为系统性的应用内提示反馈，请遵守系统默认效果，避免与其他弹出类组件内容重叠。特殊场景下可对内容布局进行规避。
25
26## 即时反馈模式对比
27
28即时反馈提供了两种显示模式，分别为DEFAULT（显示在应用内）、TOP\_MOST（显示在应用之上）。
29
30在TOP_MOST类型的Toast显示前，会创建一个全屏大小的子窗（手机上子窗大小和主窗大小一致），然后在该子窗上计算Toast的布局位置，最后显示在该子窗上。具体和DEFAULT模式Toast的差异如下：
31
32| 差异点| DEFAULT | TOP_MOST |
33| --- | --- | --- |
34| 是否创建子窗	 | 否 | 是 |
35| 层级 | 显示在主窗内，层级和主窗一致，一般比较低 | 显示在子窗中，一般比主窗层级高，比其他弹窗类组件层级高，比软键盘和权限弹窗层级低。 |
36| 是否避让软键盘 | 软键盘抬起时，必定上移软键盘的高度 | 软键盘抬起时，只有toast被遮挡时，才会避让，且避让后toast底部距离软键盘高度为80vp。 |
37| UIExtension内布局 | 以UIExtension为主窗中布局，对齐方式与UIExtension对齐 | 以宿主窗口为主窗中布局，对齐方式与宿主窗口对齐。|
38
39```ts
40import {promptAction} from '@kit.ArkUI';
41@Entry
42@Component
43struct Index {
44  build() {
45    Column({space: 10}) {
46      TextInput()
47      Button() {
48        Text("DEFAULT类型Toast")
49          .fontSize(20)
50          .fontWeight(FontWeight.Bold)
51
52      }
53      .width('100%')
54      .onClick(()=>{
55        promptAction.showToast({
56          message:"ok，我是DEFAULT toast",
57          duration:2000,
58          showMode: promptAction.ToastShowMode.DEFAULT,
59          bottom:80
60        })
61      })
62      Button() {
63        Text("TOPMOST类型Toast")
64          .fontSize(20)
65          .fontWeight(FontWeight.Bold)
66
67      }
68      .width('100%')
69      .onClick(()=>{
70        promptAction.showToast({
71          message:"ok，我是TOP_MOST toast",
72          duration:2000,
73          showMode: promptAction.ToastShowMode.TOP_MOST,
74          bottom:85
75        })
76      })
77    }
78  }
79}
80```
81
82## 创建即时反馈
83
84适用于短时间内提示框自动消失的场景。
85
86```ts
87import { LengthMetrics, PromptAction } from '@kit.ArkUI'
88import { BusinessError } from '@kit.BasicServicesKit'
89
90@Entry
91@Component
92struct toastExample {
93  private uiContext: UIContext = this.getUIContext()
94  private promptAction: PromptAction = this.uiContext.getPromptAction()
95
96  build() {
97    Column() {
98      Button('Show toast').fontSize(20)
99        .onClick(() => {
100          try {
101            this.promptAction.showToast({
102              message: 'Hello World',
103              duration: 2000
104            });
105          } catch (error) {
106            let message = (error as BusinessError).message
107            let code = (error as BusinessError).code
108            console.error(`showToast args error code is ${code}, message is ${message}`);
109          };
110        })
111    }.height('100%').width('100%').justifyContent(FlexAlign.Center)
112  }
113}
114```
115
116![image](figures/UIToast1.gif)
117