plugins
Dialog
查看 MarkdownKasumi 对话框插件的方法、权限、安全边界与平台差异。
理解 Dialog 插件的系统消息框、确认框、文件选择和保存边界。
Dialog 插件只显示原生用户交互并返回选择结果。它不读取、写入或删除文件，也不向前端暴露 真实宿主路径。文件选择结果必须继续交给 Filesystem 插件处理。
| 层级 | 入口 | 责任 |
|---|---|---|
| 前端 API | frontend/src/api/dialog.ts | 参数守卫和命令封装 |
| 协议清单 | protocol/plugins.json | dialog 插件和四个命令归属 |
| Windows 插件 | windows/src/plugins/ksm_dialog_plugin.cpp | Win32 消息框和文件选择器 |
| Android 插件 | KSMDialogPlugin.kt | AlertDialog 与文档选择 Intent |
| 命令 | Windows | Android | 权限 | 返回 |
|---|---|---|---|---|
dialog.message | 支持 | 支持 | dialog | { confirmed } |
dialog.confirm | 支持 | 支持 | dialog | { confirmed } |
dialog.openFile | 支持 | 支持 | dialog | { file } |
dialog.saveFile | 支持 | 支持 | dialog | { file } |
文件选择结果为空时返回 { file: null }，不是 CANCELLED。消息框或确认框取消时返回
{ confirmed: false }。
| 方法 | 参数 | 说明 |
|---|---|---|
message({ title, message }) | 两个非空字符串 | 显示单按钮消息 |
confirm({ title, message }) | 两个非空字符串 | 显示确认与取消选择 |
openFile({ filters? }) | 平台相关过滤数组 | 返回 picked 文件句柄 |
saveFile({ suggestedName? }) | 建议文件名 | 返回 picked 保存句柄 |
Windows filters 使用文件对话框过滤表达式；Android 把过滤项传给
Intent.EXTRA_MIME_TYPES。两端没有统一的扩展名语义，跨平台业务必须在应用层转换。
content:// URI。BUSY。TIMEOUT 拒绝；宿主抑制迟到结果。const confirmation = await KSM.dialog.confirm({
title: '删除缓存',
message: '确定删除全部缓存吗？'
});
if (!confirmation.confirmed) {
return;
}
const picked = await KSM.dialog.openFile({
filters: ['text/plain']
});
if (!picked.file) {
return;
}
const text = await KSM.fs.readText({ path: picked.file });
console.info(text);需要更长等待时间时，显式传入不超过 600000 毫秒的超时：
await KSM.invoke(
'dialog.openFile',
{ filters: ['application/json'] },
60000
);Windows 使用 MessageBoxW、GetOpenFileNameW 和 GetSaveFileNameW；Android 使用
AlertDialog、ACTION_OPEN_DOCUMENT 和 ACTION_CREATE_DOCUMENT。Android 的系统文档
选择器可能由其他应用提供，返回结果只通过 picked token 暴露。
| 错误码 | 场景 |
|---|---|
INVALID_ARGS | 标题、正文、过滤项或建议文件名非法 |
PERMISSION_DENIED | 未授予 dialog 或当前窗口不允许文件选择 |
BUSY | 已有打开或保存请求进行中 |
NOT_SUPPORTED | 宿主未注册原生对话框服务 |
TIMEOUT / CANCELLED | 请求超时或窗口销毁 |
capabilities.commands 包含目标对话框命令。dialog 权限。filters 使用 MIME 类型，Windows 使用文件过滤表达式。
评论