@okutils/toasts

框架无关的加载与消息提示库，用于加载状态和简短反馈。

安装

pnpm add @okutils/toasts

快速使用

建议在浏览器应用中共享一个实例，由应用统一管理生命周期：

// toasts.ts
import { OKToasts } from '@okutils/toasts';

export const sharedToastsInstance = new OKToasts();

import { sharedToastsInstance } from './toasts';

const loadingHandle = sharedToastsInstance.showLoading({ text: '正在保存' });

const successHandle = sharedToastsInstance.showToast({
  text: '保存成功',
  type: 'success',
});

sharedToastsInstance.hide(loadingHandle);
sharedToastsInstance.hide(successHandle);

加载提示不会自动关闭；消息提示默认会自动关闭，也可以通过 duration: 0 持续展示。

API

import { OKToasts } from '@okutils/toasts';
import type {
  OKToastsOptions,
  ShowLoadingOptions,
  ShowToastOptions,
  ToastHandle,
} from '@okutils/toasts';

new OKToasts(options?: OKToastsOptions);

方法	说明
showLoading(options?)	展示加载提示，返回句柄，需要主动关闭
showToast(options?)	展示消息提示，返回句柄，可按 duration 自动关闭
hide(handle)	关闭指定句柄对应的提示
hideAll()	关闭当前实例的提示
destroy()	销毁实例并释放资源

同一个实例内，新提示会替换旧提示。旧句柄传给 hide() 是安全的，不会关闭后续新提示。

配置

实例配置会作为默认值，单次调用传入的选项会覆盖实例配置。

字段	默认值	说明
width	"160px"	提示宽度，支持 px、rem、vh、vw
height	"120px"	提示高度，支持 px、rem、vh、vw
fontSize	"14px"	文字字号，支持 px、rem
theme	"dark"	支持 "light"、"dark"
duration	3000	消息自动关闭时间，单位毫秒；0 表示不自动关闭
text	加载为 "Wait ..."，消息为空	展示文本
type	"note"	消息类型

消息类型支持：

'success' | 'warning' | 'error' | 'note';

示例：

const toasts = new OKToasts({
  theme: 'light',
  duration: 2000,
});

toasts.showLoading({
  text: '上传中',
  width: '180px',
});

toasts.showToast({
  text: '上传完成',
  type: 'success',
});

使用建议

业务组件应只关闭自己持有的句柄。hideAll() 和 destroy() 更适合由实例所有者调用，避免影响其他业务的提示。

可以创建多个独立实例，但它们彼此不会协调展示状态；通常一个应用共享一个实例更简单。

运行环境

包入口和构造函数可在服务端安全使用，但展示提示需要浏览器 DOM 环境。

在 React、Vue、Solid 或其他框架中，请在客户端挂载后、事件回调中或其他浏览器生命周期内调用展示方法。

本地开发

pnpm install
pnpm run typecheck
pnpm run build
pnpm fmt
pnpm run format:check

构建使用 tsdown，格式化使用 oxfmt。