版本：bleeding-edge 🩸

📁 File

File 表示一个系统文件条目。

信息

无法打开服务器文件夹之外的文件。所有路径都必须相对于服务器的可执行文件所在文件夹。默认情况下，所有文件均以二进制文件方式打开。

🎒 示例

Server/Index.lua
local configuration_file = File("my_awesome_configuration.json")

local configuration_file_json = JSON.parse(configuration_file:Read())

📂 文件访问与沙盒

文件访问受到沙盒保护。只允许对指定的目录和文件进行写入或读取操作。

允许的扩展名

仅允许访问（读取和写入）以下文件扩展名：

.txt .dat .json .toml .xml .csv .log .png .jpg .jpeg .webp .webm .mp3 .wav .ogg .mp4

备注

如果你认为应该将某个文件扩展名添加到允许列表中，请在反馈中心中报告。

服务器端

在服务器端，只允许访问服务器文件夹本身（服务器可执行文件所在的位置）内的文件。此外，也不允许访问 Config.toml 文件。

访问包中的文件示例：Packages/My-Package/Server/MyFile.json。

客户端

在客户端，我们有 .transient/ 文件夹的概念，这是一个在客户端缓存的 Packages/ 文件夹内自动生成的文件夹，可以在其中以更持久的方式创建文件。

不允许访问客户端缓存文件夹 Packages/ 之外的文件，并且只允许在 .transient/ 文件夹本身内进行写入访问。

默认目录位于客户端缓存的 Packages/.transient/ 文件夹中。

从包中访问文件（具有只读权限）的示例：../my-package/Client/MyFile.json。

访问临时文件（具有写入权限）的示例：MyFile.json。

🛠 构造函数

Default Constructor

No description provided

local my_file = File(file_path, truncate?)

Parameters

Type	Name	Default	Description
string	`file_path`	Required parameter	如果在服务器端，这是相对于服务器可执行文件的路径。否则如果在客户端，这是相对于客户端 'Packages/.transient/' 文件夹的路径
boolean	`truncate`	`false`	是否在打开文件时清除该文件

🗿 静态函数

Returns	Name	Description
boolean	`CreateDirectory`	创建一个目录（针对传入的每个文件夹）
boolean	`Exists`	验证文件系统中是否存在该条目
table of string	`GetDirectories`	根据给定路径获取所有目录的列表
table of string	`GetFiles`	获取目录中的所有文件列表
string	`GetFullPath`	根据当前端（客户端或服务器端），获取给定相对路径的完整路径
boolean	`IsDirectory`	检查路径是否为目录
boolean	`IsRegularFile`	检查路径是否为文件
integer	`Remove`	删除文件夹或文件
boolean	`Rename`	重命名或移动文件夹或文件
integer	`Time`	返回文件最后一次被修改的 Unix 时间

Slow

`CreateDirectory`

创建一个目录（针对传入的每个文件夹）

local ret = File.CreateDirectory(path)

Parameters

Type	Parameter	Default	Description
string	`path`	Required parameter	文件夹路径

Returns

Type	Description
boolean	如果成功

Moderate

`Exists`

验证文件系统中是否存在该条目

local ret = File.Exists(path)

Parameters

Type	Parameter	Default	Description
string	`path`	Required parameter	文件或文件夹的路径

Returns

Type	Description
boolean	如果存在

Slow

`GetDirectories`

获取给定路径下的所有目录列表，可选择使用过滤器。请注意，由于文件系统工作方式的不同，Linux 和 Windows 之间的结果可能会有所差异

local ret = File.GetDirectories(path_filter?, max_depth?)

Parameters

Type	Parameter	Default	Description
string	`path_filter?`		路径过滤器
integer	`max_depth?`	`-1`	搜索时在文件夹中进一步深入的最大深度。传入 -1 表示最大深度

Returns

Type	Description
table of string	目录列表

Slow

`GetFiles`

获取目录中的所有文件列表，可选择使用过滤器。请注意，由于文件系统工作方式的不同，Linux 和 Windows 之间的结果可能会有所差异

local ret = File.GetFiles(path_filter?, extension_filter?, max_depth?)

Parameters

Type	Parameter	Default	Description
string or table	`path_filter?`		路径过滤器
string	`extension_filter?`		例如：`.lua`
integer	`max_depth?`	`-1`	搜索时在文件夹中进一步深入的最大深度。传入 -1 表示最大深度

Returns

Type	Description
table of string	文件列表

Moderate

`GetFullPath`

根据当前端（客户端或服务器端），获取给定相对路径的完整路径

local ret = File.GetFullPath(path)

Parameters

Type	Parameter	Default	Description
string	`path`	Required parameter	文件或目录的路径

Returns

Type	Description
string	解析后的完整路径

Moderate

`IsDirectory`

检查路径是否为目录

local ret = File.IsDirectory(path)

Parameters

Type	Parameter	Default	Description
string	`path`	Required parameter	文件夹路径

Returns

Type	Description
boolean	该路径是否为目录

Moderate

`IsRegularFile`

检查路径是否为文件

local ret = File.IsRegularFile(path)

Parameters

Type	Parameter	Default	Description
string	`path`	Required parameter	文件路径

Returns

Type	Description
boolean	该路径是否为常规文件

Slow

`Remove`

删除文件夹或文件

local ret = File.Remove(path)

Parameters

Type	Parameter	Default	Description
string	`path`	Required parameter	文件或文件夹的路径

Returns

Type	Description
integer	被删除的文件数量

Slow

`Rename`

重命名或移动文件夹或文件

local ret = File.Rename(old_path, new_path)

Parameters

Type	Parameter	Default	Description
string	`old_path`	Required parameter	现有文件或文件夹的路径
string	`new_path`	Required parameter	文件或文件夹的新路径

Returns

Type	Description
boolean	是否重命名成功

Slow

`Time`

返回文件最后一次被修改的 Unix 时间

local ret = File.Time(path)

Parameters

Type	Parameter	Default	Description
string	`path`	Required parameter	文件路径

Returns

Type	Description
integer	以 Unix 时间表示的最后更新时间

🦠 函数

Returns	Name	Description
	`Close`	关闭文件并销毁该实体
	`Flush`	将内容刷新写入到文件中
boolean	`HasFailed`	检查上一次操作是否失败
boolean	`IsBad`	检查文件状态是否为 Bad
boolean	`IsEOF`	检查文件状态是否为 End of File（文件末尾）
boolean	`IsGood`	检查文件状态是否为 Good
string	`Read`	从文件中读取字符并将其返回。同时将文件指针移动到最新的读取位置。传入 0 以读取整个文件
	`ReadAsync`	异步地从文件中读取字符。
table	`ReadJSON`	将整个文件作为 JSON 读取并返回。
	`ReadJSONAsync`	异步地将整个文件作为 JSON 读取并返回。
string	`ReadLine`	读取并返回文件的下一行
	`Seek`	将文件指针设置到特定位置
integer	`Size`	返回文件的大小
	`Skip`	从当前文件指针位置跳过 n 个位置
integer	`Tell`	返回当前文件指针的位置
	`Write`	在文件的当前位置写入数据

Blocking

`Close`

关闭文件并销毁该实体

my_file:Close()

Blocking

`Flush`

将内容刷新写入到文件中

my_file:Flush()

Optimal

`HasFailed`

检查上一次操作是否失败

local ret = my_file:HasFailed()

Returns

Type	Description
boolean	如果上一次操作失败

Optimal

`IsBad`

检查文件状态是否为 Bad

local ret = my_file:IsBad()

Returns

Type	Description
boolean	如果状态为 Bad

Optimal

`IsEOF`

检查文件状态是否为 End of File（文件末尾）

local ret = my_file:IsEOF()

Returns

Type	Description
boolean	如果为 EOF

Optimal

`IsGood`

检查文件状态是否为 Good

local ret = my_file:IsGood()

Returns

Type	Description
boolean	如果状态为 Good

Blocking

`Read`

从文件中读取字符并将其返回。同时将文件指针移动到最新的读取位置。传入 0 以读取整个文件

local ret = my_file:Read(length?)

Parameters

Type	Parameter	Default	Description
integer	`length?`	`0`	要从文件中读取的长度，留空（或为 0）以读取整个文件

Returns

Type	Description
string	文件数据

Optimal

`ReadAsync`

异步地从文件中读取字符。

my_file:ReadAsync(length?, callback)

Parameters

Type	Parameter	Default	Description
integer	`length?`	`0`	要从文件中读取的长度，传入 0 以读取整个文件
function	`callback`	Required parameter	回调函数 with this format

Blocking

`ReadJSON`

将整个文件作为 JSON 读取并返回。

local ret = my_file:ReadJSON()

Returns

Type	Description
table	解析后的表

Optimal

`ReadJSONAsync`

异步地将整个文件作为 JSON 读取并返回。

my_file:ReadJSONAsync(callback)

Parameters

Type	Parameter	Default	Description
function	`callback`	Required parameter	带有读取文件的回调函数 with this format

Blocking

`ReadLine`

读取并返回文件的下一行

local ret = my_file:ReadLine()

Returns

Type	Description
string	文件行数据

Moderate

`Seek`

将文件指针设置到特定位置

my_file:Seek(position)

Parameters

Type	Parameter	Default	Description
integer	`position`	Required parameter	偏移文件指针的位置

Optimal

`Size`

返回文件的大小

local ret = my_file:Size()

Returns

Type	Description
integer	文件大小

Optimal

`Skip`

从当前文件指针位置跳过 n 个位置

my_file:Skip(amount)

Parameters

Type	Parameter	Default	Description
integer	`amount`	Required parameter	偏移文件指针的数量

Optimal

`Tell`

返回当前文件指针的位置

local ret = my_file:Tell()

Returns

Type	Description
integer	当前文件指针位置

Slow

`Write`

在文件的当前位置写入数据

my_file:Write(data)

Parameters

Type	Parameter	Default	Description
string	`data`	Required parameter	要写入文件的数据

🚀 事件

This class doesn't have own events.

🎒 示例​

📂 文件访问与沙盒​

允许的扩展名​

服务器端​

客户端​

🛠 构造函数​

Default Constructor​

Parameters

🗿 静态函数​

CreateDirectory​

Parameters

Returns

Exists​

Parameters

Returns

GetDirectories​

Parameters

Returns

GetFiles​

Parameters

Returns

GetFullPath​

Parameters

Returns

IsDirectory​

Parameters

Returns

IsRegularFile​

Parameters

Returns

Remove​

Parameters

Returns

Rename​

Parameters

Returns

Time​

Parameters

Returns

🦠 函数​

Close​

Flush​

HasFailed​

Returns

IsBad​

Returns

IsEOF​

Returns

IsGood​

Returns

Read​

Parameters

Returns

ReadAsync​

Parameters

ReadJSON​

Returns

ReadJSONAsync​

Parameters

ReadLine​

Returns

Seek​

Parameters

Size​

Returns

Skip​

Parameters

Tell​

Returns

Write​

Parameters

🚀 事件​

🎒 示例

📂 文件访问与沙盒

允许的扩展名

服务器端

客户端

🛠 构造函数

Default Constructor

🗿 静态函数

`CreateDirectory`

`Exists`

`GetDirectories`

`GetFiles`

`GetFullPath`

`IsDirectory`

`IsRegularFile`

`Remove`

`Rename`

`Time`

🦠 函数

`Close`

`Flush`

`HasFailed`

`IsBad`

`IsEOF`

`IsGood`

`Read`

`ReadAsync`

`ReadJSON`

`ReadJSONAsync`

`ReadLine`

`Seek`

`Size`

`Skip`

`Tell`

`Write`

🚀 事件