客户端 API/网页应用/小程序API/文件/文件系统概述
# 文件系统概述

文件系统是小程序或网页应用内提供的一套文件管理的接口集合。本文主要介绍文件系统包含的文件类型，以及各文件类型的管理逻辑。

## 功能简介

小程序或网页应用的文件系统中，文件主要分为代码包文件和本地文件两大类。

文件类型 | 说明
---|---
代码包文件 | 代码包文件是指在项目目录中添加的文件。
本地文件 | 本地文件由本地调用接口产生，或通过网络下载并存储到本地的文件，其中本地文件分为两种：<br>- 本地临时文件（以 `ttfile://temp` 开头）：临时产生的、在小程序重启时会被清空的文件。<br>- 本地用户文件（以 `ttfile://user` 开头）：小程序调用指定接口，将本地临时文件保存后产生的文件，每个小程序最多可存储 200 MB 大小的本地用户文件。自<br>V7.54版本起，当用户**退出登录所有账号**或**深度清理**的时候本地文件也将被清理

文件系统相关说明：

- 文件系统存放区域，以应用 appId 和用户 userId 维度进行数据隔离。

- 在应用中调用 [tt.getFileSystemManager()](https://open.larksuite.com/document/uYjL24iN/uETOuETOuETO/tt_get_file_system_manager) 可以获取到全局唯一的文件系统管理器，所有文件系统的管理操作，通过 `tt.getFileSystemManager()` 的返回值 `FileSystemManager` 实现。示例代码配置如下：

```js
  var fs = tt.getFileSystemManager()
  ```
## 读写权限

不同文件类型在应用内的读写权限说明如下表所示。

文件类型 | 读权限 | 写权限 
--|--|--
代码包文件 | 有 | 无 
本地临时文件 | 有 | 无
本地用户文件 | 有 | 有

## 代码包文件

基于代码包文件的大小限制，该类文件适用于存储应用首次加载时所需的文件。对于数据较大或需要动态替换的文件，不推荐添加到代码包文件中。

### 访问代码包文件

代码包目录路径所支持的格式包括 `a/b/c`、`/a/b/c`、`./a/b/c`， 且仅支持这三种格式。例如，读取包内 app.js 文件的示例代码配置如下所示。

```js
const fileSystemManager = tt.getFileSystemManager();
fileSystemManager.readFile({
  filePath: "app.js",	// 文件格式，还可以是 "/app.js", "./app.js"
  encoding: "utf8",
  success(res) {
    // app.js 文件内容
    console.log(res.data);
  },
  fail(res) {
    console.error("读取失败", res.errMsg);
  },
});
```

### 修改代码包文件

代码包内的文件无法在应用运行后动态修改或删除。如需修改代码包文件，则需要重新发布应用版本。

## 本地文件

本地文件指的是小程序被用户添加到手机后，存在的一块独立的文件存储区域。本地文件以 `userId + appId` 维度进行数据隔离，即同一台手机内，每个独立的Lark用户不能访问到其他登录用户的文件，同一个用户不同 appId 之间的文件也不能互相访问。 

### 本地临时文件

本地临时文件只在调用特定接口时产生，不能直接写入内容。

- 当本地临时文件产生后，仅在当前生命周期内保证有效，应用重启之后不保证可用。如果你需要保证在下次应用启动时，无需重新下载临时文件，则可以通过 [FileSystemManager.saveFile()](https://open.larksuite.com/document/uYjL24iN/ugDOz4CO4MjL4gzM) 或 [FileSystemManager.copyFile()](https://open.larksuite.com/document/uYjL24iN/uETOuETOuETO/file_system_manager/file_system_manager_copy_file) 接口，把本地临时文件转化成本地用户文件存储。

- 当小程序重启后，本地临时文件会被清除。

- 产生本地临时文件的示例代码逻辑如下所示。

```js
  //Demo1
  tt.chooseImage({
    success (res) {
        const tempFilePaths = res.tempFilePaths // tempFilePaths 的每一项是一个本地临时文件路径
    },
    fail (res) {}
  });

//Demo2
  tt.downloadFile({
      "url": "https://xxx.png",
      success(res) {
        const tempFilePath = res.tempFilePath // tempFilePath 是一个本地临时文件路径
      },
      fail(res) {}
  });
  ```

### 本地用户文件

本地用户文件目录用于保存应用的常规文件数据，应用对该目录有完全自由的读写权限。示例代码逻辑如下：

```js
const fileSystemManager = tt.getFileSystemManager();
const filePath = `ttfile://user/example.txt`;	//本地用户文件
fileSystemManager.writeFile({
  filePath,
  encoding: "utf8",
  data: "example content",
  success(_res) {
    const data = fileSystemManager.readFileSync(filePath);
    console.log("写入的内容为:", data);
  },
  fail(res) {}
});
```
- v7.54 版本开始，本地用户文件在用户**退出登录所有账号**或者进行**深度清理**后将被系统清理；[小程序和网页应用本地用户文件清理策略变更](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/breaking-change/change-in-local-user-file-cleaning-strategy)
- 你可通过 [getFileSystemManager](https://open.larksuite.com/document/uYjL24iN/uETOuETOuETO/tt_get_file_system_manager) 的返回值 `FileSystemManager` 手动清理文件。例如，以下示例代码中，调用 [FileSystemManager.unlink](https://open.larksuite.com/document/uYjL24iN/uETOuETOuETO/file_system_manager/file_system_manager_unlink) 清理文件。

```js
  const fileSystemManager = tt.getFileSystemManager();
  const filePath = `ttfile://user/example.txt`;	//本地用户文件
  fileSystemManager.unlink({
    filePath: filePath,
    success(_res) {
      console.log("unlink success");
    },
    fail(res) {}
  });
  ```