Skip to content

showToast ​

接口说明 ​

showToast:options: 用于向用户展示轻量级提示消息 Toast。

Toast 通常用于展示操作结果、状态提示或短文本通知,例如“操作成功”“加载失败”等。调用方可以通过 SUDOPShowToastOptions 配置提示文案、图标、展示时长以及是否显示透明遮罩层。

常量定义 ​

objectivec
static NSString * const kSUDOPShowToastOptionsIconTypeSuccess = @"success";
static NSString * const kSUDOPShowToastOptionsIconTypeFail = @"fail";
static NSString * const kSUDOPShowToastOptionsIconTypeLoading = @"loading";

图标类型说明 ​

常量值说明
kSUDOPShowToastOptionsIconTypeSuccesssuccess成功图标。
kSUDOPShowToastOptionsIconTypeFailfail失败图标。
kSUDOPShowToastOptionsIconTypeLoadingloading加载中图标。

类型声明 ​

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 ​

参数类型是否必填默认值说明
titleNSString *是-Toast 展示的文本内容。
iconNSString *否-Toast 图标类型或图标标识,可使用内置值:success、fail、loading。
imageNSString *否-自定义图标的本地文件路径,image 优先级高于 icon。自 1.1.0 及以上版本可用。
durationNSInteger否1500Toast 展示时长,单位为毫秒。
maskBOOL否NO是否显示透明遮罩层。设置为 YES 时,Toast 展示期间会阻止用户点击背后的页面内容。

方法参数 ​

参数类型是否必填说明
stateHandleid<SUDOPStateHandle>是状态句柄对象,用于管理当前操作状态及回调。
optionsSUDOPShowToastOptions *是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 指定的本地图标。

处理流程 ​

  1. 业务侧创建 SUDOPShowToastOptions 对象。
  2. 设置 Toast 文本内容 title。
  3. 根据需要设置内置图标类型 icon,例如 success、fail、loading。
  4. 如需使用自定义图标,设置 image 为本地图标文件路径。
  5. 根据需要设置展示时长 duration,单位为毫秒。
  6. 根据需要设置是否展示透明遮罩层 mask。
  7. 调用 showToast:options: 展示 Toast。
  8. SDK 在指定时长后自动隐藏 Toast。

注意事项 ​

  • stateHandle 不应为空,否则 SDK 可能无法正确管理当前操作状态或回调。
  • options 不应为空。
  • title 建议必填;为空时可能导致 Toast 无文本展示,具体表现以 SDK 实现为准。
  • duration 单位为毫秒,默认值为 1500。
  • image 仅支持本地文件路径,自 SDK 1.1.0 及以上版本可用。
  • image 的优先级高于 icon,同时设置时会优先展示自定义图片。
  • icon 建议使用 SDK 提供的内置常量,避免字符串拼写错误。
  • mask 设置为 YES 时,Toast 展示期间会阻止用户点击背后的页面内容。
  • mask 设置为 NO 时,Toast 背后的页面可能仍可响应用户交互。
  • 如果短时间内多次调用该方法,SDK 可能会覆盖上一条 Toast,也可能排队展示,具体行为以 SDK 实现为准。
  • 该方法无同步返回值,展示结果或异常信息应以 SDK 回调或状态回调为准。