showToast
接口说明
showToast:options: 用于向用户展示轻量级提示消息 Toast。
Toast 通常用于展示操作结果、状态提示或短文本通知,例如“操作成功”“加载失败”等。调用方可以通过 SUDOPShowToastOptions 配置提示文案、图标、展示时长以及是否显示透明遮罩层。
常量定义
objectivec
static NSString * const kSUDOPShowToastOptionsIconTypeSuccess = @"success";
static NSString * const kSUDOPShowToastOptionsIconTypeFail = @"fail";
static NSString * const kSUDOPShowToastOptionsIconTypeLoading = @"loading";图标类型说明
| 常量 | 值 | 说明 |
|---|---|---|
kSUDOPShowToastOptionsIconTypeSuccess | success | 成功图标。 |
kSUDOPShowToastOptionsIconTypeFail | fail | 失败图标。 |
kSUDOPShowToastOptionsIconTypeLoading | loading | 加载中图标。 |
类型声明
objectivec
/**
Options for configuring toast message display behavior.
*/
@interface SUDOPShowToastOptions : NSObject
/**
The text content of the toast message.
*/
@property(nonatomic, strong) NSString *title;
/**
The icon type or identifier to be displayed alongside the toast message.
*/
@property(nonatomic, strong) NSString *icon;
/**
The local file path of a custom icon.
The priority of `image` is higher than `icon`.
@availability 1.1.0 and above
*/
@property(nonatomic, strong) NSString *image;
/**
The duration (in milliseconds) for which the toast should be displayed.
@default 1500
*/
@property(nonatomic, assign) NSInteger duration;
/**
Whether to show a transparent mask layer to prevent touch-through events.
When set to YES, user interactions behind the toast are blocked.
*/
@property(nonatomic, assign) BOOL mask;
@end方法声明
objectivec
/**
Displays a toast message (brief non-intrusive notification) to the user.
@param stateHandle The state handle object that manages the operation state and callbacks.
@param options The options configuration for the toast (e.g., message text, duration, position).
*/
- (void)showToast:(id<SUDOPStateHandle>)stateHandle
options:(SUDOPShowToastOptions *)options;参数说明
SUDOPShowToastOptions
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
title | NSString * | 是 | - | Toast 展示的文本内容。 |
icon | NSString * | 否 | - | Toast 图标类型或图标标识,可使用内置值:success、fail、loading。 |
image | NSString * | 否 | - | 自定义图标的本地文件路径,image 优先级高于 icon。自 1.1.0 及以上版本可用。 |
duration | NSInteger | 否 | 1500 | Toast 展示时长,单位为毫秒。 |
mask | BOOL | 否 | NO | 是否显示透明遮罩层。设置为 YES 时,Toast 展示期间会阻止用户点击背后的页面内容。 |
方法参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
stateHandle | id<SUDOPStateHandle> | 是 | 状态句柄对象,用于管理当前操作状态及回调。 |
options | SUDOPShowToastOptions * | 是 | Toast 展示配置对象,包含文案、图标、展示时长、遮罩层等配置。 |
使用示例
展示普通 Toast
objectivec
id<SUDOPStateHandle> stateHandle = self.stateHandle;
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"操作成功";
options.duration = 1500;
[self showToast:stateHandle options:options];展示成功 Toast
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"保存成功";
options.icon = kSUDOPShowToastOptionsIconTypeSuccess;
options.duration = 1500;
[self showToast:self.stateHandle options:options];展示失败 Toast
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"提交失败";
options.icon = kSUDOPShowToastOptionsIconTypeFail;
options.duration = 2000;
[self showToast:self.stateHandle options:options];展示加载中 Toast
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"加载中";
options.icon = kSUDOPShowToastOptionsIconTypeLoading;
options.duration = 3000;
options.mask = YES;
[self showToast:self.stateHandle options:options];使用自定义图标
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"已收藏";
options.icon = kSUDOPShowToastOptionsIconTypeSuccess;
options.image = @"/var/mobile/Containers/Data/Application/xxx/icon_star.png";
options.duration = 1500;
[self showToast:self.stateHandle options:options];当同时设置
image和icon时,优先使用image指定的本地图标。
处理流程
- 业务侧创建
SUDOPShowToastOptions对象。 - 设置 Toast 文本内容
title。 - 根据需要设置内置图标类型
icon,例如success、fail、loading。 - 如需使用自定义图标,设置
image为本地图标文件路径。 - 根据需要设置展示时长
duration,单位为毫秒。 - 根据需要设置是否展示透明遮罩层
mask。 - 调用
showToast:options:展示 Toast。 - SDK 在指定时长后自动隐藏 Toast。
注意事项
stateHandle不应为空,否则 SDK 可能无法正确管理当前操作状态或回调。options不应为空。title建议必填;为空时可能导致 Toast 无文本展示,具体表现以 SDK 实现为准。duration单位为毫秒,默认值为1500。image仅支持本地文件路径,自 SDK1.1.0及以上版本可用。image的优先级高于icon,同时设置时会优先展示自定义图片。icon建议使用 SDK 提供的内置常量,避免字符串拼写错误。mask设置为YES时,Toast 展示期间会阻止用户点击背后的页面内容。mask设置为NO时,Toast 背后的页面可能仍可响应用户交互。- 如果短时间内多次调用该方法,SDK 可能会覆盖上一条 Toast,也可能排队展示,具体行为以 SDK 实现为准。
- 该方法无同步返回值,展示结果或异常信息应以 SDK 回调或状态回调为准。
