当前位置：首页 > news >正文

【SpreadJS V18.2 新特性】Table 与 DataTable 双向转换功能详解

news 2025/9/2 10:01:24

SpreadJS V18.2 引入了一项强大的新功能，允许用户在静态工作表表格（Table）和绑定数据表（DataTable）之间进行无缝转换。这一功能极大地增强了数据绑定应用程序的灵活性，对于需要结构化数据绑定（如实时分析、报表生成）或快照保存（如数据审计、模板复用）的应用场景尤为重要。

Table 与 DataTable 双向转换

SpreadJS 现在支持用户在普通表格（Regular Tables）和数据表（Data Tables）之间进行无缝转换，轻松应对动态数据集成或静态数据管理的各种场景。这一能力通过两种实现方式提供：

API 驱动方式：使用专门的 convertToDataTable 和 convertFromDataTable 方法进行程序化控制
设计器 UI 操作：通过 SpreadJS Designer 的可视化界面执行转换

下面我们将详细介绍这两种方法的操作步骤，同时强调实际用例和技术细节。

将普通表格转换为数据表

通过将现有表格数据集成到数据管理器（Data Manager）生态系统中，您可以充分利用数据管理器提供的高级功能，如直接与控件绑定、复杂筛选、排序、分组和数据源操作，同时仍能在工作表上使用表格的可视化表示。

重要注意事项和规则

将普通表格转换为数据表时，请牢记以下规则：

未绑定要求：只有尚未绑定到数据源的普通表格才能使用此功能进行转换
数据和公式清除：转换后，原始普通表格数据范围内的所有数据和公式将从工作表单元格中清除，数据和列定义将由数据管理器表格管理
数据管理器表格创建：在 spread.dataManager().tables 集合中会创建一个新表格
绑定关系：原始工作表表格将重新绑定到这个新创建的数据管理器表格，此时工作表表格作为数据管理器所管理数据的视图
命名规则：新的数据管理器表格将尝试使用与原始普通表格相同的名称。如果同名的数据管理器表格已存在，新表格的名称将自动调整，通过添加数字（从1开始，加上相同前缀的最大现有数字）来确保唯一性

使用 API 进行转换

以下代码演示了如何调用 convertToDataTable 方法将普通表格转换为数据表：

// 向工作表添加普通表格
var sheet = spread.getActiveSheet();
sheet.tables.add('table1', 0, 0, 4, 4, GC.Spread.Sheets.Tables.TableThemes.light1);
// 为表格设置值
sheet.setArray(0, 0, [['Id', 'Name', 'Age', 'Grade'],[1000, 'Tom', 23, 98],[1001, 'Bob', 22, 80],[1002, 'Tony', 23, 99]
]);let dmTable = spread.dataManager().tables['table1']; // 此时 dmTable 为 undefined
// 将普通表格转换为数据表，创建并绑定数据管理器表格
let table = sheet.tables.convertToDataTable('table1');
// 现在已从 table1 创建了一个数据管理器表格
let bindingTable = table.getBindingSource(); // 普通表格已转换为数据表
dmTable = spread.dataManager().tables['table1']; // dmTable 已创建
// bindingTable === dmTable // 返回 true，表格的 bindingTable 就是数据管理器中的 dmTable

使用设计器进行转换

设计器提供了用户友好的界面来执行转换操作：

选择表格：点击您想要转换的普通表格内的任意位置。这将激活功能区中的"表设计"选项卡。在"表设计"选项卡的"表绑定"框中，绑定源为空。
访问转换选项：

方法一：转到功能区中的"表格设计"选项卡，在"表格绑定"部分，点击"转换为数据表"按钮。
方法二：右键点击表格，在弹出的上下文菜单中，将鼠标悬停在"表格"子菜单上，然后选择"转换为数据表"。

在弹出的对话框中点击"确定"。
转换成功后，您会看到之前为空的绑定源现在显示为"Table2"—这表明原始普通表格已成功转换为数据表。

将数据表转换为普通表格

SpreadJS 提供了一种方法，可以断开工作表表格与其底层数据管理器（DataManager）源的连接。当您转换数据绑定表格时：

表格中当前显示的数据和任何列公式将被复制并直接设置到工作表中表格所占据的单元格范围内
工作表上的表格实例成为普通表格，不再绑定到数据管理器
数据管理器中的原始数据表不会被此转换过程删除或影响，仍可用于其他用途

当您需要从数据源捕获数据快照并在工作表中静态使用，而不需要表格自动从源更新或不需要该特定表格实例与数据管理器连接时，此功能非常有用。

使用 API 进行转换

以下代码演示了如何调用 convertFromDataTable 方法将数据绑定表格转换回普通表格：

var sheet = spread.getActiveSheet();// 添加数据源
const productsTable = spread.dataManager().addTable("products", {remote: {read: {url: 'https://northwind.vercel.app/api/products'}}
});productsTable.fetch().then(()=>{// 添加普通表格并通过 addFromDataSource 绑定数据管理器表格sheet.tables.addFromDataSource("Table1", 0, 0, "products", GC.Spread.Sheets.Tables.TableThemes.medium7);// 将绑定数据管理器表格的表格转换为普通表格let table = sheet.tables.convertFromDataTable('Table1');let bindingTable = table.getBindingSource(); // 此时 bindingTable 为 null，因为数据表已转换回普通表格
});

检索绑定表格的数据源

SpreadJS V18.2 引入了一个新的 API，可通过编程方式从绑定表格中检索基础数据源，简化了数据操作和同步。GC.Spread.Sheets.Tables.Table 对象上的 getBindingSource 方法允许您检索表格所绑定的基础数据源。

获取绑定源

您可以通过暴露表格的绑定源来识别表格是否绑定到数据管理器表格。

使用 API

GC.Spread.Sheets.Tables.Table 对象上的 getBindingSource 方法允许您检索表格所绑定的基础数据源。

注意：如果表格未绑定到任何数据源，getBindingSource 将返回 null。

示例 1：绑定到对象数组

当使用 JavaScript 数组作为数据源创建或绑定表格时，getBindingSource 将返回该数组。

var source = [{ LastName: "张", FirstName: "三", Title: "销售代表", Phone: "138-1234-5678"},{ LastName: "李", FirstName: "四", Title: "销售副总裁", Phone: "139-8765-4321"},{ LastName: "王", FirstName: "五", Title: "销售代表", Phone: "137-2345-6789"},{ LastName: "赵", FirstName: "六", Title: "销售代表", Phone: "136-3456-7890"},
];
// 假设 'activeSheet' 是当前工作表
const table = activeSheet.tables.addFromDataSource("Table1", 5, 2, source, GC.Spread.Sheets.Tables.TableThemes.dark1);// 获取绑定源 - 它将是 'source' 数组
const bindingSource = table.getBindingSource();
console.log(bindingSource === source); // 应输出 true

示例 2：绑定到数据管理器表格

当使用数据管理器表格的名称作为数据源创建或绑定表格时，getBindingSource 将返回数据管理器中相应的 GC.Data.Table 对象。

// 假设 'spread' 是 SpreadJS 实例
const productsTable = spread.dataManager().addTable("products", {remote: {read: {url: 'https://northwind.vercel.app/api/products'}}
});productsTable.fetch().then(()=>{// 方法 1：添加表格并使用 addFromDataSource 绑定到数据管理器表格const table1 = spread.getActiveSheet().tables.addFromDataSource("Table1", 0, 0, "products", GC.Spread.Sheets.Tables.TableThemes.medium7);// 获取绑定源 - 它将是 'productsTable' 数据管理器表格let bindingTable1 = table1.getBindingSource();console.log(bindingTable1 === productsTable); // 应输出 true// 方法 2：添加表格，然后使用 bind 方法绑定到数据管理器表格const table2 = spread.getActiveSheet().tables.add('Table2', 0, 0, 5, 5);table2.bind([], // 可选：指定绑定列，或传递空数组undefined, // 可选：绑定路径"products" // 指定数据管理器表格名称);// 获取绑定源 - 它也将是 'productsTable' 数据管理器表格let bindingTable2 = table2.getBindingSource();console.log(bindingTable2 === productsTable); // 应输出 true
});