开发指南

脚本作用范围和触发事件

workbook（工作簿）

workbook作用范围是当前打开的工作簿，有新建前、新建、保存前、保存后、提交前、提交后、删除前、打印前、扫码后、页面加载后、自定义页面确认后和WebSocket这12个触发事件。

1、新建前：是指单据在新建请求发起之前执行脚本内容，此时Luckysheet表实例未创建，所有关于表格的操作都不能执行；

2、新建：是指单据在新建请求返回后，将返回后的数据在Luckysheet中渲染完成后执行脚本内容；

3、保存前：是指单据在保存请求发起前执行脚本内容；

4、保存后：是指单据在保存请求返回后执行脚本内容；

5、提交前：是指单据在提交请求发起前执行脚本内容，可以使用【submit=false】脚本来终止提交请求；

6、提交后：是指单据在提交请求返回后执行脚本内容；

7、删除前：是指单据在删除请求发送前执行脚本内容；

8、打印前：是指单据在打印命令执行前执行脚本内容；

9、扫码后：是指单据在扫码命令返回后执行脚本内容，扫码返回参数为data，可以在脚本中使用；

10、页面加载后：是指打开单据而非新建单据时请求数据返回后，将返回数据在Luckysheet中渲染完成后执行脚本内容；

11、自定义页面确认后：是指调用打开自定义页面脚本后，在自定义页面中触发确认事件后执行脚本内容；

12、WebSocket：是指单据页面加载后会自动根据websocket连接地址建立连接，在接收到后端发送的websocket消息后执行脚本内容，消息返回参数msg，可以在脚本中使用。

Sheet（工作表）

Sheet作用范围是数字表格界面底部的当前激活工作表如：sheet1，有单元格更新后、单元格批量更新后、单元格选中时、单元格单击前和公式更新后5个触发事件。

1、有单元格更新后：是指在单元格内容更新后执行脚本内容；

2、单元格批量更新后：是指在粘贴批量单元格内容后触发的单元格内容批量更新后执行，返回参数range粘贴区域，可以在脚本中使用；

3、单元格选中时：是指在单元格选中后执行脚本内容；

4、单元格单击前：是指在单元格单击事件触发前执行脚本内容，此时获取当前单元格的值还不是当前所单击的单元格；

5、公式更新后：是指在全表任何公式更新后都会执行脚本内容。

自定义按钮

自定义按钮是指在【模板设置】页签中，顶部可以配置多个自定义按钮，在模板中添加完自定义按钮并保存后就可以在脚本编辑页签的作用范围中选到指定的按钮名称，选中指定按钮名称后有请求接口返回后、单击事件、执行Node脚本前、Node脚本和执行Node脚本后5个事件。

1、请求接口返回后：是指在添加自定义按钮界面单击事件选择类型为调用接口，填写接口地址，在使用过程点击按钮会自动请求所填写的接口地址，在请求返回后执行脚本内容，返回成功后的内容参数result可以在脚本中使用；

2、单击事件：是指在添加自定义按钮界面单击事件选择类型为执行脚本，在使用过程中点击按钮后会执行脚本内容；

3、执行Node脚本前：是指在添加自定义按钮界面单击事件选择执行Node脚本，在使用过程中点击按钮后先执行该脚本内容，执行完后会调用服务器接口执行服务器上Node脚本，在脚本中可以对params进行赋值，params为object类型，例如：params={name:"张三"}，params会被传到服务器端在Node脚本中使用它。

4、Node脚本：是指脚本将被作为服务器代码执行，可以用来查询数据库数据并返回给前端，有一个前端传入参数params可以在脚本中使用；

5、执行Node脚本后：是指服务器Node脚本执行请求完成后执行的脚本内容，返回参数result是服务器脚本查询数据库的结果，可在脚本中只用；

客户端脚本开发

客户端脚本是指在浏览器上运行数字表格示例过程中执行的脚本，客户端上默认有Cells和Form两个变量分别用来操作表格和表单的相关功能。

获取当前操作单元格

使用示例 Cells.currentCell() 使用说明 该方法返回当前操作的单元格对象，获得该对象后可以使用getValue/setValue/setFillColor等方法来设置单元格属性。例如：

let cell = Cells.currentCell();
let value = cell.getValue();
console.log(value);  // 此时在控制台会打印出当前选中单元格的值

获取指定坐标单元格

使用示例 Cells.getCell(行号, 列号) 使用说明 该方法返回指定行号和列号所对应的单元格对象，它有两个参数，第一参数是行从1开始，第二个参数是列从1开始。例如：

let cell = Cells.getCell(1,1)
let value = cell.getValue();
console.log(value);  // 此时在控制台会打印出当前选中单元格的值

获取指定名称单元格

使用示例 Cells.getCell(表单字段名) 使用说明 该方法返回指定表单字段名所对应的单元格对象，传入唯一参数为表格中设置的单元格名称。例如：

let cell = Cells.getCell('员工姓名')

获取指定地址单元格

使用示例 Cells.getCellByName(单元格地址) 使用说明 该方法返回指定单元格地址所对应的单元格对象，传入唯一参数为表格中设置的单元格地址。例如：

let cell = Cells.getCellByName('A1')

获取单元格的值

使用示例 cell.getValue() 使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
let value = mycell.getValue()

该方法返回当前单元格对象的值。

获取单元格行号

使用示例 cell.getRowNumber() 使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
let r = mycell.getRowNumber()

该方法返回当前单元格对象的行号。

获取单元格列号

使用示例 cell.getColumnNumber() 使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
let c = mycell.getColumnNumber()

该方法返回当前单元格对象的列号。

获取单元格地址

使用示例 cell.getPosition() 使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
let p = mycell.getPosition()

该方法返回当前单元格对象的地址。

获取单元格所在工作簿

使用示例 cell.getSheetName() 使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
let name = mycell.getSheetName()

该方法返回当前单元格对象的工作簿名称。

设置单元格的值

使用示例 cell.setValue(单元格值, 是否刷新)

使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
mycell.setValue('内容')

该方法用来设置当前获取单元格对象的值。

设置单元格公式

使用示例 cell.setFormula(公式内容, {isRefresh:false(是否刷新),order:0(表格下标)})

使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
mycell.setFormula('公式')

该方法用来设置当前获取单元格对象的值。

设置单元格是否可编辑

单个设置单元格可编辑

使用示例 cell.setCellEditable(布尔值) 使用说明 cell是通过自己定义并使用第Cells.currentCell()、Cells.getCell(表单字段名)和Cells.getCellByName(单元格地址)方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
mycell.setCellEditable(true)

该方法用于设置当前单元格对象的可编辑状态，唯一参数取值true(可编辑)/false(不可编辑)。

批量设置单元格可编辑

使用示例 Cells.setCellsEditable(选区,布尔值)

使用说明 该方法用于设置单个选区内所有单元格的可编辑状态。该方法有两个参数，第一个是选区地址'A1:B2'，第二个参数取值为true（可编辑）/false（不可编辑）。

Cells.setCellsEditable('A1:B2',true)

设置单元格格式

设置单元格填充色

使用示例 cell.setFillColor(颜色值)

使用说明 cell是通过自己定义并使用第1、2、3个方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
mycell.setFillColor('#FF0000')

该方法用于设置当前单元格对象的填充颜色。

设置单元格边框

使用示例 Form.setBorder(选区范围,边框类型,边框粗细,边框颜色)

设置单元格字体颜色

使用示例 cell.setFontColor(颜色值)

使用说明 cell是通过自己定义并使用第1、2、3个方法获取到的单元格对象，名字可以自定义例如:

let mycell = Cells.currentCell()
mycell.setFontColor('#FF0000')

该方法用于设置当前单元格对象的字体颜色。

其他格式设置参数

其他格式设置需要使用luckysheet.setCellFormat(row, column, attr, value [,setting])方法来实现

属性名 attr 列表如下：

比如设置A1单元格的格式为百分比格式：

luckysheet.setCellFormat(0, 0, "ct", {fa:"0.00%", t:"n"})

设置当前工作表A1单元格文本加粗：

luckysheet.setCellFormat(0, 0, "bl", 1)

获取当前表单参数

使用示例 Form.getEnvParam(表单参数名)

使用说明 该方法返回当前表单的表单参数值，表单参数是模板配置中头部添加并设置为顶部显示的参数，该参数在新建表单的弹窗中供用户输入参数值。例如：

let name = Form.getEnvParam('员工姓名')

获取当前表单表头数据

使用示例 Form.getBillData(表头名称)

使用说明 该方法返回当前表单的表头数据值，传入表头的名称可以返回表头对应的值。例如：

let name = Form.getBillData('创建人')

获取关联表格属性字段值

使用示例 Form.getRelatedData(关联表单名，字段名称)

使用说明 该方法返回指定的关联表单属性中指定的字段值，有两个参数，第一个参数为基础属性中设置的属性类型为关联表单的属性名称，第二的参数为关联表单中包含的其中一个字段名称。例如：

let name = Form.getRelatedData('小样记录单','员工姓名')

根据条件查找基础资料数据

使用示例 Form.findBaseData(路径, 条件)

使用说明 该方法返回符合条件的基础资料数据行，有两个参数，第一个参数为基础资料中sheet页名称，前面加上./，第二个参数为筛选条件以多个健值对的形式组合成一个Object，例如：

Form.findBaseData('./员工信息',{'员工姓名':'张三','员工性别':'男'})

根据条件查找通用资料数据

使用示例 Form.findBaseData(路径, 条件)

使用说明 该方法返回符合条件的通用资料数据行，有两个参数，第一个参数为通用资料路径'通用资料名称/sheet页名称'，第二个参数为筛选条件以多个健值对的形式组合成一个Object，例如：

let baseData =await Form.findBaseData('组织机构信息/员工信息',{'员工姓名':'张三'})

获取当前登录用户ID

let userId = getUserId()

获取浏览器地址栏参数

let attr = getQueryString(attr)

设置脚本开启/关闭

使用示例 Form.enableEvents(是否启用)

使用说明 该方法是在执行脚本过程中不希望再次触发该脚本或其他脚本。

Form.EnableEvents = true

获取满足条件的数字表格列表

使用示例 let formList = await Form.getFormList(条件,[表单名称])

使用说明

let formList = await Form.getFormList({'单据编号':'B20230403'})

返回内容

{
    "errcode":0,
    "errmsg":"",
    "content":[{
        "BillId": "B20230403",
        "BillState": "已创建",
        "BillCreatedDate": "2023-04-25",
        "BillCreatedTime": "11:07:26",
        "BillCreatedBy": "admin",
        "BillModifiedDate": "2023-04-25",
        "BillModifiedTime": "11:09:22",
        "BillModifiedBy": "admin",
        "34c4f68b-8df7-4130-b4af-02f58145a3e1": "",
        "formInstanceId": "253e1ed7-7938-4000-81f9-a561a2a30a93",
        "version": "1682386342060"
    }]
}

根据数字表格列表获取数据

使用示例 Form.getFormData(单据列表或单据)

使用说明

let formData = await Form.getFormData({
        "BillId": "B20230403",
        "BillState": "已创建",
        "BillCreatedDate": "2023-04-25",
        "BillCreatedTime": "11:07:26",
        "BillCreatedBy": "admin",
        "BillModifiedDate": "2023-04-25",
        "BillModifiedTime": "11:09:22",
        "BillModifiedBy": "admin",
        "34c4f68b-8df7-4130-b4af-02f58145a3e1": "",
        "formInstanceId": "253e1ed7-7938-4000-81f9-a561a2a30a93",
        "version": "1682386342060"
    })

或

let formData = await Form.getFormData([{
        "BillId": "B20230403",
        "BillState": "已创建",
        "BillCreatedDate": "2023-04-25",
        "BillCreatedTime": "11:07:26",
        "BillCreatedBy": "admin",
        "BillModifiedDate": "2023-04-25",
        "BillModifiedTime": "11:09:22",
        "BillModifiedBy": "admin",
        "34c4f68b-8df7-4130-b4af-02f58145a3e1": "",
        "formInstanceId": "253e1ed7-7938-4000-81f9-a561a2a30a93",
        "version": "1682386342060"
    },{
        "BillId": "B20230405",
        "BillState": "已创建",
        "BillCreatedDate": "2023-04-25",
        "BillCreatedTime": "11:07:26",
        "BillCreatedBy": "admin",
        "BillModifiedDate": "2023-04-25",
        "BillModifiedTime": "11:09:22",
        "BillModifiedBy": "admin",
        "34c4f68b-8df7-4130-b4af-02f58145a3e2": "",
        "formInstanceId": "253e1ed7-7938-4000-81f9-a561a2a30a95",
        "version": "1682386342060"
    }])

返回结果：

{
    "errcode": 0,
    "errmsg": "",
    "content": [
        {
            "formInstanceId": "717a1b3c-b22a-45ab-84c1-b1786b347a2a",
            "version": "1744591256031",
            "提交时间": "",
            "状态": "已创建",
            "提交人": "",
            "审核人": "",
            "审核日期": "",
            "审核时间": "",
            "修改时间": "08:41:16",
            "修改人": "admin",
            "创建时间": "08:41:14",
            "创建日期": "2025-04-14",
            "创建人": "admin",
            "修改日期": "2025-04-14",
            "单据编号": "B20250401",
            "提交日期": "",
            "小数": 0,
            "是否": false,
            "AAAA": "1",
            "BBBB": "2",
            "CCCC": "3"
        }
    ]
}

获取数字表格的DS数据

使用示例 Form.queryFormData(表单名称,版本号,{筛选条件})

使用说明 该方法返回符合条件的表单数据，该方法为异步请求需要在方法前加await来进行同步，该方法有三个参数，第一个参数为表单名称，第二个参数为版本号值为''空时表示当前版本，第三个参数为筛选条件以多个健值对的形式组合成一个Object，该方法返回一个DS结构的数据，例如：

let formData = await Form.queryFormData('成品出库单','',{})

返回结果：

{
    "errcode": 0,
    "errmsg": "",
    "content": {
        "dataTables": [
            {
                "schema": {
                    "columns": [
                        {
                            "visible": true,
                            "displayLength": 20,
                            "name": "formId",
                            "label": "表单Id",
                            "alignment": "Left",
                            "type": "String",
                            "stringSize": 50
                        },
                        {
                            "visible": true,
                            "displayLength": 20,
                            "name": "formVersion",
                            "label": "表单版本",
                            "alignment": "Left",
                            "type": "String",
                            "stringSize": 50
                        },
                        {
                            "visible": true,
                            "displayLength": 20,
                            "name": "formInstanceId",
                            "label": "表单实例",
                            "alignment": "Left",
                            "type": "String",
                            "stringSize": 50
                        },
                        {
                            "visible": true,
                            "displayLength": 20,
                            "name": "单据编号",
                            "label": "单据编号",
                            "alignment": "Left",
                            "type": "String",
                            "stringSize": 50
                        }
                    ],
                    "name": "成品出库单",
                    "id": "2f50d30e-69d5-44f7-b8d2-fb9d26ca310e",
                    "label": "成品出库单",
                    "type": "General"
                },
                "data": []
            },
            {
                "schema": {
                    "columns": [
                        {
                            "visible": true,
                            "displayLength": 20,
                            "name": "formInstanceId",
                            "label": "表单实例",
                            "alignment": "Left",
                            "type": "String",
                            "stringSize": 50
                        },
                        {
                            "visible": true,
                            "displayLength": 20,
                            "name": "商品名称",
                            "label": "商品名称",
                            "alignment": "Left",
                            "type": "String",
                            "stringSize": 100
                        },
                        {
                            "visible": true,
                            "displayLength": 20,
                            "name": "规格",
                            "label": "规格",
                            "alignment": "Left",
                            "type": "String",
                            "stringSize": 100
                        }
                    ],
                    "name": "明细行",
                    "id": "1b9a9e14-6f73-4a0a-a2dc-856b952cf836",
                    "label": "明细行",
                    "type": "General"
                },
                "data": []
            }
        ],
        "id": "0040267b-6ff0-4322-b580-d8de27373f26"
    }
}

获取数字表格的明细行数据

使用示例： Form.getDetailData(明细表名称, [列名1, 列名2])

使用说明：

let detailData = await Form.getDetailData('自定义1', ['员工编号', '员工姓名'])

返回结果：

[
    {
        "员工编号": "1001",
        "员工姓名": "张三"
    },
    {
        "员工编号": "1002",
        "员工姓名": "李四"
    },
    {
        "员工编号": "1003",
        "员工姓名": "王五"
    }
]

获取表格中选中区域的数据

使用示例 Form.getValueOfRange() 说明：该方法返回选中区域的数据，数据以数组形式返回，支持返回多个选区。

返回结果：

[
    [
        "aa",
        "bb",
        "cc"
    ],
    [
        "1",
        "2",
        "3"
    ]
]

获取数据弹窗中选中的数据

使用示例 Form.getSelectObject() 说明：通过该方法可以拿到最近一次数据弹窗选择返回的数据行。

返回结果：

{
    "员工姓名":"张三",
    "员工编号":"1001"
}

请求自定义接口

使用示例 Form.createAjax(请求地址, {请求参数}, 请求方式)

使用说明

let result = await Form.createAjax("/web/test",{})

获取contextMap中的参数

使用示例 getContextMap(键的名称)

保存当前表单

// 使用示例
Form.save()

提交当前表单

// 使用示例
Form.submit()

取消提交表单

// 使用示例
Form.cancelSubmit()

审核当前表单

// 使用示例
Form.check();
Form.check(url='/web/apps/customCheck');
Form.check(url='/web/apps/customCheck','2405c217-9a1f-4568-972c-b2bbe2e5c2ce')

取消审核表单

// 使用示例
Form.cancelCheck('2405c217-9a1f-4568-972c-b2bbe2e5c2ce');

删除当前表单

// 使用示例
Form.deleteForm()

保存表单数据到历史记录

// 使用示例
Form.saveHistory(特征)
// 特征参数说明：自定义字符串，用于标记当前保存的历史记录是哪个操作产生的

打开自定义弹窗

使用示例 Form.openSelect(是否多选, 列配置, 数据行, 回调方法)

使用说明

let columns = [
    {
        "label":"员工姓名",
        "prop":"userId",
        "width":"100"
    },
    {
        "label":"员工姓名",
        "prop":"userName"
    }
];
let data = [
    {
        "userId":"1001",
        "userName":"张三"
    },
    {
        "userId":"1002",
        "userName":"李四"
    }
];
Form.openSelect(false, columns, data, (res)=>{console.log(res)})

打开自定义页面

使用示例 Form.openHTML(自定义页面路径, 页面标题)

使用说明

Form.openHTML("https://www.baidu.com/","百度")

隐藏指定Sheet页

// 使用示例
// Form.setSheetHide(Sheet页下标)
Form.setSheetHide(0)

设置二维码到指定单元格

使用示例 Form.setQRCode(行号, 列号, 码号, {order:工作表下标, margin:二维码边距, endRow:结束行号, endCol:结束列号})

使用说明

Form.setQRCode(1, 1, "wlbh0001", {order:0, margin:1, endRow:3, endCol:3})

获取表单formInstanceId

// 使用示例
let formInstanceId = Form.formInstanceId

通过OS系统文件ID运行JS脚本

使用示例 runJS(文件ID, 参数)

服务端脚本开发

服务端脚本是在服务器上运行的脚本，主要用于操作数据库查询数据

创建数据库连接

使用示例 let myquery = await sys().getDAO('物料域')

使用说明 该方法用于创建数据库连接得到一个连接对象，只能在服务器端运行，方法可以传入一个参数域的名称如'物料域'，不传参数默认连接综合域，例如：

let myquery1 = await sys().getDAO()
let myquery2 = await sys().getDAO('物料域')

查询数据表唯一记录

使用示例 let myquery = await myquery.findUniqueResult(sql)或queryUniqueResult(sql)

使用说明 该方法用于查询数据库中数据表的数据，只能在服务器端运行，方法可以传入两个参数，第一个参数为sql查询字符串，第二个参数是一个数组用于表达sql查询字符串的占位符,如果sql查询字符串没有使用占位符第二个参数可以省略，例如：

let myquery = await sys().getDAO()
let sql = 'SELECT * FROM SysUser WHERE userId=?'
let myResult1 = await myquery.findUniqueResult(sql,[1])
let myResult2 = await myquery.queryUniqueResult('SELECT * FROM SysUser WHERE id=1')

查询数据表记录列表

使用示例 let myquery = await myquery.queryList(sql)

使用说明 该方法用于查询数据库中数据表的数据，只能在服务器端运行，方法可以传入两个参数，第一个参数为sql查询字符串，第二个参数是一个数组用于表达sql查询字符串的占位符,如果sql查询字符串没有使用占位符第二个参数可以省略，例如：

let myquery = sys().getDAO()
let myResult1 = await myquery.queryList('SELECT * FROM SysUser WHERE age=?',[20])
let myResult2 = await myquery.queryList('SELECT * FROM SysUser WHERE age=20')

根据条件查询数字表格数据

使用示例 let myquery = await queryFormData('表单名称','',{})

参数参考客户端脚本queryFormData方法

使用说明 该方法返回符合条件的表单数据，只能在服务器端运行，该方法为异步请求需要在方法前加await来进行同步，该方法有三个参数，第一个参数为表单名称，第二个参数为版本号值为''空时表示当前版本，第三个参数为筛选条件以多个健值对的形式组合成一个Object，该方法返回一个DS结构的数据，例如：

let formData = await queryFormData('成型报单','',{})