fs(文件模块)

fs

访问文件系统

当 tauri.conf.json 中的 build.withGlobalTauri 设置为 true 时，也可以通过 window.__TAURI__.fs 访问此软件包。

API 必须添加到 tauri.conf.json 中的 tauri.allowlist.fs 中：


{
  "tauri": {
    "allowlist": {
      "fs": {
        "all": true, // 启用所有 FS APIs
        "readFile": true,
        "writeFile": true,
        "readDir": true,
        "copyFile": true,
        "createDir": true,
        "removeDir": true,
        "removeFile": true,
        "renameFile": true,
        "exists": true
      }
    }
  }
}

建议只允许列出您使用的 API，以优化程序包的大小和安全性。

安全

该模块禁止路径遍历，不允许使用绝对路径或父目录组件（例如，不允许使用"/usr/path/to/file "或".../path/to/file "路径）。使用此 API 访问的路径必须是相对于某个基本目录的路径，因此如果需要访问任意文件系统路径，必须在核心层编写此类逻辑。

API 有一个作用域配置，可强制限制使用 glob 模式访问的路径。

作用域配置是一个 glob 模式数组，描述了允许访问的文件夹路径。例如，该范围配置只允许访问 $APPDATA目录下databases文件夹中的文件：


{
  "tauri": {
    "allowlist": {
      "fs": {
        "scope": ["$APPDATA/databases/*"]
      }
    }
  }
}

请注意 $APPDATA 变量的使用。该值在运行时注入，解析到应用程序数据目录。可用的变量有:
$APPCONFIG, $APPDATA, $APPLOCALDATA,
$APPCACHE, $APPLOG,
$AUDIO, $CACHE, $CONFIG, $DATA,
$LOCALDATA, $DESKTOP, $DOCUMENT,
$DOWNLOAD, $EXE, $FONT, $HOME,
$PICTURE, $PUBLIC, $RUNTIME,
$TEMPLATE, $VIDEO, $RESOURCE, $APP,
$LOG, $TEMP.

尝试使用未在作用域中配置的 URL 执行任何 API,都会因为访问被拒绝而导致 Promise 被拒绝。

请注意，此范围适用于本模块上的所有 API。

参考

`Dir`

重命名并重新导出BaseDirectory

`writeFile`

重命名并重新导出writeTextFile

枚举

`BaseDirectory`

自1.0.0版本起

枚举成员

名称	类型	定义于
`App`	`18`	fs.ts:98
`AppCache`	`24`	fs.ts:104
`AppConfig`	`21`	fs.ts:101
`AppData`	`22`	fs.ts:102
`AppLocalData`	`23`	fs.ts:103
`AppLog`	`25`	fs.ts:105
`Audio`	`1`	fs.ts:81
`Cache`	`2`	fs.ts:82
`Config`	`3`	fs.ts:83
`Data`	`4`	fs.ts:84
`Desktop`	`6`	fs.ts:86
`Document`	`7`	fs.ts:87
`Download`	`8`	fs.ts:88
`Executable`	`9`	fs.ts:89
`Font`	`10`	fs.ts:90
`Home`	`11`	fs.ts:91
`LocalData`	`5`	fs.ts:85
`Log`	`19`	fs.ts:99
`Picture`	`12`	fs.ts:92
`Public`	`13`	fs.ts:93
`Resource`	`17`	fs.ts:97
`Runtime`	`14`	fs.ts:94
`Temp`	`20`	fs.ts:100
`Template`	`15`	fs.ts:95
`Video`	`16`	fs.ts:96

接口

`FileEntry`

自1.0.0版本起

属性

`children`

Optional children: FileEntry[]

如果是目录，则是该条目的子目录；否则为null

定义在: fs.ts:167

`name`

Optional name: string

如果路径以..结尾，目录/文件名可以为空。

定义在: fs.ts:165

`path`

path: string

定义在: fs.ts:160

`FsBinaryFileOption`

用于将二进制数据写入文件的选项对象。

自1.0.0版本起

属性

`contents`

contents: BinaryFileContents

字节数组的内容。

定义在: fs.ts:153

`path`

path: string

要写入文件的路径。

定义在: fs.ts:151

`FsDirOptions`

自1.0.0版本起

属性

`dir`

Optional dir: BaseDirectory

定义在: fs.ts:126

`recursive`

Optional recursive: boolean

定义在: fs.ts:127

`FsOptions`

自1.0.0版本起

属性

`append`

Optional append: boolean

内容是覆盖文件内容还是附加到文件中。

自1.5.0版本起

定义在: fs.ts:118

`dir`

Optional dir: BaseDirectory

定义在: fs.ts:112

`FsTextFileOption`

用于将 UTF-8 字符串写入文件的选项对象。

自1.0.0版本起

属性

`contents`

contents: string

要写入文件的 UTF-8 字符串。

定义在: fs.ts:139

`path`

path: string

要写入文件的路径。

定义在: fs.ts:137

类型别名

`BinaryFileContents`

BinaryFileContents: Iterable<number> | ArrayLike<number> | ArrayBuffer

定义在: fs.ts:142

方法

`copyFile`

copyFile(source: string, destination: string, options?: FsOptions): Promise<void>

将文件复制到目的地。

示例


import { copyFile, BaseDirectory } from '@tauri-apps/api/fs';
// Copy the `$APPCONFIG/app.conf` file to `$APPCONFIG/app.conf.bk`
await copyFile('app.conf', 'app.conf.bk', { dir: BaseDirectory.AppConfig });

自1.0.0版本起

参数

名称	类型
`source`	`string`
`destination`	`string`
`options`	`FsOptions`

返回值: Promise<void>

表示操作成功或失败的promise。

`createDir`

createDir(dir: string, options?: FsDirOptions): Promise<void>

创建一个目录。如果路径的父组件之一不存在，且recursive选项未设置为 "true"，则promise会reject。

示例


import { createDir, BaseDirectory } from '@tauri-apps/api/fs';
// Create the `$APPDATA/users` directory
await createDir('users', { dir: BaseDirectory.AppData, recursive: true });

自1.0.0版本起

参数

名称	类型
`dir`	`string`
`options`	`FsDirOptions`

返回值: Promise<void>

表示操作成功或失败的promise。

`exists`

exists(path: string, options?: FsOptions): Promise<boolean>

检查路径是否存在。

示例


import { exists, BaseDirectory } from '@tauri-apps/api/fs';
// Check if the `$APPDATA/avatar.png` file exists
await exists('avatar.png', { dir: BaseDirectory.AppData });

自1.1.0版本起

参数

名称	类型
`path`	`string`
`options`	`FsOptions`

返回值: Promise<boolean>

`readBinaryFile`

readBinaryFile(filePath: string, options?: FsOptions): Promise<Uint8Array>

以字节数组形式读取文件。

示例


import { readBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
// Read the image file in the `$RESOURCEDIR/avatar.png` path
const contents = await readBinaryFile('avatar.png', { dir: BaseDirectory.Resource });

自1.0.0版本起

参数

名称	类型
`filePath`	`string`
`options`	`FsOptions`

返回值: Promise<Uint8Array>

`readDir`

readDir(dir: string, options?: FsDirOptions): Promise<FileEntry[]>

列出目录文件。

示例


import { readDir, BaseDirectory } from '@tauri-apps/api/fs';
// Reads the `$APPDATA/users` directory recursively
const entries = await readDir('users', { dir: BaseDirectory.AppData, recursive: true });

function processEntries(entries) {
  for (const entry of entries) {
    console.log(`Entry: ${entry.path}`);
    if (entry.children) {
      processEntries(entry.children)
    }
  }
}

自1.0.0版本起

参数

名称	类型
`dir`	`string`
`options`	`FsDirOptions`

返回值: Promise<FileEntry[]>

`readTextFile`

readTextFile(filePath: string, options?: FsOptions): Promise<string>

以 UTF-8 编码字符串的形式读取文件。

示例


import { readTextFile, BaseDirectory } from '@tauri-apps/api/fs';
// Read the text file in the `$APPCONFIG/app.conf` path
const contents = await readTextFile('app.conf', { dir: BaseDirectory.AppConfig });

自1.0.0版本起

参数

名称	类型
`filePath`	`string`
`options`	`FsOptions`

返回值: Promise<string>

`removeDir`

removeDir(dir: string, options?: FsDirOptions): Promise<void>

删除一个目录。如果目录不为空，且recursive选项未设置为 true，则promise会reject。

示例


import { removeDir, BaseDirectory } from '@tauri-apps/api/fs';
// Remove the directory `$APPDATA/users`
await removeDir('users', { dir: BaseDirectory.AppData });

自1.0.0版本起

参数

名称	类型
`dir`	`string`
`options`	`FsDirOptions`

返回值: Promise<void>

表示操作成功或失败的promise。

`removeFile`

removeFile(file: string, options?: FsOptions): Promise<void>

删除文件。

示例


import { removeFile, BaseDirectory } from '@tauri-apps/api/fs';
// Remove the `$APPConfig/app.conf` file
await removeFile('app.conf', { dir: BaseDirectory.AppConfig });

自1.0.0版本起

参数

名称	类型
`file`	`string`
`options`	`FsOptions`

返回值: Promise<void>

表示操作成功或失败的promise。

`renameFile`

renameFile(oldPath: string, newPath: string, options?: FsOptions): Promise<void>

重命名文件。

示例


import { renameFile, BaseDirectory } from '@tauri-apps/api/fs';
// Rename the `$APPDATA/avatar.png` file
await renameFile('avatar.png', 'deleted.png', { dir: BaseDirectory.AppData });

自1.0.0版本起

参数

名称	类型
`oldPath`	`string`
`newPath`	`string`
`options`	`FsOptions`

返回值: Promise<void>

表示操作成功或失败的promise。

`writeBinaryFile`

writeBinaryFile(path: string, contents: BinaryFileContents, options?: FsOptions): Promise<void>

将字节数组内容写入文件。

示例


import { writeBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a binary file to the `$APPDATA/avatar.png` path
await writeBinaryFile('avatar.png', new Uint8Array([]), { dir: BaseDirectory.AppData });

自1.0.0版本起

参数

名称	类型	描述
`path`	`string`	-
`contents`	`BinaryFileContents`	-
`options?`	`FsOptions`	Configuration object.

返回值: Promise<void>

表示操作成功或失败的promise。

writeBinaryFile(file: FsBinaryFileOption, options?: FsOptions): Promise<void>

将字节数组内容写入文件。

示例


import { writeBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a binary file to the `$APPDATA/avatar.png` path
await writeBinaryFile({ path: 'avatar.png', contents: new Uint8Array([]) }, { dir: BaseDirectory.AppData });

自1.0.0版本起

参数

名称	类型	描述
`file`	`FsBinaryFileOption`	The object containing the file path and contents.
`options?`	`FsOptions`	Configuration object.

返回值: Promise<void>

表示操作成功或失败的promise。

`writeTextFile`

writeTextFile(path: string, contents: string, options?: FsOptions): Promise<void>

写入 UTF-8 文本文件。

示例


import { writeTextFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a text file to the `$APPCONFIG/app.conf` path
await writeTextFile('app.conf', 'file contents', { dir: BaseDirectory.AppConfig });

自1.0.0版本起

参数

名称	类型
`path`	`string`
`contents`	`string`
`options?`	`FsOptions`

返回值: Promise<void>

writeTextFile(file: FsTextFileOption, options?: FsOptions): Promise<void>

写入 UTF-8 文本文件。

示例


import { writeTextFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a text file to the `$APPCONFIG/app.conf` path
await writeTextFile({ path: 'app.conf', contents: 'file contents' }, { dir: BaseDirectory.AppConfig });

自1.0.0版本起

参数

名称	类型
`file`	`FsTextFileOption`
`options?`	`FsOptions`

返回值: Promise<void>

表示操作成功或失败的promise。

event(事件模块)

globalShortcut(全局快捷键模块)