跳至主要内容

Saver

重要 注意 提醒

Coding Style wiki​

Saver 是 SaverSystem 的抽象儲存器基類 (實作 ISaver、IDisposable)，定義字串/整數/浮點數的基本鍵值存取抽象方法 (由子類決定儲存後端)，並提供以文本形式儲存的 Data Map 功能 (多筆 key value 數據打包於單一字串鍵中，具解析緩存)；內建實作有 PlayerPrefsSaver 與 EditorPrefsSaver，也可繼承自行擴展。

命名空間OxGKit.SaverSystem
類型public abstract class Saver : ISaver, IDisposable
原始碼Saver.cs、ISaver.cs
using OxGKit.SaverSystem;

快速上手​

using OxGKit.SaverSystem;

// 建立儲存器 (以內建 PlayerPrefsSaver 為例)
Saver saver = new PlayerPrefsSaver();

// 基本存取
saver.SaveInt("language", 2);
int language = saver.GetInt("language", 0);

// 文本形式儲存 (單一 contentKey 中儲存多筆 key value 數據)
saver.SaveData("appPrefs", "lastLogin", "2026-07-29");
string lastLogin = saver.GetData("appPrefs", "lastLogin", null);

通用規則​

ISaver 介面​

public interface ISaver
{
    void SaveString(string key, string value);

    string GetString(string key, string defaultValue = "");

    void SaveInt(string key, int value);

    int GetInt(string key, int defaultValue = 0);

    void SaveFloat(string key, float value);

    float GetFloat(string key, float defaultValue = 0f);

    bool HasKey(string key);

    void DeleteKey(string key);

    void DeleteAll();
}

Saver 的基本存取方法皆為 abstract (對應 ISaver 介面)，由子類覆寫決定儲存後端；文本數據功能 (SaveData / GetData / DeleteData / DeleteContext) 則由基類實作，任何子類皆可直接使用。

文本數據格式​

SaveData 會將多筆數據以每行一筆 key value 的格式，儲存於單一字串鍵 (contentKey) 的文本內容中：

# 以 '#' 開頭的行視為註解
lastLogin 2026-07-29
resolution 1920x1080

重要 每行以第一個空格分隔 key 與 value：key 不可包含空格；value 可包含空格，但不可包含換行 (逐行解析)。

提醒 建議重複使用同一個 Saver 實例，GetData 的解析緩存以實例為單位，每次重新建立實例會失去緩存效果。

儲存定位​

注意 本系統定位為設定值與小型數據的鍵值儲存 (模組概觀詳見模塊介紹)；無 bool 與物件 API，bool 可以 int (0/1) 儲存，物件可自行序列化為 JSON 字串後透過 SaveString 儲存。

基本存取​

方法總覽​

方法說明
SaveString儲存字串。
GetString取得字串。
SaveInt儲存整數。
GetInt取得整數。
SaveFloat儲存浮點數。
GetFloat取得浮點數。
HasKey檢查指定鍵是否存在。
DeleteKey刪除指定鍵。
DeleteAll刪除所有鍵。

SaveString​

public abstract void SaveString(string key, string value)

儲存字串 (由子類實作儲存後端)。

saver.SaveString("name", "michael");

GetString​

public abstract string GetString(string key, string defaultValue = "")

取得字串，鍵不存在時返回 defaultValue。

SaveInt​

public abstract void SaveInt(string key, int value)

儲存整數。

saver.SaveInt("language", 2);

GetInt​

public abstract int GetInt(string key, int defaultValue = 0)

取得整數，鍵不存在時返回 defaultValue。

SaveFloat​

public abstract void SaveFloat(string key, float value)

儲存浮點數。

saver.SaveFloat("bgmVolume", 0.8f);

GetFloat​

public abstract float GetFloat(string key, float defaultValue = 0)

取得浮點數，鍵不存在時返回 defaultValue。

HasKey​

public abstract bool HasKey(string key)

檢查指定鍵是否存在。

DeleteKey​

public abstract void DeleteKey(string key)

刪除指定鍵。

DeleteAll​

public abstract void DeleteAll()

刪除所有鍵 (影響範圍依儲存後端而定，詳見各實作頁面)。

文本數據 (Data Map)​

方法總覽​

方法說明
SaveData透過文本形式儲存數據 (新增或更新單筆 key value)。
GetData獲取文本中的特定數據 (具解析緩存)。
DeleteData刪除文本中的特定數據。
DeleteContext刪除全文本數據 (含解析緩存)。
ParsingDataMap(靜態) 解析文本數據為字典。
Dispose釋放解析緩存。

SaveData​

public void SaveData(string contentKey, string key, string value)

於 contentKey 的文本內容中新增或更新一筆 key value 數據 (內部透過 GetString / SaveString 讀寫整份文本)，並標記 Dirty 供 GetData 重新解析。

saver.SaveData("appPrefs", "lastLogin", "2026-07-29");
saver.SaveData("appPrefs", "resolution", "1920x1080");

GetData​

public string GetData(string contentKey, string key, string defaultValue = null)

獲取 contentKey 文本中指定 key 的數據；文本不存在或該筆數據為空時返回 defaultValue。解析結果會以 contentKey 為單位緩存 (Dirty Flag 機制)，僅於 SaveData / DeleteData 之後才會重新解析文本。

string lastLogin = saver.GetData("appPrefs", "lastLogin", null);

DeleteData​

public void DeleteData(string contentKey, string key)

刪除 contentKey 文本中指定 key 的數據行，並標記 Dirty。

saver.DeleteData("appPrefs", "lastLogin");

DeleteContext​

public void DeleteContext(string contextKey)

刪除整份文本數據 (內部呼叫 DeleteKey 刪除儲存鍵)，並一併清除對應的解析緩存與 Dirty 標記。

saver.DeleteContext("appPrefs");

ParsingDataMap​

public static Dictionary<string, string> ParsingDataMap(string content)

(靜態方法) 將文本內容解析為 Dictionary<string, string>：依換行逐行分割，跳過 # 開頭的註解行，每行以第一個空格分隔 key 與 value；重複的 key 只取第一筆。

// 亦可單獨作為 "key value" 行格式的配置文件解析器
string content = saver.GetString("appPrefs");
Dictionary<string, string> dataMap = Saver.ParsingDataMap(content);

提醒 由於支持 # 註解行，此格式也適合作為可手動編輯的配置文件格式 (例如 OxGFrame 的媒體 URL 配置文件即使用 Saver.ParsingDataMap 解析)。

Dispose​

public virtual void Dispose()

釋放解析緩存 (Data Map 緩存與 Dirty 標記)。

注意 Dispose 後緩存字典會被置空，不可再使用該實例的文本數據功能，需重新建立 Saver 實例。

自定義 Saver​

繼承 Saver 並覆寫抽象方法，即可將數據儲存至任意後端 (檔案、加密儲存、雲端等)；文本數據功能 (Data Map) 由基類提供，無需另行實作。

using OxGKit.SaverSystem;

public class FileSaver : Saver
{
    public override void SaveString(string key, string value) { /* 寫入檔案 */ }

    public override string GetString(string key, string defaultValue = "") { /* 讀取檔案 */ return defaultValue; }

    public override void SaveInt(string key, int value) => this.SaveString(key, value.ToString());

    public override int GetInt(string key, int defaultValue = 0) => int.TryParse(this.GetString(key), out var value) ? value : defaultValue;

    public override void SaveFloat(string key, float value) => this.SaveString(key, value.ToString());

    public override float GetFloat(string key, float defaultValue = 0f) => float.TryParse(this.GetString(key), out var value) ? value : defaultValue;

    public override bool HasKey(string key) { /* ... */ return false; }

    public override void DeleteKey(string key) { /* ... */ }

    public override void DeleteAll() { /* ... */ }
}