📁 文件

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

Client & Server🧑‍💻API Source

---

信息

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

🎒 示例

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	删除文件夹或文件
	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

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.