uni-app x 强力工具库 unix-utils 正式发布

unix-utils 首个版本正式发布！这是一个为 uni-app x 提供便利工具的集合，以 UTS 源码随标准 uni_modules 插件分发（插件市场 + npm 双轨），当前包含 toast 模块——对 uni.showToast 的全端兼容封装，覆盖 Android / iOS / Web / 微信 / 鸿蒙五端。

为什么需要它

uni.showToast 官方各端能力差异长期存在：Android 缺少 position、小程序端 icon 行为不一、duration 精度不可控、部分参数静默失效无法感知。unix-utils 用一套与 uni.showToast 完全同构的 API 抹平这些差异——参数一致，迁移零成本；不支持的参数自动降级并经 fail 回调留痕，降级可感知、可过滤。

核心特性

• 参数完全对齐
  ：title / icon / image / mask / duration / position / success / fail / complete 与 uni.showToast 同构；ToastOptions 除 title 外均为可选字段，icon / position / 错误码为字面量联合类型
• 分端混合通道
  （自动分发，业务零配置）： 
• App-Android / App-iOS：UTS 直挂系统窗口（Android WindowManager / iOS UIWindow 免注册挂窗），position / warning / mask / 精确 duration 全生效，系统窗口级生命周期跨页面存活，挂窗失败自动降级 uni.showToast 原生通道
• Web：DOM 单例自绘，position / warning / 无平台截断全生效
• 微信 / 鸿蒙：uni.showToast 原生通道，不支持的参数自动降级并留痕
• icon 超集
  ：原生 6 值 + 扩展 warning；fail / exception 在原生端归一化为 error，自绘通道真实渲染
• position 三值全支持
  ：top / center / bottom 在自绘通道全生效，位置语义跨端一致（top / bottom 距显示区边缘 10%）
• 双轨 API
  ：回调式 showToast（主）+ Promise 式 showToastAsync（辅）；语义化快捷 showToastSuccess / showToastError / showToastInfo
• hideToast 统一语义
  ：自绘通道可靠隐藏（含原生不支持隐藏的 position 形态）
• 全局默认配置 configureToast
  ：项目级预设 duration / icon / mask，字段传 null 沿用库内置默认
• 结构化失败信息 ToastFail
  ：errCode（1001 参数非法 / 2001 平台不支持）、errSubject、param（触发降级的参数名）、platform（端标识）

快速开始

// uni_modules 方式导入（npm 方式改为 '@meng-xi/unix-utils'）import { showToast } from '@/uni_modules/unix-utils'// 基础用法——与 uni.showToast 参数完全一致showToast({ title: '保存成功', icon: 'success' })// 全端生效的顶部提示（原生 uni.showToast 在 Android 无效）showToast({ title: '网络异常，请重试', icon: 'warning', position: 'top' })// Promise 式 + 语义化快捷import { showToastAsync, showToastError } from '@/uni_modules/unix-utils'await showToastAsync({ title: '已提交' })showToastError('操作失败')

安装方式

• npm
  ：pnpm add @meng-xi/unix-utils，源码以 UTS 分发，Web / 小程序 → JS，Android → Kotlin，iOS → Swift 由编译链现场编译
• uni_modules（推荐）
  ：HBuilderX 插件市场搜索 unix-utils，导入后即得自包含的 uni_modules/unix-utils（utssdk/ 官方目录结构）

文档

从入门到精通的完整文档位于文档站：https://mengxi-studio.github.io/unix-utils/，覆盖快速开始、Toast 提示、通道架构与降级、完整 API 参考。

平台兼容性

• Web / H5、微信小程序、鸿蒙 → 编译为 JS
• App-Android → 编译为 Kotlin
• App-iOS → 编译为 Swift
• 不引入任何第三方 UI 依赖，业务零配置自动分发到对应通道

后续规划

• 更多工具模块持续加入（工具集定位，toast 只是第一个）
• 各模块沿用「全端兼容 + 参数抹平 + 结构化降级」的统一设计范式

欢迎 Star 与反馈：GitHub · 更新日志