@mzzsfy/dsh-toast

@mzzsfy/dsh-toast

DSH 全局浮出通知 Toast 库:多条并存栈式展示,自动消失与常驻确认两种生命周期。供各插件发送全局操作反馈与事件通知,替代各插件自写通知 UI。

本包是普通 npm 依赖,不是 dsh 插件:不声明 dsh.bundle.patch,不自带 cordis.patch.yml,无需也不应 dsh plugin add,且不进 profile 表层 manifest 依赖行(插件市场已装列表因此不显示本包)。安装与装载链:消费插件 dependencies 声明本包 → pnpm(hoisted 布局)作为传递依赖实体安装到顶层 node_modules,dsh 启动 fallback 沿 bundles 依赖闭包补链兜底;开发态由 dev-link 的 junction 指向仓库工作副本保热更。消费插件在自身 cordis.patch.yml 中代挂本包宿主占位条目使 client 进入客户端模块表。机制推导与实证见 MECHANISM.md。

消费方接入

1. package.json:

{
  "dependencies": { "@mzzsfy/dsh-toast": "^0.2.0" },
  "dsh": {
    "client": {
      "external": ["@mzzsfy/dsh-toast/client"]
    }
  }
}

2. cordis.patch.yml(insert 列表追加一条,使本包 client 进入模块表;id 必须带消费插件前缀,name 才是包解析键)。占位条目全仓唯一:全仓只允许一个插件代挂本包占位(当前为 session-manager)——client-modules 按 npm 名做多源检查,两个占位条目装载基不同即 fatal 拖垮整树;其余消费插件不代挂占位,改为可选消费:

// 模块表缺失(权威消费方未安装)时干净降级,不代挂占位
let toast = null
try { toast = require('@mzzsfy/dsh-toast/client').show } catch {}
// 调用点:toast?.(...)

3. client.js 的 factory 内:

const { show: toast } = require('@mzzsfy/dsh-toast/client')

toast('已保存', { kind: 'ok' })                    // 成功反馈,自动消失
toast('保存失败:' + reason, { kind: 'error', sticky: true }) // 常驻待确认
toast('回合完成', { holdMs: 6 * 1000 })            // 自定义展示期

API

• show(text, opts) → id:入栈一条通知。opts.kind 为 'info' | 'ok' | 'error'(非法归 info,默认深色 / 成功绿 / 错误红);opts.sticky 真值常驻不自动消失,渲染「知道了」按钮;opts.holdMs 有限正值自定义展示期(默认 4 秒,非有限值或超出 setTimeout 钳位上界回落默认);opts.onClick 函数使整卡可点(带 pointer 样式),点击即触发回调并消失,「知道了」按钮显式关闭不连带触发。text 非字符串或纯空白时忽略并返回 null
• dismiss(id):移除指定条目并撤销其自动消失计时,幂等
• mount():显式挂载渲染容器(一般无需调用,首次 show 惰性自举)
• __test:非公开 API,仅供本包测试驱动 store 消费,无兼容承诺,消费方禁用

行为规格(BDD)

• Given 库已加载,When show(text),Then 通知顶部居中显示,默认 4 秒后自动消失
• Given 栈内已有 4 条,When 再入栈一条,Then 最旧条目立即移除(含 sticky,新通知优先),被裁条目的自动消失计时同步撤销
• Given show(text, {sticky: true}),Then 通知常驻,点「知道了」或 dismiss(id) 后消失
• Given kind: 'error',Then 红色变体渲染
• Given show(text, {onClick}),Then 整卡可点,点击即消失并触发 onClick;Given 该条目另有 sticky,点「知道了」仅关闭不触发 onClick
• Given 首次 show,Then 渲染容器与样式惰性挂载(容器直挂 body,不受设置页全屏层 z-index 遮挡)
• Given HMR 重载产生同 id 旧容器,When 新代首次挂载,Then 旧容器移除、新容器就位;旧代闭包再调 show/mount 时发现在位容器属更新代际即退避,不拆新代容器
• Given 容器在场而样式节点被外部移除,When 再次 show,Then 样式补挂(容器与样式同级自愈)
• Given 用户系统开启减弱动态效果,Then 入场动画禁用

实现说明

• 位置顶部居中:不遮挡聊天输入区;容器直挂 body,层级高于设置全屏层(z-index 1100 为对宿主层级的显式假设,宿主层级调整时回归核对)
• 样式全部取宿主 --dsw-* 令牌且带就近 fallback(宿主升级更名令牌时降级为可用默认形态,不静默失效);样式挂宿主文档级、幂等且内容变化原位替换,容器在场时随每次挂载自愈
• store 位于模块闭包单例;渲染容器惰性自举、幂等、自愈(旧 root 卸载后重建),容器带代际标记防 HMR 两代互拆;不依赖宿主生命周期
• react / react-dom/client 由宿主平台模块表提供,peerDependencies 声明 react 与 react-dom

dsh 版本兼容

公共依赖包,由消费方(dsh-cron-board 等)代挂装载,三版本装载层均正常,无独立激活单元。