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 · 更新日志