JS API 接口文档

currentSheet

描述：当前sheet索引

getSheet

描述：获取指定下标的sheet

说明：getSheet(index)

返回值：sheet相关的api(此时不用再传sheetIndex这个参数了)

示例：

const sheet = luckySheetApi.getSheet(0);
//或const sheet = luckySheetApi.getSheet(context.currentSheet);
const val = sheet.getCellValue(7,3);

⚠️注意：getSheet返回luckySheetApi中所有sheet相关api，所以下文中列示的其他方法也都可以用这种简要写法，例子中不再枚举。

getCellValue

描述：获取单元格的值

说明：getCellValue(sheetIndex,row,column)

返回值：单元格的值（number | string ）

示例：

const cellValue = luckySheetApi.getCellValue(0,2,2);

getRangeValue

描述：获取矩形范围单元格的值

说明：getRangeValue(sheetIndex,row,column,rowCount,columnCount)

返回值：单元格的值二维数组（number | string ）

示例：

const cellValue = luckySheetApi.getRangeValue(0,2,2,2,2);  //[[1,2],[3,4]]

getCellMonitor (等同于 getCellText)

描述：获取单元格的显示文本

说明：getCellMonitor(sheetIndex,row,column)

返回值：单元格的显示文本（string）

示例：

const getCellMonitor = luckySheetApi.getCellMonitor(0,2,2);

⚠️注意：与getCellValue区别：在获取带格式的数字（比如日期、分隔符等）时，有不同表现。

setCellValue

描述：设置单元格的值

说明：setCellValue(sheetIndex,row,column,val)

返回值：无

示例：

luckySheetApi.setCellValue(0,2,2,12);

setRangeValue

描述：设置矩形范围单元格的值

说明：setRangeValue(sheetIndex,row,column,rowCount,columnCount,val)

返回值：无

示例：

luckySheetApi.setRangeValue(0,2,2,2,2,[[1,2],[3,4]]);

⚠️注意：

• 若val超过矩形范围，则超出的数据将被忽略

• 若val小于矩形范围，未覆盖的单元格将不做处理

setCellFormula

描述：设置单元格的公式

说明：setCellFormula(sheetIndex,row,column,formula)

返回值：无

示例：

luckySheetApi.setCellFormula(0,2,2,'=A1');

⚠️注意：

如果添加了大量计算公式，可在JS运行期间调用停止计算功能，以提高效率，具体见suspendCalculate

setCellValueAndMonitor

描述：同时设置单元格值和渲染在单元格中显示的文案。

说明：setCellValueAndMonitor(sheetIndex,row,column,label,value)

返回值：无

示例：

luckySheetApi.setCellValueAndMonitor(0,2,2,'SH','上海');

⚠️注意：

此API目前仅支持浮动表逻辑属性为维度，用户，值列表，自定义列表，日期的单元格。可以自行设定单元格值（如编码，用户ID）及对应显示层的内容（如名称描述，用户昵称）。其他单元格调用无效

为什么会有 v 和 m？

clearCellValue

描述：清除单元格值和公式

说明：clearCellValue(sheetIndex,row,column)

返回值：无

示例：

luckySheetApi.clearCellValue(0,2,2);

clearRangeValue

描述：清除矩形范围单元格值和公式

说明：clearRangeValue(sheetIndex,row,column,rowCount,columnCount)

返回值：无

示例：

luckySheetApi.clearRangeValue(0,2,2,2,2);

clearCellAll（待排期）

描述：清除单元格所有内容(样式，值，附加属性等)

说明：clearCellAll(sheetIndex,row,column)

返回值：无

示例：

luckySheetApi.clearCellAll(0,2,2,2,2);

⚠️注意：

此API只建议在普通底稿上使用

请谨慎使用此API在动态表，DF公式，浮动行区域中。清除所有信息后，可能会导致后续业务逻辑的异常。如数据审计，浮动表逻辑属性特殊单元格

clearRangeAll（待排期）

描述：清除矩形范围单元格所有内容(样式，值，附加属性等)

说明：clearRangeAll(sheetIndex,row,column,rowCount,columnCount)

返回值：无

示例：

luckySheetApi.clearRangeAll(0,2,2,2,2);

⚠️注意：

此API只建议在普通底稿上使用

请谨慎使用此API在动态表，DF公式，浮动行区域中。清除所有信息后，可能会导致后续业务逻辑的异常。如数据审计，浮动表逻辑属性特殊单元格

getActiveSheet

描述：获取当前激活的sheet索引

说明：getActiveSheet()

返回值: {

index: number; //sheet索引值

sheetName: string //sheet名称

}

示例：

const index = luckySheetApi.getActiveSheet();

setSheetLocked

描述：锁定sheet

说明：setSheetLocked(sheetIndex,locked)

返回值: 无

示例：

const index = luckySheetApi.setSheetLocked(0,true);

setCellExpandContract（试用）

描述：给单元格增加折叠图标。

说明：会按照参数控制行列折叠

返回值: 无

⚠️注意：对于对齐方式为水平居右的，暂时不支持

示例：

//控制2,2单元格，增加行折叠功能，默认为加号（3-10行会自动隐藏），点击后会控制第3行-第10行的折叠
luckySheetApi.setCellExpandContract(0,2,2,{
  fold: true,
  type: 'row',
  s: 3,
  e: 10
});

单元格样式相关

总览

const info = luckySheetApi.getCellStyle(0,0,0);

luckySheetApi.setCellFormatter(0,0,0,'#,##0.00');

luckySheetApi.setRangeFormatter(0,0,0,2,2,'#,##0.00');

luckySheetApi.setCellLocked(0,2,2,true);

luckySheetApi.setRangeLocked(0,2,2,4,4,true);

luckySheetApi.setCellBackgroundColor(0,2,2,'#ffffff');

luckySheetApi.setRangeBackgroundColor(0,2,2,4,4,'#ffffff');

luckySheetApi.setCellFont(0,2,2,'微软雅黑');

"微软雅黑"
"PingFangSC-Regular"
"Times New Roman"
"Arial"
"Tahoma"
"Verdana"
"宋体"
"黑体"
"楷体"
"仿宋"
"隶书"

luckySheetApi.setRangeFont(0,2,2,2,2,'微软雅黑');

luckySheetApi.setCellFontSize(0,2,2,10);

luckySheetApi.setRangeFontSize(0,2,2,4,4,10);

luckySheetApi.setCellFontColor(0,2,2,'#ffffff');

luckySheetApi.setRangeFontColor(0,2,2,4,4,'#ffffff');

// 边框类型，可选值如下：
// "border-left" 
// "border-right" 
// "border-top" 
// "border-bottom" 
// "border-all" 
// "border-none"
luckySheetApi.setCellBorder(0,2,2,'border-all','#ff0000');

// 边框类型，可选值如下：
// "border-left" 
// "border-right" 
// "border-top" 
// "border-bottom" 
// "border-all" 
// "border-none"
// "border-outside"
// "border-inside"
// "border-horizontal"
// "border-vertical"
luckySheetApi.setRangeBorder(0,2,2,2,2,'border-all','#ff0000');

luckySheetApi.setCellBold(0,2,2,true);

luckySheetApi.setRangeBold(0,2,2,2,2,true);

luckySheetApi.setCellItalic(0,2,2,true);

luckySheetApi.setRangeItalic(0,2,2,2,2,true);

luckySheetApi.setHorizontalAlign(0,0,0,'left');

luckySheetApi.setRangeHorizontalAlign(0,0,0,2,2,'left');

luckySheetApi.setVerticalAlign(0,0,0,'middle');

luckySheetApi.setRangeVerticalAlign(0,0,0,2,2,'middle');

luckySheetApi.setTextDecoration(0,0,0);

luckySheetApi.setRangeTextDecoration(0,0,0,2,2);

luckySheetApi.setCellStyle(0,0,0,{
  formatter: '#,##0.00',   //格式
	locked: true, // 锁定
	background: '#007bff', // 背景色
  font: '微软雅黑',
  fontSize: 10,
	fontColor: '#ffffff', // 字体颜色
	textDecoration: true, // 下划线
	horizontalAlign: 'center', // 水平对齐
	verticalAlign: 'middle', // 垂直对齐
  bold: true, //字体加粗
  italic: true //斜体
  textbreak: 2 //自动换行
});

luckySheetApi.setRangeStyle(0,0,0,2,2,{
  formatter: '#,##0.00',   //格式
	locked: true, // 锁定
	background: '#007bff', // 背景色
  font: '微软雅黑',
  fontSize: 10,
	fontColor: '#ffffff', // 字体颜色
	textDecoration: true, // 下划线
	horizontalAlign: 'center', // 水平对齐
	verticalAlign: 'middle', // 垂直对齐
  bold: true, //字体加粗
  italic: true //斜体
});

// 清除的属性包含字符格式，背景色，字体，字体颜色，字体大小，加粗，斜体，删除线，
// 水平对齐，垂直对齐，文本换行，下划线，缩进
luckySheetApi.clearCellStyle(0,0,0);

luckySheetApi.clearRangeStyle(0,0,0,2,2);

luckySheetApi.setCellIndent(0,0,0,2); //缩进两个单位

luckySheetApi.setRangeIndent(0,0,0,2,2,4); //缩进4个单位个数

luckySheetApi.setCellTextbreak(0,0,0,1);  //单元格设置为溢出

luckySheetApi.setRangeTextbreak(0,0,0,2,2,1); //设置单元格溢出

addMergeCells

描述：增加合并单元格

说明：addMergeCells(sheetIndex,row,column,rowCount,columnCount)

返回值：无

示例：

luckySheetApi.addMergeCells(0,2,2,3,3); // 合并的区域C3:E5

cancelMergeCells

描述：取消合并单元格

说明：cancelMergeCells(sheetIndex,row,column,rowCount,columnCount)

返回值：无

示例：

luckySheetApi.cancelMergeCells(0,2,2,3,3); // 取消合并的区域C3:E5

⚠️注意：

参数范围内的所有合并，不管是完全包含，还是有交集，都会被取消

getRowCount

描述：获取sheet的实际行数（没有数据的空白区域也算在内）

说明：getRowCount(sheetIndex)

返回值：实际行数(number)

示例：

const sheet = luckySheetApi.getSheet(0);
const rowCount = luckySheetApi.getRowCount(0);
//const rowCount = sheet.getRowCount();

getColumnCount

描述：获取sheet的实际列数（没有数据的空白区域也算在内）

说明：getColumnCount(sheetIndex)

返回值：实际列数(number)

示例：

const sheet = luckySheetApi.getSheet(0);
const columnCount = luckySheetApi.getColumnCount(0);
//const rowCount = sheet.getColumnCount();

setRowVisible

描述：设置行显示/隐藏

说明：setRowVisible(sheetIndex,row,status)

返回值：无

示例：

luckySheetApi.setRowVisible(0,1,false);

⚠️注意：

如果有很多行需要隐藏，建议使用setSpecificRowVisible，以提高性能。

setSpecifyRowVisible

描述：批量展示行

说明：setSpecifyRowVisible(sheetIndex,rows,status)

返回值：无

示例：

luckySheetApi.setSpecifyRowVisible(0，[0,1,3],true);

setColumnVisible

描述：设置列显示/隐藏

说明：setColumnVisible(sheetIndex,row,status)

返回值：无

示例：

luckySheetApi.setColumnVisible(0,1,false);

⚠️注意：

如果有很多列需要隐藏，建议使用setSpecificColumnVisible，以提高性能。

setSpecifyColumnVisible

描述：批量展示列

说明：setSpecifyColumnVisible(sheetIndex,columns,status)

返回值：

示例：

luckySheetApi.setSpecifyColumnVisible(0，[0,1,3],true);

setColumnWidth

描述：设置列宽

说明：setColumnWidth(sheetIndex,option)

返回值：无

示例：

// A列设置列宽48，B列设置自适应列宽
luckySheetApi.setColumnWidth(0,{0: 48,1: 'auto'});

setRowHeight

描述：设置列宽

说明：setRowHeight(sheetIndex,option)

返回值：无

示例：

// 第一行设置高度100px，第二行设置自适应行高
luckySheetApi.setRowHeight(0,{0: 100,1: 'auto'});

suspendDraw

描述：是否暂停渲染。

说明：suspendDraw(flag)

返回值：无

示例：

// getSheet的结果不包含此方法
luckySheetApi.suspendDraw(true);

批量更改单元格值，样式等信息时请添加suspendDraw，以提高效率

suspendCalculate

描述：是否暂停计算。

说明：suspendCalculate(flag)

返回值：无

示例：

// getSheet的结果不包含此方法
luckySheetApi.suspendCalculate(true);

批量更改单元格公式时请添加suspendCalculate，以提高效率

syncOriginData

描述：是否开始同步表格初始数据

说明：表格开表后，会将开表的原始数据记录下来，当通过Js或者用户编辑更改数据后，会与此原始数据比较，从而获得增量变化的数据。此API开关闭合期间，所有的更改操作都会直接同步原始数据，这些单元格的变化将不再视为增量变化。

返回值：无

示例：

// getSheet的结果不包含此方法
luckySheetApi.syncOriginData(true);
//dosomething like setCellValue,setCellFormula
luckySheetApi.syncOriginData(false);

tips 本API的使用场景，跟电子表格2.0的数据变更及保存相关逻辑有关，以下供参考：

1、数据是分层次的（概念理解上的层次，并不一定是技术侧分层）：

第一层（原始数据）：财务模型取数、底版数据、dfdata取数、dfdatafx计算、override覆盖

第二层：通过自定义JS修改数据

第三层：用户手工编辑

2、数据变更状态：

第1层和第2、3层之间不一样，就认为数据发生了变更（是否变更是单元格标黄及保存的前提条件）

3、标黄

如果

则单元格需要标黄。如果sheet上有标黄的单元格，刷新或关闭的时候，需要提醒。

4、数据保存

如果数据变更了，并且用户有模型侧权限，在总保存时需要将数据存储到服务端

（datafx除外，它永远都会保存）

场景举例：

1. 动态表或dfdata(wr)，用户填数了->数据变更->-标黄->保存

2. dfdatafx，引用的单元格发生了变化->数据变更->标黄对象里没他->永远保存

3. 通过JS修改可input的动态表单元格（固定值或公式）->数据变更->标黄->保存

4. 通过JS修改标题或空白区域->数据变更->不标黄->不保存

5. 通过JS修改可input的动态表单元格->通过API重置了初始状态->开表时不认为是变更->只要用户不编辑，都没变更->不标黄->不保存

6. override里右边是data或fx->除非用户手动input，否则不是变更->不标黄->不保存

~~refreshOriginData(已废弃)~~

~~描述：更新原始数据~~

~~说明：refreshOriginData(data)~~

~~返回值：无~~

~~示例：~~

// getSheet的结果不包含此方法
luckySheetApi.refreshOriginData([{
	sheetIndex: 0,
	whiteList: {
  	'2_6': 1,
  	'3_9': 1,
  }
}]);
// 如果通过js修改了luckysheet的数据，又不想被识别为变更数据，可以通过此方法更新原始数据
// 其中whiteList，blackList的key，就是行列坐标用“_”连接的字符串
// 场景1，修改了单元格2_6,3_9,4_9,whiteList传2_6,3_9,那么此时获取变更数据时，只会得到4_9;
// 场景2，修改了单元格2_6,3_9,4_9,blackList传2_6,那么此时获取变更数据时，只会得到2_6;

setFrozen

描述：设置冻结行/列

说明：setFrozen(sheetIndex,cell,type)

返回值：无

示例：

luckySheetApi.setFrozen(0,'B5',1);

getSelectedCellRange

描述：获取当前选中的单元格的坐标范围

返回值：{

hideColumn: Array

hideRow: Array

range: [{

row: [number,number];

colunm:[number,number];

}]

sheetIndex: number

}

const info = luckySheetApi.getSelectedCellRange();

setSheetZoom

描述：设置工作表缩放比例

返回值：无

luckySheetApi.setSheetZoom(0,3);

getCellInfo

描述：获取单元格信息

说明：getCellInfo(sheetIndex,row,column)

返回值：{

povDimension:Record<string,string>|undefined,

cellDimension:Record<string,string>|undefined,

isComment: boolean|undefined, //是否为批注，用于DF公式或动态表虚拟度量维

cube: {

elementName: string,

folderId: string,

path: string,

serverName: string,

…

} | undefined,

floatInfo:{

lineId: string | undefined; //新增的行，合计行，行头为undefined

tableInfo: {

tableElementName: string, //数据表元素名

folderId: string, //目录id

actualTableName: string //实际表明

} | undefined,

columnInfo: {

name: string //列名

} | undefined

} | undefined,

value: string | number,

}

示例

const info = luckySheetApi.getCellInfo(0,4,4);

modifyCellCubeAuthority

描述：修改单元格模型权限值

说明：modifyCellCubeAuthority(sheetIndex,row,column,authority)

返回值：修改结果成功或者失败(boolean)

示例：

// 如果单元格不是动态表区域单元格，也不是底稿公式单元格，结果返回为false
const result = luckySheetApi.modifyCellCubeAuthority(0,2,2,1);

以下为authority的枚举值以及解释：

addRightClickMenu

描述：增加自定义右键菜单

说明：addRightClickMenu(param)

返回值：无

示例

luckySheetApi.addRightClickMenu({
	title: '自定选项',
	onClick: (data)=>{console.log(data)},
	verify: ()=> true
})

setSheetVisible

描述：显示/隐藏 sheet

说明：setSheetVisible(sheetIndex,status)

返回值：Promise

示例

//第一张表隐藏
luckySheetApi.setSheetVisible(0,false).then(() => {
	// your code ...
})

setFilterConditions

描述：设置指定sheet内筛选区域指定列的筛选条件

说明：setFilterConditions(sheetIndex,column,condition)

返回值：无

示例

// 最后的参数type暂时只支持value
luckySheetApi.setFilterConditions(0,2,{type: 'value',value: [1,2,3]})

setActiveSheet

描述：设置激活sheet下标

说明：setActiveSheet(sheetIndex)

返回值：无

示例：

// 设置sheet2为激活sheet
luckySheetApi.setActiveSheet(1);

bindEvent

描述：单元格绑定事件

说明：bindEvent(name,func)

返回值：无

示例

// getSheet的结果不包含此方法
luckySheetApi.bindEvent('cellClick',(...params) => {
	// params会因为不同的事件，里面的数据可能也不同
	// params 参数示例如下
	// [
  // 		{
  //     	"m": "12.00",
  //     	"v": 12
  // 		},
  // 		{
  //     	"r": 3,
  //     	"c": 3
  // 		}
	// ]
});

事件参数列表

⚠️注意：

1.一个典型的错误是在cellUpdate事件中无差别的去更改单元格值，这会导致再次触发cellUpdate，最终造成程序的死循环。请在cellUpdate中增加适当的限制逻辑避免死循环的产生

2.另一个典型的错误是在刷新后重复绑定事件监听，重复绑定可能会造成严重的性能问题，为了防止事件重复绑定，可以声明一个变量来避免。代码如下

export default function(){
  //判定变量
  let isBinded = false
  function init(){
    //绑定过了就不绑了
    if(!isBinded){
      isBinded = true
      luckySheetApi.bindEvent('cellClick',(...params) => {
        //dosomething
      });
    }
  }

  return {init}
}

setCellError

描述：设置单元格错误信息（左上角红色小图标，鼠标悬浮出错误提示）

说明：setCellError(sheetIndex,row,column,content)

返回值：无

示例：

// 设置第一个sheet的A1单元格的错误信息为“测试错误信息”
luckySheetApi.setCellError(0,0,0,'测试错误信息');

clearCellError

描述：删除单元格错误信息

说明：clearCellError(sheetIndex,row,column）

返回值：无

示例：

// 删除第一个sheet的A1单元格的错误信息
luckySheetApi.clearCellError(0,0,0);

setFilterSortType

描述：设置指定sheet内筛选区域指定列的排序类型

说明：setFilterSortType(sheetIndex,column,type)

返回值：无

示例：

// 设置第1个sheet筛选区域内的A列按照升序排序
luckySheetApi.setFilterSortType(0,0,'asc');

条件格式

所有API均挂在命名空间luckySheetApi.ConditionFormat下

条件格式需要先通过实例化对应的条件，然后通过add方法到sheet中生效

const {Contain,add,CompareType} = luckySheetApi.ConditionFormat

const instance = new Contain({
  cellRange: 'A1:B2',
  condition: {
    name: CompareType.Betweenness,
    value: [5,'A10']
  },
	format: {
    textColor: '#FFC7CE'
  }
})

add(0,instance);

const {Contain,CompareType} = luckySheetApi.ConditionFormat;

const instance = new Contain({
  cellRange: 'A1:B2',
  condition: {
    name: CompareType.Betweenness,
    value: [5,'A10']
  },
	format: {
    textColor: '#FFC7CE'
  }
})

const {Formula} = luckySheetApi.ConditionFormat;

const instance = new Formula({
  cellRange: 'A1:B2',
  condition: 'A5>10',
	format: {
    cellColor: '#FFC7CE'
  }
})

const {Order} = luckySheetApi.ConditionFormat;
//前20%
const instance = new Order({
  cellRange: 'A1:B2',
  condition: {
    type: 'top',
    percent: true,
    value: 20
  },
	format: {
    textColor: '#9C0006'
    cellColor: '#FFC7CE'
  }
})

const {Average} = luckySheetApi.ConditionFormat;

const instance = new Average({
  cellRange: 'A1:B2',
  condition: 'above',
  format: {
    textColor: '#9C0006'
    cellColor: '#FFC7CE'
  }
})

const {Unique} = luckySheetApi.ConditionFormat;

const instance = new Unique({
  cellRange: 'A1:B2',
  format: {
    textColor: '#9C0006'
    cellColor: '#FFC7CE'
  }
})

const {Duplicate} = luckySheetApi.ConditionFormat;

const instance = new Duplicate({
  cellRange: 'A1:B2',
  format: {
    fontColor: '#9C0006'
    cellColor: '#FFC7CE'
  }
})

const {DataBar} = luckySheetApi.ConditionFormat;

const instance = new DataBar({
  cellRange: 'A1:B2'
  format: ['#FFC7CE']
})

const {ColorGradation} = luckySheetApi.ConditionFormat;

const instance = new ColorGradation({
  cellRange: 'A1:B2'
  format: ['#FFC7CE','#9C0006']
})