📝 文件 API

這裡提供了對接 底層系統功能 的接口，包括操作文件系統、訪問網絡等

對插件開發來說，實現與系統底層接口的互通是重要的擴展，大大增強了插件開發的靈活性。

📝 簡單文件讀寫 API

下面這些API提供了簡單讀寫文件的接口，為偶爾讀取和寫入文件提供方便。
腳本引擎使用文件類 File 來封裝文件相關操作
如果需要頻繁地操作文件，請使用下方的文件類，以提高性能

注：所有文本相關的操作均使用UTF-8編碼。

讀入文件的所有內容

File.readFrom(path[,isBinary])

• 參數：
• path : String
  目標文件的路徑，相對路徑以BDS根目錄為基準
• isBinary : Boolean
  是否按二進制方式讀取，默認為false
• 返回值：文件的所有數據
• 返回值類型：String / ByteBuffer
• 如返回值為 Null 則表示讀取失敗

如果 isBinary 為 true，則返回 ByteBuffer，否則返回 String。

在0.19.1之前，此函數只能使用 File.readFrom(path) 形式調用，返回值類型固定為 String。

向指定文件寫入內容

File.writeTo(path,text)

• 參數：

• path : String
  目標文件的路徑，相對路徑以BDS根目錄為基準

• text : String / ByteBuffer
  要寫入的內容

• 返回值：是否寫入成功

• 返回值類型：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
• 如果打開失敗，將拋出異常

文件的打開模式有如下可選項：

當使用ReadMode和WriteMode時，可以使用seekTo手動移動文件指針位置

如果給出路徑的文件存在，會直接打開那個已存在的文件；如果文件不存在，會自動創建新的文件。如果打開的路徑中有部分目錄不存在，接口將會自動創建目錄。

在打開文件之後，就可以使用下述文件對象的接口來讀寫文件。

文件對象 - 屬性

每一個文件對象都包含一些固定的對象屬性。對於某個特定的文件對象fi，有以下這些屬性

這些對象屬性都是隻讀的，無法被修改

文件對象 - 函數

每一個文件對象都包含一些可以執行的成員函數（成員方法）。對於某個特定的文件對象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

如果在上述接口使用中遇到了失敗，在獲取錯誤碼完成之後，使用此函數清除錯誤狀態，以繼續正常使用文件對象