---
title: "writeText"
description: "向虚拟文件系统写入 UTF-8 文本。"
---


> 向虚拟文件系统写入 UTF-8 文本。

## 签名

```ts
KSM.fs.writeText(args: {
  path: string;
  content: string;
}): Promise<{ written: boolean }>
```

## 平台与权限

| Windows | Android |权限 |
| --- | --- | --- |
|支持 |支持 | `fs.write` |

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `path` | `string` |是 |可写虚拟路径 |
| `content` | `string` |是 |UTF-8 文本，最大 16 MiB |

## 返回值

|字段 |类型 |说明 |
| --- | --- | --- |
| `written` | `boolean` |成功时为 `true` |

当前契约中成功响应固定为 `written: true`，失败会拒绝 Promise。

## 行为

- 只允许写入 `app://data`、`app://cache`、`app://tmp` 和已登记的 `app://picked/<id>`。
- 目标位于 `app://res` 或 `app://assets` 时返回 `PERMISSION_DENIED`。
- 父目录不存在时由宿主创建。
- 写入会截断并覆盖已有文本文件。
- 内容以 UTF-8 写入，单文件上限 16 MiB。

## 示例

```ts
await KSM.fs.writeText({
  path: 'app://data/settings.json',
  content: JSON.stringify({ theme: 'light' }, null, 2)
});
```

写入用户选择的文件时，只能使用选择器返回的句柄：

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

if (picked.file) {
  await KSM.fs.writeText({
    path: picked.file,
    content: '{}'
  });
}
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` |路径或内容类型未通过前端守卫 |
| `PERMISSION_DENIED` |只读根、越权路径或权限不可用 |
| `IO_ERROR` |创建目录、打开文件或写入失败，或内容超过 16 MiB |
| `NOT_SUPPORTED` |对应文件服务未配置 |

## 相关

- [readText](/docs/kasumi/api/fs/read-text)
- [dialog.saveFile](/docs/kasumi/api/dialog/save-file)