前端EXCEL插件智表ZCELL数据源功能详解

news2025/5/30 18:22:57

一、数据源功能介绍

前端EXCEL插件智表ZCELL提供了强大的数据源管理功能，使开发者能够灵活地在电子表格中集成和管理结构化数据。数据源功能主要分为两种类型：

卡片式数据源：适合展示和编辑单个数据记录
表格式数据源：适合处理表格形式的多行数据

二、核心API详解

1. 创建数据源 (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);

2. 设置映射关系 (Mapping)

功能：建立数据字段与表格单元格/列的对应关系。

参数：

卡片式：cname(单元格名), field(字段名)
表格式：colname(列名), field(字段名)

示例代码：

// 卡片式映射
ds.Mapping("D23", "name"); //单元格名必须大写

// 表格式映射
ds.Mapping("G", "cn"); //列名必须大写

3. 设置列样式 (SetColumnInfo)

功能：为表格式数据源的列设置样式，新增行时会自动应用这些样式。

参数：

colname: 列名
coloption: 列样式设置对象
- cellType: 单元格类型
- cellStyle: 单元格样式
- cellBorder: 单元格边框
- cellFormat: 单元格数值格式

示例代码：

ds.SetColumnInfo("G", { 
  cellStyle: colstyle1, 
  cellBorder: border1 
});

4. 绑定数据源 (BindDataSource)

功能：将数据源对象与表页对象绑定。

示例代码：

sheet.BindDataSource(ds);

5. 获取数据源 (GetDataSource)

功能：通过名称获取已创建的数据源对象。

示例代码：

let ds1 = sheet.GetDataSource("motong");

三、数据操作功能

1. 新增数据行 (AddRow)

功能：为表格式数据源添加新行。

参数：

count: 新增行数
order: 新增顺序("asc"-尾部增加，"desc"-首行增加)

示例代码：

let ds1 = sheet.GetDataSource("person");
if (ds1 != null) {
  ds1.AddRow(2, "asc"); //在尾部新增2行
}

2. 获取变更数据

ZCELL提供了多种获取变更数据的方法：

// 获取新增行
let drows = ds1.GetInsertRows();

// 获取变更行
let drows = ds1.GetChangRows();

// 获取删除行
let drows = ds1.GetDeleteRows();

// 获取变更单元格(卡片式)
let ccs = ds1.GetChangeCells();

3. 清空变更记录 (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();