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 42@Entry 43@Component 44struct Index { 45 build() { 46 Column({ space: 10 }) { 47 TextInput() 48 Button() { 49 Text("DEFAULT类型Toast") 50 .fontSize(20) 51 .fontWeight(FontWeight.Bold) 52 53 } 54 .width('100%') 55 .onClick(() => { 56 this.getUIContext().getPromptAction().showToast({ 57 message: "ok，我是DEFAULT toast", 58 duration: 2000, 59 showMode: promptAction.ToastShowMode.DEFAULT, 60 bottom: 80 61 }) 62 }) 63 64 Button() { 65 Text("TOPMOST类型Toast") 66 .fontSize(20) 67 .fontWeight(FontWeight.Bold) 68 69 } 70 .width('100%') 71 .onClick(() => { 72 this.getUIContext().getPromptAction().showToast({ 73 message: "ok，我是TOP_MOST toast", 74 duration: 2000, 75 showMode: promptAction.ToastShowMode.TOP_MOST, 76 bottom: 85 77 }) 78 }) 79 } 80 } 81} 82``` 83 84## 创建即时反馈 85 86适用于短时间内提示框自动消失的场景。 87 88```ts 89import { LengthMetrics, PromptAction } from '@kit.ArkUI'; 90import { BusinessError } from '@kit.BasicServicesKit'; 91 92@Entry 93@Component 94struct toastExample { 95 private uiContext: UIContext = this.getUIContext() 96 private promptAction: PromptAction = this.uiContext.getPromptAction() 97 98 build() { 99 Column() { 100 Button('Show toast').fontSize(20) 101 .onClick(() => { 102 try { 103 this.promptAction.showToast({ 104 message: 'Hello World', 105 duration: 2000 106 }); 107 } catch (error) { 108 let message = (error as BusinessError).message 109 let code = (error as BusinessError).code 110 console.error(`showToast args error code is ${code}, message is ${message}`); 111 }; 112 }) 113 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 114 } 115} 116``` 117 118 119 120## 显示关闭即时反馈 121 122适用于提示框提留时间较长，用户操作可以提前关闭提示框的场景。 123 124```ts 125import { LengthMetrics, PromptAction } from '@kit.ArkUI'; 126import { BusinessError } from '@kit.BasicServicesKit'; 127 128@Entry 129@Component 130struct toastExample { 131 @State toastId: number = 0; 132 private uiContext: UIContext = this.getUIContext() 133 private promptAction: PromptAction = this.uiContext.getPromptAction() 134 135 build() { 136 Column() { 137 Button('Open Toast') 138 .type(ButtonType.Capsule) 139 .height(100) 140 .onClick(() => { 141 try { 142 this.promptAction.openToast({ 143 message: 'Toast Massage', 144 duration: 10000, 145 }).then((toastId: number) => { 146 this.toastId = toastId; 147 }); 148 } catch (error) { 149 let message = (error as BusinessError).message; 150 let code = (error as BusinessError).code; 151 console.error(`OpenToast error code is ${code}, message is ${message}`); 152 }; 153 }) 154 Blank().height(50); 155 Button('Close Toast') 156 .height(100) 157 .type(ButtonType.Capsule) 158 .onClick(() => { 159 try { 160 this.promptAction.closeToast(this.toastId); 161 } catch (error) { 162 let message = (error as BusinessError).message; 163 let code = (error as BusinessError).code; 164 console.error(`CloseToast error code is ${code}, message is ${message}`); 165 }; 166 }) 167 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 168 } 169} 170``` 171 172 173 174 175
