# informat.file 本地文件

## 概述

使用`informat.file`对象进行文件操作,所有的文件都会存储在app沙盒环境

::: info 术语说明

- app沙盒环境：app的运行环境。每个app都是在自己的沙盒中运行的，不能直接访问其他app的资源文件和数据。
- app沙盒中的文件路径：以app目录作为根目录的文件路径，例如，app的沙盒环境的根目录是`/`
  :::

## getFile

获取文件信息

```javascript
informat.file.getFile(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

返回文件信息[File](/guide/script/model.md#file)

**示例**

::: code-group

```javascript [调用]
informat.file.getFile('gzb.xlsx');
```
```json [返回值]
{
  "absolute": true,
  "absolutePath": "/home/appadmin/informat_home/file_storage/localfiles/g09aj7cus3d8s/ey89pc358ousw/gzb.xlsx",
  "canRead": true,
  "canWrite": true,
  "directory": false,
  "file": true,
  "isAbsolute": true,
  "isDirectory": false,
  "isFile": true,
  "lastModified": 1683602289249,
  "length": 10317,
  "name": "gzb.xlsx",
  "path": "/home/appadmin/informat_home/file_storage/localfiles/g09aj7cus3d8s/ey89pc358ousw/gzb.xlsx",
  "totalSpace": 211243687936,
  "usableSpace": 80439672832
}

```

:::

## getRealPath

获取文件完整路径

```javascript
informat.file.getRealPath(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`String`，本地文件完整路径

**示例**

::: code-group

```javascript [调用]
informat.file.getRealPath('gzb.xlsx');
```
```text [返回值]
/home/appadmin/informat_home/file_storage/localfiles/g09aj7cus3d8s/ey89pc358ousw/gzb.xlsx
```
:::

## md5

获取文件MD5

```javascript
informat.file.md5(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`String`，返回本地文件MD5值

**示例**

::: code-group

```javascript [调用]
informat.file.md5('gzb.xlsx');
```
```text [返回值]
eb5958522b1043d715ecf076d5ff3dc9
```
:::

## create

创建文件，在app的沙盒环境中创建文件

```javascript
informat.file.create(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`String`，返回是否创建成功

**示例**

::: code-group

```javascript [调用]
informat.file.create('a.txt');
```
```text [返回值]
true
```
:::

## mkdirs

创建文件夹，在app的沙盒环境中创建文件夹

```javascript
informat.file.mkdirs(path)
```

| 参数   | 类型       | 描述    |
|------|----------|-------|
| path | `String` | 文件夹路径 |

**返回值**

类型`Boolean`，返回是否创建成功

**示例**

::: code-group

```javascript [调用]
informat.file.mkdirs('a/b/c');
```
```text [返回值]
true
```

:::

## delete

删除文件，在app的沙盒环境中删除文件

如果path对应的文件不存在，系统会报`文件不存在`错误；
如果path对应的是一个文件夹，不是文件，系统会报`文件不存在`错误；

```javascript
informat.file.delete(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`Boolean`，返回是否删除成功

**示例**

::: code-group

```javascript [调用]
informat.file.delete('a.txt');
```
```text [返回值]
true
```
:::


## deleteDirectory

删除文件夹，在app的沙盒环境中删除文件文件夹，如果文件夹下面有子文件夹和文件也会一起删除

如果path对应的文件夹不存在，系统会报`文件不存在`错误；
如果path对应的是一个文件，不是文件夹，系统会报`文件不存在`错误；

```javascript
informat.file.deleteDirectory(path)
```

| 参数   | 类型       | 描述    |
|------|----------|-------|
| path | `String` | 文件夹路径 |

**返回值**

类型`Boolean`，返回是否删除成功

**示例**

::: code-group

```javascript [调用]
informat.file.deleteDirectory('a');
```
```text [返回值]
true
```

:::


## exists

判断是否存在文件，在app的沙盒环境中判断是否存在本地文件

```javascript
informat.file.exists(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`Boolean`，返回临时文件是否存在

**示例**

::: code-group

```javascript [调用]
informat.file.exists('a.txt');
```
```text [返回值]
true
```
:::

## isDirectory

判断文件是否是文件夹

```javascript
informat.file.isDirectory(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`Boolean`，返回是否是文件夹

**示例**

::: code-group

```javascript [调用]
informat.file.isDirectory('a.txt');
```
```text [返回值]
false
```
:::


## listFile

返回文件夹下的文件列表

```javascript
informat.file.listFile(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`Array<String>`，返回文件夹下的文件列表

**示例**

::: code-group

```javascript [调用]
informat.file.listFile('');
```
```json [返回值]
[
  "xxxx123.txt",
  "1234444",
  "gzb2.xlsx",
  "a",
  "gzb.xlsx"
]
```
:::

## move

将source文件移动到target

```javascript
informat.file.move(source, target)
```

::: tip
如果目标路径已存在，则会移动到目标路径下一级
:::

| 参数     | 类型       | 描述    |
|--------|----------|-------|
| source | `String` | 源文件路径 |
| target | `String` | 目标路径  |

**返回值**

类型`Boolean`，返回是否成功

**示例**
::: code-group

```javascript [调用]
informat.file.move('a', 'b');
```
```text [返回值]
true
```

:::

## copy

将source文件复制到target

```javascript
informat.file.copy(source, target)
```

| 参数     | 类型       | 描述    |
|--------|----------|-------|
| source | `String` | 源文件路径 |
| target | `String` | 目标路径  |

**返回值**

类型`Boolean`，返回是否成功

**示例**

::: code-group

```javascript [调用]
informat.file.copy('a.txt', 'b.txt');
```
```text [返回值]
true
```

:::

::: warning 注意
源文件不能是文件夹
:::

## zip

压缩文件

```javascript
informat.file.zip(sourcePath, targetPath, charsetName, withSrcDir)
```

| 参数          | 类型        | 描述              |
|-------------|-----------|-----------------|
| sourcePath  | `String`  | 压缩文件的路径         |
| targetPath  | `String`  | 需要压缩的文件目录       |
| charsetName | `String`  | 编码,默认`UTF-8`，可选 |
| withSrcDir  | `Boolean` | 是否包含被打包目录，可选    |

**示例**

```javascript
const result1 = informat.file.exists("文件内容/测试内容.jpg");
const result2 = informat.file.exists("文件内容/测试内容1.txt");
informat.file.zip('文件内容', '压缩路径/归档.zip');
informat.file.zip('文件内容', '压缩路径/归档.zip', 'GB2312', true);
```

**下载附件字段的附件数据，压缩文件夹**

```javascript
/**
 * XXX表附件下载和压缩脚本
 * 功能：下载多条记录的2个附件字段并压缩为zip文件
 */

export function downloadAndZip(recordList) {
    if(recordList.length==0){
        return null;
    }
    const idList = recordList.map(item => item.id);
    const downloadDir=informat.utils.randomUUID();
    const zipPath = downloadDir+`.zip`;
    try {
        console.log("开始执行XXX表附件下载和压缩脚本...");
        
        // 1. 查询空柜/空车拍照表的所有记录
        console.log("正在查询表记录...");
        const records = informat.table.queryList('testTable',{
            pageSize: -1,
            returnOptionName:true,
            filter: {
                opt: "and",
                conditionList: [{ fieldId: "id", opt: "in", value: idList }]
            }
        });
        
        console.log(`查询到 ${records.length} 条记录`);
        
        if (records.length === 0) {
            console.log("没有找到任何记录，脚本执行结束");
            return;
        }
        
        informat.file.mkdirs(downloadDir);
        
        // 2. 处理每条记录
        for (let i = 0; i < records.length; i++) {
            const record = records[i];
            console.log(`\n处理第 ${i + 1} 条记录 (ID: ${record.id})`);
            
            // 定义2个附件字段
            const attachmentFields = [
                { field: "floorPhoto", name: "空车地板拍照" },
                { field: "frontPhoto", name: "前面照" }
            ];
            
            // 创建记录专属文件夹
            const recordFolder = downloadDir+`/${record.plateNumber_name}/`;
            informat.file.mkdirs(recordFolder);
            
            const downloadedFiles = [];
            
            // 3. 下载每个附件字段的文件
            for (const attachmentField of attachmentFields) {
                const attachment = record[attachmentField.field];
                
                if (attachment && attachment.id) {
                    console.log(`  下载 ${attachmentField.name}...`);
                    
                    try {
                        let localPath=`${recordFolder}${attachment.name}`;
                        // 从共享存储下载文件到本地沙盒
                        informat.storage.download(
                            attachment.path,
                            localPath
                        );
                        
                        downloadedFiles.push(localPath);
                        console.log(`    ✓ 下载成功: ${localPath}`);
                    } catch (error) {
                        console.log(`    ✗ 下载失败: ${attachmentField.name} - ${error.message}`);
                    }
                } else {
                    console.log(`  跳过 ${attachmentField.name} - 无附件`);
                }
            }
            
            // 4. 压缩文件
            if (downloadedFiles.length > 0) {
                console.log(`  开始压缩文件...${downloadDir}`);
                try {
                    informat.file.zip(downloadDir,zipPath);
                    console.log(`  ✓ 压缩成功: ${zipPath}`);
                    console.log(`  ✓ 共压缩 ${downloadedFiles.length} 个文件`);
                } catch (error) {
                    console.log(`  ✗ 压缩失败: ${error.message}`);
                }
            } else {
                console.log(`无附件可压缩，跳过该记录`);
            }
        }
        informat.file.deleteDirectory(downloadDir);
        console.log("\n脚本执行完成！");
        
    } catch (error) {
        informat.file.deleteDirectory(downloadDir);
        console.error("脚本执行出错:", error);
        throw error;
    }
    return zipPath;
}

```

## unzip

解压缩文件

```javascript
informat.file.unzip(sourcePath, targetPath, charsetName)
```

| 参数          | 类型       | 描述                      |
|-------------|----------|-------------------------|
| sourcePath  | `String` | 需要解压缩的文件路径              |
| targetPath  | `String` | 解压缩的文件夹路径，如果文件夹不存在会自动创建 |
| charsetName | `String` | 编码，默认`UTF-8` 可选         |

**示例**

```javascript
informat.file.unzip("压缩路径/归档.zip", '解压路径/所有文件');
informat.file.unzip("压缩路径/归档.zip", '解压路径/所有文件', 'GB2312');
```

## readAsBytes

读取文件返回二进制内容

```javascript
informat.file.readAsBytes(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`Array<byte>`，文件读取结果,如果文件不存在返回`null`

**示例**

```javascript
informat.file.readAsBytes('a.txt');
```

## readAsString

读取文件返回字符串内容

```javascript
informat.file.readAsString(path, charset)
```

| 参数      | 类型       | 描述       |
|---------|----------|----------|
| path    | `String` | 文件路径     |
| charset | `String` | 返回内容的字符集 |

**返回值**

类型`String`，文件读取结果,如果文件不存在返回`null`

**示例**
::: code-group

```javascript [调用]
informat.file.readAsString('a.txt', 'utf-8');
```
```text [返回值]
hello informat
```

:::

## readAsBase64String

读取文件二进制内容并按照base64编码返回字符串内容

```javascript
informat.file.readAsBase64String(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`String`，文件读取结果,如果文件不存在返回`null`

**示例**
::: code-group

```javascript [调用]
const file = 'a.txt';
informat.file.writeString(file, 'hello informat', 'utf-8');
informat.file.readAsBase64String(file);
```
```text [返回值]
aGVsbG8gaW5mb3JtYXQ=
```

:::

## readAsBase64Bytes

读取文件二进制内容并按照base64编码返回二进制内容

```javascript
informat.file.readAsBase64Bytes(path)
```

| 参数   | 类型       | 描述   |
|------|----------|------|
| path | `String` | 文件路径 |

**返回值**

类型`Array<byte>`，文件读取结果,如果文件不存在返回`null`

**示例**
::: code-group

```javascript [调用]
const file = 'a.txt';
informat.file.writeString(file, 'hello informat', 'utf-8');
informat.file.readAsBase64Bytes(file);
```

:::

## writeBytes

将二进制内容写入文件

```javascript
informat.file.writeBytes(path, content)
```

| 参数      | 类型            | 描述    |
|---------|---------------|-------|
| path    | `String`      | 文件路径  |
| content | `Array<byte>` | 二进制内容 |

**示例**

```javascript
const readResult = informat.file.readAsBytes('x90.txt');
informat.file.writeBytes('b.txt', readResult);
```

## writeString

将字符串写入文件

```javascript
informat.file.writeString(path, content, charset)
```

| 参数      | 类型       | 描述   |
|---------|----------|------|
| path    | `String` | 文件路径 |
| content | `String` | 内容   |
| charset | `String` | 字符集  |

**示例**

```javascript
informat.file.writeString('c.txt', 'hello informat', 'utf-8');
```
