---
title: "saveFile"
description: "打开系统保存选择器，并返回可写入的虚拟文件句柄。"
---


> 打开系统保存选择器，并返回可写入的虚拟文件句柄。

## 签名

```ts
KSM.dialog.saveFile(args?: {
  suggestedName?: string;
}): Promise<{ file: string | null }>
```

## 平台与权限

| Windows | Android |权限 |
| --- | --- | --- |
|支持 |支持 | `dialog` |

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `suggestedName` | `string` |否 |保存对话框中的建议文件名 |

## 返回值

|字段 |类型 |说明 |
| --- | --- | --- |
| `file` | `string \| null` |成功时是 `app://picked/<id>`，取消时为 `null` |

## 行为

- Windows 使用 `GetSaveFileNameW`，启用覆盖确认。
- Android 使用 `ACTION_CREATE_DOCUMENT`，把建议名放入 `EXTRA_TITLE`。
- 用户取消或选择失败时返回 `{ file: null }`。
- Android 宿主内部等待 60 秒仍未完成时返回 `{ file: null }`；前端总线默认 10 秒
 先以 `TIMEOUT`拒绝。
- 返回句柄登记后才可用于 `fs.writeText()` 或 `fs.remove()`。
- Windows 保存对话框当前只使用 `All Files` 过滤。

## 示例

```ts
const saved = await KSM.dialog.saveFile({
  suggestedName: 'settings.json'
});

if (!saved.file) {
  return;
}

await KSM.fs.writeText({
  path: saved.file,
  content: JSON.stringify({ ready: true })
});
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` | `suggestedName` 不是字符串 |
| `PERMISSION_DENIED` | `dialog` 权限不可用 |
| `NOT_SUPPORTED` |宿主没有配置保存服务 |
| `TIMEOUT` |请求超过桥接层 10 秒超时 |

## 相关

- [openFile](/docs/kasumi/api/dialog/open-file)
- [fs.writeText](/docs/kasumi/api/fs/write-text)