辅助 · 21 / 21
Command tools toast · alert · confirm · prompt
五个命令式工具：toast、alert、confirm、prompt、contextMenu。直接在 JS 里 import 调用，Promise 拿返回值，用完即销毁，不需要在模板里预置组件。
toast：即用消息
默认 3s 自动消失，固定在视口左下角并向下堆叠。传对象可以换颜色、改时长；duration: 0 表示不自动关闭，只能点 ✕ 或调用返回的 close()。
LIVE
toast(message | options)示例代码
import toast from "/packages/snackbar/toast.js";
toast("已保存到草稿"); // 默认 3s
toast({ message: "同步完成", color: "success", duration: 4000 });
const t = await toast({ message: "点 ✕ 关闭", duration: 0 });
t.close(); // 手动关闭，幂等
// 返回 { close, el }alert：只有一个确认键
确认返回 true；点遮罩或按 Escape 返回 null。参数支持字符串简写，也可以用对象补标题与按钮文案。
LIVE
await alert()示例代码
import alert from "/packages/dialog/alert.js";
const ok = await alert("操作成功"); // true
await alert({
title: "提示",
message: "密码已重置，请用新密码登录。",
ok: "知道了",
});
// 点遮罩 / Escape → nullconfirm：确认、取消与危险操作
确认返回 true，取消返回 false，点遮罩或按 Escape 返回 null。危险操作把 color 设为 error，主按钮会使用错误色。
LIVE
await confirm()示例代码（错误色）
import confirm from "/packages/dialog/confirm.js";
const ok = await confirm({
title: "确认删除",
message: "删除后不可恢复。",
yes: "删除",
cancel: "取消",
color: "error",
});
if (ok === true) {
// 执行删除
} else if (ok === false) {
// 用户点了取消
} else {
// 点遮罩 / Escape
}prompt：输入并返回结果
确认返回输入值（字符串，可能为空串），取消、遮罩或 Escape 返回 null。输入框会自动聚焦并全选默认值，Enter 提交。
LIVE
await prompt()示例代码
import prompt from "/packages/dialog/prompt.js";
const name = await prompt({
title: "重命名",
message: "输入新的项目名称",
placeholder: "项目名称",
value: "官网改版", // 预填并全选
});
if (name !== null) {
// name 是字符串
}contextMenu：右键菜单
传事件或坐标与 items 数组，菜单挂在 body 上定位并自动翻转避让视口。选中的叶子项 id 即返回值；点空白或按 Escape 返回 null，禁用项不可选。
LIVE
await contextMenu(e, items)在这里点右键：基础菜单
在这里点右键：子菜单 + 分隔线
结果：{{ctxResult}} · 取消返回 null
示例代码（含子菜单）
import contextMenu from "/packages/menu/context-menu.js";
const id = await contextMenu(event, [
{ id: "copy", label: "复制", prefix: "⧉", suffix: "⌘C" },
{ id: "rename", label: "重命名", prefix: "✏" },
{ separator: true },
{
id: "export",
label: "导出为",
children: [
{ id: "pdf", label: "PDF" },
{ id: "md", label: "Markdown" },
],
},
{ id: "delete", label: "删除", disabled: true },
]);
// id → "copy" / "pdf" 等；取消 → null组合成完整流程
命令式工具可以直接串起来：先 confirm 拿决定，再按结果 toast；或 prompt 拿到名称后写回数据。这样不需要在模板里维护对话框的 open 状态。
LIVE
confirm → toast示例代码（confirm → toast）
import confirm from "/packages/dialog/confirm.js";
import toast from "/packages/snackbar/toast.js";
const ok = await confirm({
title: "删除项目",
message: "“官网改版”会被移入回收站。",
yes: "删除",
color: "error",
});
if (ok === true) {
toast({ message: "已删除项目", color: "success" });
} else {
toast("已取消");
}调用签名
| 工具 | 参数 | 返回 | 说明 |
|---|---|---|---|
toast | string / { message, duration, color } | { close, el } | duration 毫秒，0 = 不自动关闭 |
alert | string / { title, message, ok, color } | true / null | 只有确认键 |
confirm | string / { title, message, yes, cancel, color } | true / false / null | 危险操作用 color="error" |
prompt | string / { title, message, placeholder, value, yes, cancel } | string / null | 确认返回输入值 |
contextMenu | (event | { x, y }, items) | item id / null | items 支持 separator / children / disabled |
插槽 / 事件 / 注意
- 工具内部按需注入
<l-m>，无需预引入组件；但 ofa.js 必须已加载。 - 所有对话框自动挂到
document.body，关闭动画结束后自动移除，不要跨会话复用实例。 - 文本都经过转义；需要富文本请直接用
st-dialog标签。 toast多条堆叠在左下角，容器不挡页面交互。contextMenu的source传事件时自动preventDefault；也可传{ x, y }坐标。