---
title: "readText"
description: "从虚拟文件系统读取 UTF-8 文本，大文本返回临时文件句柄。"
---


> 从虚拟文件系统读取 UTF-8 文本，大文本返回临时文件句柄。

## 签名

```ts
KSM.fs.readText(args: {
  path: string;
}): Promise<string | { file: string }>
```

命名导出调用形式相同：`fs.readText({ path })`。

## 平台与权限

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

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `path` | `string` |是 |可读的 `app://` 虚拟路径 |

## 返回值

- 内容不超过 64 KiB 时返回 `string`。
- 内容超过 64 KiB 时返回 `{ file: string }`，`file` 是 `app://tmp/read-<id>.txt`。
- 再次读取该临时句柄时仍返回同一个句柄。

## 行为

- 目标文件必须存在且是普通文件。
- 文件大小上限是 16 MiB；超过上限按不可读取处理。
- `app://res` 和 `app://assets` 只读，但可以通过本方法读取。
- `app://picked/<id>` 必须是文件选择器登记过的 token。
- 内容按 UTF-8 文本读取。

## 示例

```ts
const result = await KSM.fs.readText({
  path: 'app://data/large.txt'
});

if (typeof result === 'string') {
  console.info(result);
} else {
  const handleResult = await KSM.fs.readText({ path: result.file });
  console.assert(
    typeof handleResult === 'object' &&
    handleResult.file === result.file
  );
}
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` |路径未通过前端守卫 |
| `PERMISSION_DENIED` |路径越出沙箱，或权限不可用 |
| `NOT_FOUND` |目标文件不存在 |
| `IO_ERROR` |文件存在但无法读取、超过 16 MiB 或临时句柄写入失败 |
| `NOT_SUPPORTED` |对应文件服务未配置 |
| `TIMEOUT` |宿主未在默认时间内响应 |

## 相关

- [writeText](/docs/kasumi/api/fs/write-text)
- [fs 模块](/docs/kasumi/api/fs)