一、数据源功能介绍
前端EXCEL插件智表ZCELL提供了强大的数据源管理功能，使开发者能够灵活地在电子表格中集成和管理结构化数据。数据源功能主要分为两种类型：
卡片式数据源：适合展示和编辑单个数据记录
表格式数据源：适合处理表格形式的多行数据
二、核心API详解
- 创建数据源 (CreatDataSource)
功能：初始化数据源对象，支持卡片式和表格式两种类型。
参数：
{
name: "数据源名称", //必填
type: 0, //0-卡片式，1-表格式
data: jsondata, //数据集
// 表格式特有参数
startrow: 22, //起始行索引(从0开始)
startcol: "G", //起始列索引(从A开始)
autoBindColumn: true //是否自动绑定列(可选)
}
示例代码：
// 创建卡片式数据源
var jsondata = { name: "哪吒", age: 15, address: "陈塘关" };
let option1 = {
name: "motong",
type: 0,
data: jsondata
};
let ds = sheet.CreatDataSource(option1);
// 创建表格式数据源
var persons = [];
for (let i = 0; i < 3; i++) {
let p = {
cn: (i + 1).toString().padStart(3, "0"),
book: "西游记",
auth: "吴承恩",
name: "徒弟" + (i + 1),
operate: ""
};
persons.push(p);
}
let option = {
name: "person",
type: 1,
data: persons,
startrow: 22,
startcol: "G"
};
let ds = sheet.CreatDataSource(option);
- 设置映射关系 (Mapping)
功能：建立数据字段与表格单元格/列的对应关系。
参数：
卡片式：cname(单元格名), field(字段名)
表格式：colname(列名), field(字段名)
示例代码：
// 卡片式映射
ds.Mapping("D23", "name"); //单元格名必须大写
// 表格式映射
ds.Mapping("G", "cn"); //列名必须大写
- 设置列样式 (SetColumnInfo)
功能：为表格式数据源的列设置样式，新增行时会自动应用这些样式。
参数：
colname: 列名
coloption: 列样式设置对象
cellType: 单元格类型
cellStyle: 单元格样式
cellBorder: 单元格边框
cellFormat: 单元格数值格式
示例代码：
ds.SetColumnInfo("G", {
cellStyle: colstyle1,
cellBorder: border1
});
- 绑定数据源 (BindDataSource)
功能：将数据源对象与表页对象绑定。
示例代码：
sheet.BindDataSource(ds);
- 获取数据源 (GetDataSource)
功能：通过名称获取已创建的数据源对象。
示例代码：
let ds1 = sheet.GetDataSource("motong");
三、数据操作功能
- 新增数据行 (AddRow)
功能：为表格式数据源添加新行。
参数：
count: 新增行数
order: 新增顺序("asc"-尾部增加，"desc"-首行增加)
示例代码：
let ds1 = sheet.GetDataSource("person");
if (ds1 != null) {
ds1.AddRow(2, "asc"); //在尾部新增2行
}
- 获取变更数据
ZCELL提供了多种获取变更数据的方法：
// 获取新增行
let drows = ds1.GetInsertRows();
// 获取变更行
let drows = ds1.GetChangRows();
// 获取删除行
let drows = ds1.GetDeleteRows();
// 获取变更单元格(卡片式)
let ccs = ds1.GetChangeCells();
- 清空变更记录 (ClearChange)
功能：手工清空变更记录，标记为已提交状态。
示例代码：
let ds = sheet.GetDataSource("person");
if (ds != null) {
ds.ClearChange();
}
四、最佳实践
完整工作流程示例
// 1. 创建表格式数据源
var products = [
{ id: "001", name: "笔记本电脑", price: 5999, stock: 100 },
{ id: "002", name: "智能手机", price: 3999, stock: 150 }
];
let option = {
name: "product",
type: 1,
data: products,
startrow: 5,
startcol: "B"
};
let ds = sheet.CreatDataSource(option);
// 2. 设置列映射
ds.Mapping("B", "id");
ds.Mapping("C", "name");
ds.Mapping("D", "price");
ds.Mapping("E", "stock");
// 3. 设置列样式
let priceStyle = {
cellFormat: "¥#,##0.00",
cellStyle: { fontColor: "#FF0000", fontWeight: "bold" }
};
ds.SetColumnInfo("D", priceStyle);
// 4. 绑定数据源
sheet.BindDataSource(ds);
// 5. 添加新行
ds.AddRow(1, "asc");
// 6. 获取变更(通常在保存时调用)
let newRows = ds.GetInsertRows();
let changedRows = ds.GetChangRows();
// 7. 清空变更记录
ds.ClearChange();
五、注意事项
单元格和列名在映射时必须使用大写字母。
表格式数据源必须指定startrow和startcol参数。
新增行时会自动继承列样式设置。
变更记录只在调用ClearChange前有效。
一个表页可以绑定多个数据源。
通过本教程，您应该已经掌握了ZCELL插件数据源功能的核心使用方法。这些功能可以大大简化电子表格中的数据管理任务，特别适合需要将结构化数据与电子表格结合的应用场景。