脚本引擎 - 系统功能接口文档

这里提供了对接 底层系统功能 的接口，包括操作文件系统、访问网络等

对插件开发来说，实现与系统底层接口的互通是重要的扩展，大大增强了插件开发的灵活性。

📝 简单文件读写 API

下面这些API提供了简单读写文件的接口，为偶尔读取和写入文件提供方便。
脚本引擎使用文件类 File 来封装文件相关操作
如果需要频繁地操作文件，请使用下方的文件类，以提高性能

注：所有文本相关的操作均使用UTF-8编码。

读入文件的所有内容

File.readFrom(path)

• 参数：
• path : String
  目标文件的路径，相对路径以BDS根目录为基准
• 返回值：文件的所有数据
• 返回值类型：String
• 如返回值为 Null 则表示读取失败

向指定文件写入内容

File.writeTo(path,text)

• 参数：

• path : String
  目标文件的路径，相对路径以BDS根目录为基准

• text : String
  要写入的内容

• 返回值：是否写入成功

• 返回值类型：Boolean

注：若文件不存在会自动创建，若存在则会先将其清空再写入

向指定文件追加一行

File.writeLine(path,text)

• 参数：

• path : String
  目标文件的路径，相对路径以BDS根目录为基准

• text : String
  要写入的内容

• 返回值：是否写入成功
• 返回值类型：Boolean

📋 文件对象 API

在脚本引擎中，使用「文件对象」来操作和读写某一个特定的文件。

创建一个新的文件对象

[JavaScript] new File(path,mode[,isBinary])
[Lua] File(path,mode[,isBinary])

• 参数：
• path : String
  想要打开的文件路径
• mode : Enum
  文件的打开模式
• isBinary : Boolean
  （可选参数）是否以二进制模式打开文件，默认为false
  普通模式下，文件读写过程中，换行符将会被按本地格式转换。如果你使用二进制模式打开文件，表明此文件并非普通的文本格式，这些自动转换将不会发生。
• 返回值：打开的文件对象
• 返回值类型：File
• 如果打开失败，将抛出异常

文件的打开模式有如下可选项：

打开模式	表示的含义
file.ReadMode	准备读取文件内容
file.WriteMode	准备写入文件。如果文件已存在，会被清空
file.AppendMode	准备写入文件。之后写入的任何内容都将会被追加到文件最后

当使用ReadMode和WriteMode时，可以使用seekTo手动移动文件指针位置

如果给出路径的文件存在，会直接打开那个已存在的文件；如果文件不存在，会自动创建新的文件。如果打开的路径中有部分目录不存在，接口将会自动创建目录。

在打开文件之后，就可以使用下述文件对象的接口来读写文件。

文件对象 - 属性

每一个文件对象都包含一些固定的对象属性。对于某个特定的文件对象fi，有以下这些属性

属性	含义	类型
fi.path	当前文件路径	String
fi.absolutePath	当前文件的绝对路径	String
fi.size	当前文件大小	Integer

这些对象属性都是只读的，无法被修改

文件对象 - 函数

每一个文件对象都包含一些可以执行的成员函数（成员方法）。对于某个特定的文件对象fi，可以通过以下这些函数对这个文件进行一些操作

同步读写

使用同步读写接口时需要注意，如果文件过大或者读写内容过多，消耗时间过长，可能造成游戏卡顿
如果读写内容不多，使用同步接口有更好的开发体验
如果内容较多，可以使用后面的异步读写接口

从文件读取文本 / 二进制数据

fi.readSync(cnt)

• 参数：
• cnt : Number
  要读取的字符数 / 字节数
• 返回值：读取的字符串内容 / 二进制数据
• 返回值类型：String / ByteBuffer
• 如返回值为 Null 则表示读取失败

从当前文件指针处开始读取。如果文件以二进制模式打开，则返回ByteBuffer，否则返回String

从文件读取一行文本

fi.readLineSync()

• 返回值：读取的字符串内容
• 返回值类型：String
• 如返回值为 Null 则表示读取失败

注意，字符串尾部的换行符要自行处理

从文件读取所有内容

fi.readAllSync()

• 返回值：读取的字符串内容 / 二进制数据
• 返回值类型：String / ByteBuffer
• 如返回值为 Null 则表示读取失败

从当前文件指针处开始读取，一直读取到文件末尾为止。
如果文件以二进制模式打开，则返回ByteBuffer，否则返回String

写入文本 / 二进制数据到文件

fi.writeSync(str)

• 参数：
• str : String / ByteBuffer
  要写入的内容
• 返回值：是否成功写入
• 返回值类型：Boolean

如果文件以二进制模式打开，传入的参数将被按照二进制字节写入，否则将按照普通文本写入

写入一行文本到文件

fi.writeLineSync(str)

• 参数：
• str : String
  要写入的内容
• 返回值：是否成功写入
• 返回值类型：Boolean

此函数执行时，将在字符串尾自动添加换行符

异步读写

在数据量较大，耗费时间较长时，建议使用异步读写接口，以减少对服务器的影响。

从文件读取文本 / 二进制数据（异步）

fi.read(cnt,callback)

• 参数：
• cnt : Number
  要读取的字符数 / 字节数
• callback : Function
  获取结果的回调函数
• 返回值：是否成功发送请求
• 返回值类型：Boolean

注：参数callback的回调函数原型：function(result)

• result : String / ByteBuffer
  读取到的文本 / 二进制数据
  如 result 为 Null 则表示读取失败

从当前文件指针处开始读取。如果文件以二进制模式打开，则返回ByteBuffer，否则返回String

从文件读取一行文本（异步）

fi.readLine(callback)

• 参数：
• callback : Function
  获取结果的回调函数
• 返回值：是否成功发送请求
• 返回值类型：Boolean

注：参数callback的回调函数原型：function(result)

• result : String
  读取到的文本

注意，字符串尾部的换行符要自行处理

从文件读取所有内容（异步）

fi.readAll(callback)

• 参数：
• callback : Function
  获取结果的回调函数
• 返回值：是否成功发送请求
• 返回值类型：Boolean

注：参数callback的回调函数原型：function(result)

• result : String / ByteBuffer
  读取到的文本 / 二进制数据
  如 result 为 Null 则表示读取失败

从当前文件指针处开始读取，一直读取到文件末尾为止。
如果文件以二进制模式打开，则返回ByteBuffer，否则返回String

写入文本 / 二进制数据到文件（异步）

fi.write(str[,callback])

• 参数：
• str : String / ByteBuffer
  要写入的内容
• callback : Function
  （可选参数）获取结果的回调函数
• 返回值：是否成功发送请求
• 返回值类型：Boolean

如果文件以二进制模式打开，请传入一个ByteBuffer，否则需要传入String

注：参数callback的回调函数原型：function(result)

• result : Boolean
  是否写入成功

写入一行文本到文件（异步）

fi.writeLine(str[,callback])

• 参数：
• str : String
  要写入的内容
• callback : Function
  （可选参数）获取结果的回调函数
• 返回值：是否成功发送请求
• 返回值类型：Boolean

注：参数callback的回调函数原型：function(result)

• result : Boolean
  是否写入成功

此函数执行时，将在字符串尾自动添加换行符

其他通用接口

除了上述的读写接口之外，这里还提供了其他操作文件对象的通用接口

移动文件指针

fi.seekTo(pos,isRelative)

• 参数：
• pos : Number
  文件指针要移动到的位置
• isRelative : Boolean
  是否是相对当前文件指针位置移动
• 返回值：是否移动成功
• 返回值类型：Boolean

如果isRelative为true，pos表示相对当前位置移动，正数为向后移动，负数为向前移动
如果isRelative为false，pos表示相对文件开头移动，为0或正数。如果为-1，表示移动到文件末尾

设定文件大小

fi.setSize(size)

• 参数：
• size : Number
  要设定的目标大小
• 返回值：是否设定成功
• 返回值类型：Boolean

设定的新大小可以大于文件的当前大小。
如果设定的新大小小于文件的当前大小，原文件将被截断。

关闭文件

fi.close()

• 返回值：是否成功关闭
• 返回值类型：Boolean

文件关闭后，严禁再次使用

文件指针是否位于文件尾

fi.isEOF()

• 返回值：文件指针是否处于文件尾
• 返回值类型：Boolean

刷新文件缓冲区

fi.flush()

• 返回值：是否成功刷新
• 返回值类型：Boolean

获取错误码

fi.errorCode()

• 返回值：上一次IO操作产生的错误码
• 返回值类型：Integer

如果在上述接口使用中遇到了失败，可以从这里获取上一个错误码

清除错误状态

fi.clear()

• 返回值：是否成功清除
• 返回值类型：Boolean

如果在上述接口使用中遇到了失败，在获取错误码完成之后，使用此函数清除错误状态，以继续正常使用文件对象