---
title: "dialog"
description: "显示系统消息框、确认框，选择文件或保存位置。"
---


> 显示系统消息框、确认框，选择文件或保存位置。

## 模块边界

`dialog` 只负责用户交互和文件选择，不读取、写入或删除文件。选择器返回的
`app://picked/<id>` 句柄应继续交给 [fs](/docs/kasumi/api/fs)使用。

实现入口是 `frontend/src/api/dialog.ts`。

## 方法索引

|方法 |返回 |取消表现 |
| --- | --- | --- |
| [message](/docs/kasumi/api/dialog/message) | `{ confirmed }` |返回 `false` |
| [confirm](/docs/kasumi/api/dialog/confirm) | `{ confirmed }` |返回 `false` |
| [openFile](/docs/kasumi/api/dialog/open-file) | `{ file }` |返回 `{ file: null }` |
| [saveFile](/docs/kasumi/api/dialog/save-file) | `{ file }` |返回 `{ file: null }` |

## 平台差异

|项 | Windows | Android |
| --- | --- | --- |
|实现 | Win32 `MessageBoxW` / `GetOpenFileNameW` / `GetSaveFileNameW` | `AlertDialog` / `ACTION_OPEN_DOCUMENT` / `ACTION_CREATE_DOCUMENT` |
|宿主内部等待上限 |系统对话框决定 |60 秒 |
|前端请求超时 |默认 10 秒 |默认 10 秒 |
| `filters` |过滤表达式 | `EXTRA_MIME_TYPES` |
|用户取消 | `false`或 `{ file: null }` | `false`或 `{ file: null }` |

`filters` 没有跨平台统一的扩展名语义。传入值必须按目标平台的文件选择器规则构造，
需要跨端复用时在业务适配层转换。

Android 宿主内部最多等待 60 秒，但前端总线默认请求超时是 10 秒。用户操作超过
10 秒时，Promise 会先以 `TIMEOUT`拒绝；系统对话框可能仍然存在，宿主会抑制迟到
响应。用户在请求未超时前取消时，通常得到 `false`或 `{ file: null }`。

## 示例

```ts
const confirmed = await KSM.dialog.confirm({
  title: '删除缓存',
  message: '确定删除全部缓存吗？'
});

if (!confirmed.confirmed) {
  return;
}

const picked = await KSM.dialog.openFile();
if (!picked.file) {
  return;
}

const text = await KSM.fs.readText({ path: picked.file });
```

## 边界

- 不向前端返回真实宿主路径或 `content://` URI。
-用户在请求超时前取消文件选择时返回空结果，不抛 `CANCELLED`。
- Android 同一时间只接受一个进行中的打开或保存请求。
- 系统对话框属于阻塞式平台能力。前端请求超时后，宿主可能仍需抑制迟到响应。

## 相关

- [permission.request](/docs/kasumi/api/permission/request)
- [errors](/docs/kasumi/api/errors)