Shadcn-UI 中 ShadToast 组件在移动端的显示问题解析

问题现象

在使用 Shadcn-UI 的 ShadToast 组件时，开发者发现了一个平台差异性问题：在 Web/Linux 环境下正常显示的关闭图标（closeIcon），在 Android 平台上却无法显示。这是一个典型的跨平台组件适配问题，值得深入分析。

问题本质

经过项目维护者的确认，这个问题并非真正的 bug，而是组件的预期行为。ShadToast 组件默认设计为仅在鼠标悬停时显示关闭图标（showCloseIconOnlyWhenHovered: true），这是为了优化桌面端的用户体验。由于移动设备没有鼠标悬停事件，因此图标默认不会显示。

解决方案

要让关闭图标在移动设备上显示，开发者需要显式设置：

final snackBar = ShadToast(
  showCloseIconOnlyWhenHovered: false,  // 关键设置
  closeIcon: const Icon(Icons.close, color: Colors.white),
  title: Text('Order deleted successfully.'),
  duration: const Duration(seconds: 5),
);

深入分析

1. 关闭图标的交互问题

当开发者手动覆盖 closeIcon 属性时，需要注意这会替换掉组件默认的交互逻辑。原始实现使用了 ShadButton.ghost 包裹图标，并内置了点击隐藏 toast 的功能：

ShadButton.ghost(
  icon: ShadImage.square(
    size: 16,
    widget.closeIconSrc ?? effectiveToastTheme.closeIconSrc ?? LucideIcons.x,
  ),
  onPressed: () => ShadToaster.of(context).hide(),
)

2. 自定义图标的正确方式

如果需要自定义图标但仍需保留交互功能，有两种推荐做法：

方案一：使用 closeIconSrc 而非 closeIcon

ShadToast(
  closeIconSrc: LucideIcons.x,  // 使用内置图标系统
  // ...
)

方案二：完整实现交互逻辑

ShadToast(
  closeIcon: GestureDetector(
    onTap: () => ShadToaster.of(context).hide(),
    child: const Icon(Icons.close),
  ),
  // ...
)

最佳实践建议

1. 跨平台考虑：在开发跨平台应用时，应该测试所有目标平台的组件行为
2. 交互一致性：确保移动端和桌面端有相似的用户体验
3. 使用主题配置：可以通过配置全局 Toast 主题来避免重复设置

MaterialApp(
  theme: ShadTheme.light(
    toastTheme: ShadToastTheme(
      showCloseIconOnlyWhenHovered: false,
    ),
  ),
)

总结

Shadcn-UI 的 ShadToast 组件通过 showCloseIconOnlyWhenHovered 参数提供了灵活的显示控制，开发者需要根据目标平台调整这一设置。同时，在自定义图标时要注意保持完整的交互功能，这体现了 Flutter 组件设计中组合优于继承的理念。理解这些设计原则有助于开发者更好地使用和扩展 Shadcn-UI 组件库。