F8 ExcelTool

April 20, 2026 · View on GitHub

F8 框架初衷：希望自己点击 F8，就能开始制作游戏，不想多余的事。

F8 Framework original intention: Just click F8 and start making the game, don't want to be redundant.

简介

Unity 读取 Excel 的工具

加载缓存：高性能，加载手动生成的 Excel 二进制缓存
加载文件：高适应性，运行时自动读取最新 Excel，无需人工干预
- 必须先完成本指南的初始化部分（因：对于结构、类型等变动，运行时无法刷新 C# 代码）。

导入插件（需要首先导入核心）

注意！内置在->F8Framework核心：https://github.com/TippingGame/F8Framework.git
方式一：直接下载文件，放入Unity
方式二：Unity->点击菜单栏->Window->Package Manager->点击+号->Add Package from git URL->输入：https://github.com/TippingGame/F8Framework.git

视频教程：【Unity框架】（1）配置表使用

初始化

在 Assets 下，创建 StreamingAssets/config 目录，按照下面 "Excel 示例" 创建你的 Excel（Excel例子）（首次F8后自动创建Excel）
点击菜单的开发工具项 -> 导入配置表_F8（快捷键），在 Assets/AssetBundles/Config/BinConfigData 下生成 binary 文件（也可选择 json 文件）
注意：如果你不想生成在AssetBundles目录下，可在 F5 打包工具设置导表目录
如无意外，根目录下会生成 Assets/F8Framework/ConfigData/ 目录和相关文件，（注意：F8后会清除框架自带的，并重新生成，一切报错均来自这些代码的冲突）
（可选项）更改Excel存放目录，开发工具项 -> 设置Excel存放目录
（可选项）通过 Editor，可在运行时读取 Excel 数据：点击菜单的开发工具项 -> 运行时读取 Excel_F7（快捷键）

Excel 示例

类型可分为 1. 基础类型 2. 容器类型 3. 特殊类型

1.基础类型支持
- C# 基础类型支持：（char，bool，byte，short，int，long，float，double，decimal，str / string，obj / object，datetime，sbyte，ushort，uint，ulong）
- Unity基础类型支持：（vec2 / vector2，vec3 / vector3，vec4 / vector4，vec2int / vector2int，vec3int / vector3int，quat / quaternion，color，color32，matrix4x4）
- 标准JSON规范类型：（json）

Excel 示例：（id 是唯一索引，值类型，必须添加！）

int	long	bool	float	double	str	vector3	color	datetime
id	name1	name2	name3	name4	name5	name6	name7	name8
1	9935434343	true	2.725412	1.346655321	读取 Excel 工具	1.23,1.35,1.45	122,135,145,255	1750316265001
2	9935434343	1	2.725412	1.346655321	读取 Excel 工具	[1.23,1.35,1.45]	[122,135,145,255]	2025-06-19T14:30:00.1234567+08:00

2.容器类型支持
- 数组，交错数组（[] / [][] / [][][]）
- 列表（list<>）
- 字典（dict<,> / dictionary<,>，注意：导出json格式表key只能为基础类型和枚举，如需要支持容器可使用binary）
- 值元组（valuetuple<,>，最高支持7个类型）
- 哈希集（hashset<>）
- 容器内可以填写任意的类型（变体类型除外）

Excel 示例：

int[]	string[]	vec2[]	obj[][]	list<obj>	dict<int,list<string>>	valuetuple<int,string>
name1	name2	name3	name4	name5	name6	name7
[1,5]	[test,str]	[[12,66],[12,66]]	[[22,"str"],[33,"obj"]]	123,1.888,"列表"	1,[字,典],2,["字,典"]	1,值元组
[1,5]	[test,str]	[[12,66],[12,66]]	[[22,"str"],[33,"obj"]]	[123,1.888,"列表"]	[1,["字","典"],2,["字,典"]]	[1,"值,元组"]

3.特殊类型支持
- 枚举（enum<name,int,Flags>{}）
  - name为枚举名称，int为枚举类型，Flags为枚举特性
  - 默认在当前表生成枚举类
  - enum<Sheet1.name>可跨表访问枚举，Sheet1为表名，name为枚举名称
- 变体（variant<name,variantName>）
  - name为当前表内其他变量的名称，variantName为变体名称
  - 可实现一键切换配置表变体，以此实现多语言/多版本配置

Excel 示例：
（可选参数：int类型(默认)，Flags特性，标志枚举：Value1, Value2，可跨表访问：Sheet1.name）

enum<name,int,Flags>{Value1 = 1,Value2 = 2,Value3 = 4,Value4 = 8,}	enum<Sheet1.name>	enum<Status,long>{OK = 200,Success = 200,Created = 201,Accepted = 202,}
name1	name2	name3
Value1	Value1	200
Value2	Value2	Success
Value1, Value2	Value3	201
Value4	Value4	202

// 设置变体名
FF8.Config.VariantName = "English";

// 设置单个表变体名（更优先）
Sheet1.VariantName = "English";

string	variant<desc,English>	variant<desc,Korean>	int	variant<attack,English>	variant<attack,Korean>
desc	desc	desc	attack
中文1	Chinese 1	중국어 1	1000	800	300
中文2	Chinese 2	중국어 2	1000	800	300
中文3	Chinese 3	중국어 3	1000	800	300
中文4	Chinese 4	중국어 4	1000	800	300

（你还可以拓展其他类型：ReadExcel.cs）

额外说明：
- 整行不导出：id留空
- 整列不导出：type留空或name留空

使用范例

在使用 Excel 数据前，需要执行：

加载二进制或者json配置方式：

// 指定Sheet名字加载
Sheet1 sheet1 = FF8.Config.Load<Sheet1>("Sheet1");

// 同步加载全部配置
FF8.Config.LoadAll();

// 异步加载全部配置
yield return FF8.Config.LoadAllAsyncIEnumerator();
// 也可以这样
foreach(var item in FF8.Config.LoadAllAsync())
{
    yield return item;
}
// async/await方式（无多线程，WebGL也可使用）
await FF8.Config.LoadAllAsyncTask();

运行时读取Excel的方式（如没有需求请谨慎使用）：

FF8.Config.RuntimeLoadAll(); // 运行时加载 Excel 最新文件

打印数据：

基础类型，譬如 int/float/string，请参考C# 类型系统 - Microsoft Document：

// 注意：GetSheet1ByID 方法为自动生成的。
// 注意：Sheet1 需替换为实际 Sheet 名
// 注意：name 需替换为实际表头
// 注意：2 代表您设置的 ID 2 的行
// 单个表单个数据
LogF8.Log(FF8.Config.GetSheet1ByID(2).name);

// 单个表全部数据
foreach (var item in FF8.Config.GetSheet1())
{
    LogF8.Log(item.Key);
    LogF8.Log(item.Value.name);
}

使用到的库

Excel.dll（已修改缓存地址为Application.persistentDataPath，新增使用byte[]读取Excel方法）
I18N.CJK.dll
I18N.dll
I18N.MidEast.dll
I18N.Other.dll
I18N.Rare.dll
I18N.West.dll
ICSharpCode.SharpZipLib.dll
LitJson.dll（已修改字典Key支持所有基础和枚举类型，增加C#类型：HashSet，增加Unity常用类型：Type，Vector2，Vector3，Vector4，Quaternion，GameObject，Transform，Color，Color32，Bounds，Rect，RectOffset，LayerMask，Vector2Int，Vector3Int，RangeInt，BoundsInt，Matrix4x4，修复DateTime精度丢失的问题，修复long报错的问题）

你可能需要写入Excel

使用 EPPlus.dll（已内置）但未启用，请手动选择编译的平台

    public static void WriteExcel(string str, int row, int col, string value)
    {
        string filePath = Application.streamingAssetsPath + "/"+ str + ".xlsx";

        FileInfo excelName = new FileInfo(filePath);

        using (OfficeOpenXml.ExcelPackage package = new OfficeOpenXml.ExcelPackage(excelName))
        {
            // 获取第1个sheet
            OfficeOpenXml.ExcelWorksheet worksheet = package.Workbook.Worksheets[1];
            // 修改某一行，列的数据
            worksheet.Cells[row, col].Value = value;
            // 保存excel
            package.Save();
        }
    }

注意

由于 Android 资源都在包内，在 Android 上使用实时读取Excel功能，需要先复制到可读写文件夹中再进行读取
框架内使用ICSharpCode.SharpZipLib.Zip库ZipFile类直接读取，可直接读取StreamingAssets文件，具体请看：SyncStreamingAssetsLoader.cs

    // 同步读取StreamingAssets/config文件夹下的文件
    string[] files = SyncStreamingAssetsLoader.Instance.ReadAllLines("config/fileindex.txt");
    
    // 使用后释放资源
    SyncStreamingAssetsLoader.Instance.Close();