actsheet v2.4.11

actsheet 使用文档

一、安装

使用包管理工具 yarn 或者 npm 安装

npm install @vgohm/actsheet -D

or

yarn add @vgohm/actsheet -D

二、使用

引入样式

import '@vgohm/actsheet/dist/css/actsheet.css';

引入脚本

import actsheet from '@vgohm/actsheet';

三、名词解释

• FSC (FoarmSpecConfig) - 表单全量配置数据
• FC (FoarmConfig) - 表单配置
• CDI (CellDataItem) - 单元格对应的数据项
• FD (FoarmData) - 表单数据
• CCI (CellConfigItem) - 单元格对应的配置项

1.FSC (FoarmSpecConfig) 格式要求

• 示例：

{
    // 数据模型
    "categories": [
        {"code": "code", "enumDefs": [], "structDefs": []}
    ],
    // 模型与表格映射关系
    "mappings": [
        {"categoryCode": "categoryCode", "sheetCode": "sheetCode", "structCode": "structCode"}
    ],
    // 配置标识
    "spec": "FOARM_SPEC_1_0",
    // 表单配置
    "foarmConfig": FC
}

2.FC (FoarmConfig) 格式要求

• 示例：

{
    "name": "001JLB8-2017",
	"code": "STD-CQD-001JLB8-2017.v0.r0",
	"version": "v0",
	"reversion": "r0",
	"hash": "a24c73a6b2b08a8a56e37faef1ad578f",
	"enable": true,
	"sheetConfigs": [
		{
			"name": "第1页",
			"code": "第1页",
			"enable": true,
			"sceneConfigs": [
				{
					"name": "P-STD-CQD-001JLB8-2017#recorder",
					"code": "P-STD-CQD-001JLB8-2017#recorder",
					"enable": true,
					"pageConfigs": [
						{
							"pageStart": 0,
							"pageEnd": 9999,
							"enable": true,
							"cellConfigItems": CCI
						}
					]
				}
		    ]
		}
	]
}

3.CCI (CellConfigItem) 格式要求

3.1 基本配置

• 字段说明

• 示例：

{
	"id": "id",
	"code": "code",
	"active": true,
	"allowedStyleProperties": "fontSize,strikeout,hAlign,vAlign",
	"readonly": false,
	"required": true,
	"target": "AI4",
	"type": "input",
	"zIndex": 0,
	"style": {},
	"options": {},
}

3.2 特殊类型 - 签章类型 (fadada_ca)

• options 字段说明

• 示例：

{
	"type": "fadada_ca"
	"options": {
		"action": "ca_sign",
		"x": 187,
		"y": 461,
		"height": 105,
		"width": 160,
		"offsetTop": 0,
		"offsetLeft": 0,
		"movable": true,
		"defaultImage": "//img-qn.51miz.com/preview/element/00/01/23/63/E-1236375-B8081CDD.jpg!/quality/90/unsharp/true/compress/true/fwfh/640x420"
	},
	...
}

3.3 特殊类型 - 复选框、单选框、删除线 (checkbox、radio、through)

• options 字段说明

• 示例：

{
	"type": "checkbox"  // 另外类型 "radio" "through"
	"options": {
		"group": "GroupName",
		"checked": true,
		"checkedData": "checkedData"
	},
	...
}

3.4 特殊类型 - 图片上传 (image)

• options 字段说明

• 示例：

{
	"type": "image"
	"options": {
		"x": 57,
		"y": 145,
		"height": 60,
		"width": 60,
		"offsetTop": 0,
		"offsetLeft": 0,
		"movable": true,
		"defaultImage": ""
	},
	...
}

4.FD (FoarmData) 格式要求

• 示例：

{
    "code": "STD-CQG-C-A-B-B",
	"reversion": "v0",
	"version": "v0",
	"sheets": [
		{
			"sheetName": "第1页",
			"sheetCode": "第1页",
			"sheetIndex": 1,
			"pages": [
				{
					"cellDataItems": CDI
				}
			]
		}
	]
}

5.CDI (CellDataItem) 格式要求

• 字段说明

• 示例：

{
	"code": "code",
	"cellDataType": "long",
	"id": "9EK1Z5QU",
	"type": "input",
	"value": "value",
	"valueDisplay": "valueDisplay",
	"style": {
		"fontSize": "12px",
		"fontColor": "#be680a",
		"backColor": "#B4D5FF"
	}
}

四、API 集合

setXlsx

• 名称：加载 Excel
• 定义：actsheet.setXlsx(blob, id, config)
• 返回：actsheet 实例

• 示例：

// 表单设计不需要加载 FSC FD
const sheet = await actsheet.setXlsx(resXlsxFile.data, 'actsheet', {
	useCellConfigType: 'admin',
	showtoolbar: false
});

// 用户使用需要加载 FSC FD
const sheet = await actsheet.setXlsx(resXlsxFile.data, 'actsheet', {
	cellValueData: FD,
	cellConfigData: FSC,
	showCustomToolBar: true
});

loadXlsx

• 名称：加载 Excel
• 定义：actsheet.loadXlsx(options, id, config)
• 返回：actsheet 实例，后续加载单元格配置和单元格数据

• 示例：

const sheet = await actsheet.loadXlsx(
	{
		url: '/template.xlsx',
		method: 'GET',
		data: {},
		headers: {},
		contentType: 'application/json',
		success: () => {
			console.log('加载成功');
		},
		error: (status, message) => {
			console.log(status, message);
		}
	},
	'actsheet',
	{ showCustomToolBar: true }
);

setCellsConfig

• 名称：加载单元格配置
• 定义：sheet.setCellsConfig(configs, { isChangeSheet = true } = {})
• 说明：使用加载单元格成功之后的返回实例，加载单元格配置

• 使用说明

1. ==异步函数（async await）==
2. ==isChangeSheet 参数单独加载配置不需要加载FD数据, 设置：false==

• 示例：

// sheet 为加载表格实例
await sheet.setCellsConfig(FSC, { isChangeSheet: false });

loadCellsConfig

• 名称：通过网络加载单元格配置
• 定义：sheet.loadCellsConfig(options, { isChangeSheet = true } = {})
• 说明：使用加载单元格成功之后的返回实例，加载单元格配置

• 示例：

// sheet 为加载表格实例
await sheet.loadCellsConfig(
    {
        url: '/CellConfigList.json'
        method: "GET",
        data: {},
        headers: {},
        contentType: "application/json",
        success: () => {
        	console.log('加载成功');
        },
        error: (status, message) => {
        	console.log(status, message);
        }
    },
    { isChangeSheet: false }
);

setData

• 名称：加载单元格数据
• 定义：sheet.setData(configs)
• 说明：使用加载单元格成功之后的返回实例，加载单元格数据

• 注意事项：

1. ==异步函数（async await）==
2. ==加载单元格数据之前，要先加载单元格配置文件==

• 示例：

// sheet 为加载表格实例
await sheet.setData(FD);

loadData

• 名称：通过网络加载单元格数据
• 定义：sheet.loadData(options)
• 说明：使用加载单元格成功之后的返回实例，加载单元格配置

• 示例：

// sheet 为加载表格实例
await sheet.loadData({
    url: '/CellDataList.json'
    method: "GET",
	data: {},
	headers: {},
	contentType: "application/json",
	success: () => {
		console.log('加载成功');
	},
	error: (status, message) => {
		console.log(status, message);
	}
});

getData

• 名称：获取数据
• 定义：sheet.getData()
• 说明：获取当前表格的填写项

• ReturnSheetsData 说明

• ReturnPagesData 说明

• 注意事项：

1. ==异步函数（async await）==
2. ==获取数据时会对表单进行验证==

• 示例：

// actsheet 引入的组件实例
const sheetData = await actsheet.getData();

saveFieldData

• 名称：保存数据
• 定义：sheet.saveFieldData(options)
• 说明：异步保存数据

• 示例：

// actsheet 引入的组件实例
const rs = await actsheet.saveFieldData({
    url: '/save'
    method: "POST",
	data: {},
	headers: {},
	contentType: "application/json",
	success: () => {
		console.log('请求成功');
	},
	error: (status, message) => {
		console.log(status, message);
	}
});

getField

• 名称：通过运行字段名称获取运行的字段对象
• 定义：sheet.getField(name)

• 示例：

// actsheet 引入的组件实例
const field = actsheet.getField('proSupEngSignDateYr');
const value = field.value;

// field 完整示例
{
    "code": "proSupEngSignDateYr",
    "cellDataType": "string",
    "id": "ZQWRCXIQ",
    "type": "input",
    "value": "2023",
    "valueDisplay": "2023",
    "active": true,
    "allowedStyleProperties": "fontSize,strikeout,hAlign,vAlign",
    "code": "proSupEngSignDateYr",
    "options": {},
    "readonly": false,
    "required": false,
    "style": {
        "backColor": "#E7E6E6",
        "bold": false,
        "fontSize": 14,
        "indent": 0,
        "italic": false,
        "shrinkToFit": false,
        "strikeout": false,
        "wordWrap": false
    },
    "target": "AR14",
    "zIndex": 0,
    "settingCellData": true
}

getFieldValue

• 名称：通过运行字段名称获取运行的字段的值
• 定义：sheet.getFieldValue(name)

• 示例：

// actsheet 引入的组件实例
const value = actsheet.getFieldValue('proSupEngSignDateYr');

setFieldValue

• 名称：通过运行字段名称设置运行字段
• 定义：sheet.getFieldValue(name, value)

• 示例：

// actsheet 引入的组件实例
actsheet.getFieldValue('proSupEngSignDateYr', '2023-11-24');

getCellValue

• 名称：获取单元格的值
• 定义：sheet.getCellValue(location)
• 说明：通过单元格位置获取 - 区别于 getFieldValue

• 示例：

// actsheet 引入的组件实例
const cellValue = actsheet.getCellValue('AR14');

setCellValue

• 名称：设置单元格的值
• 定义：sheet.setCellValue(location, value)
• 说明：通过单元格位置获取 - 区别于 setFieldValue

• 示例：

// actsheet 引入的组件实例
actsheet.setCellValue('AR14', '2023-11-14');

getCellStyle

• 名称：获取单元格样式
• 定义：sheet.getCellStyle(location)

• 示例：

// actsheet 引入的组件实例
const style = actsheet.getCellStyle('AR14');

// style
{
    "backColor": "#E7E6E6",
    "fontSize": 14,
    "fontColor": "#000000",
    "fontName": "楷体",
    "hAlign": 2,
    "vAlign": 1,
    "wordWrap": false,
    "bold": false,
    "italic": false,
    "strikeout": 0
}

setCellStyle

• 名称：设置单元格样式
• 定义：sheet.setCellStyle(location, style)

• 示例：

// actsheet 引入的组件实例
actsheet.setCellStyle('AR14', {
	backColor: '#E7E6E6',
	fontSize: 14,
	fontColor: '#000000',
	fontName: '楷体',
	hAlign: 2,
	vAlign: 1,
	wordWrap: false,
	bold: false,
	italic: false,
	strikeout: 0
});

getCellReadonly

• 名称：获取单元格只读状态
• 定义：sheet.getCellReadonly(location)

• 示例：

// actsheet 引入的组件实例
const readonly = actsheet.getCellReadonly('AR14');

// 返回值 readonly = true / false

setCellReadonly

• 名称：获取单元格只读状态
• 定义：sheet.setCellReadonly(location, value)

• 示例：

// actsheet 引入的组件实例
actsheet.setCellReadonly('AR14', true);

// true 只读不可以编辑单元格
// false 非只读可以编辑单元格

insertImage

• 名称：插入图片
• 定义：sheet.insertImage(url, location, param, cellData)

• ImageInfo

• CellInfo

• 使用说明

1. ==异步函数（async await）==

• 示例：

// actsheet 引入的组件实例
const image = await actsheet.insertImage(
	'http://picsum.photos/100',
	'B10',
	{
		width: 50,
		height: 50,
		offsetTop: 50,
		offsetLeft: 50,
		movable: true
	},
	{
		code: 'AC19'
	}
);

// image 示例
{
    "id": "img_lrstW6e6ni06_1700814051388",
    "insertImageMap": {
        "img_lrstW6e6ni06_1700814051388": {
            "id": "img_lrstW6e6ni06_1700814051388",
            "location": "P13",
            "image": {
                "type": "3",
                "src": "图片地址base64",
                "originWidth": 150,
                "originHeight": 100,
                "default": {
                    "width": 150,
                    "height": 100,
                    "left": 150,
                    "top": 450
                },
                "crop": {
                    "width": 150,
                    "height": 100,
                    "offsetLeft": 0,
                    "offsetTop": 0
                },
                "isFixedPos": false,
                "fixedLeft": 150,
                "fixedTop": 491,
                "border": {
                    "width": 0,
                    "radius": 0,
                    "style": "solid",
                    "color": "#000"
                },
                "handleType": {}
            },
            "movable": true,
            "code": "proSupEngSign",
            "cellData": {
                "code": "proSupEngSign",
                "cellDataType": "string",
                "id": "JG8CPUFY",
                "type": "fadada_ca",
                "value": "{\"action\":\"ca_sign\",\"x\":150,\"y\":450,\"height\":100,\"width\":150,\"offsetTop\":0,\"offsetLeft\":0,\"movable\":true,\"defaultImage\":\"http://picsum.photos/id/237/200/300\"}",
                "valueDisplay": {
                    "action": "ca_sign",
                    "x": 187,
                    "y": 471,
                    "height": 60,
                    "width": 134,
                    "offsetTop": 0,
                    "offsetLeft": 0,
                    "movable": true,
                    "defaultImage": "http://picsum.photos/id/237/200/300"
                },
                "active": true,
                "allowedStyleProperties": "fontSize,strikeout,hAlign,vAlign",
                "code": "proSupEngSign",
                "options": {
                    "action": "ca_sign",
                    "x": 187,
                    "y": 471,
                    "height": 60,
                    "width": 134,
                    "offsetTop": 0,
                    "offsetLeft": 0,
                    "movable": true,
                    "defaultImage": "图片地址base64"
                },
                "readonly": true,
                "required": false,
                "style": {
                    "backColor": "#E7E6E6",
                    "bold": false,
                    "fontSize": 14,
                    "indent": 0,
                    "italic": false,
                    "shrinkToFit": false,
                    "strikeout": false,
                    "wordWrap": false
                },
                "target": "P13",
                "zIndex": 1,
                "settingCellData": true
            }
        },
    }
}

deleteImage

• 名称：插入图片
• 定义：sheet.deleteImage(loaction, options = {})

• DeleteOptions

• 使用说明

1. ==异步函数（async await）==

• 示例：

// actsheet 引入的组件实例
await actsheet.deleteImage('B10');

setSheetCellStyle

• 名称：不加载单元格配置文件的时候设置单元的样式
• 定义：sheet.setSheetCellStyle(loaction, style)
• 说明：表单设计器使用 - 区别 setCellStyle

• 示例：

// actsheet 引入的组件实例
actsheet.setSheetCellStyle('B10', {
    fontSize: "14px",
    ...
});

setSheetCellValue

• 名称：不加载单元格配置文件的时候设置单元的值
• 定义：sheet.setSheetCellValue(loaction, value)
• 说明：表单设计器使用 - 区别 setCellValue

• 示例：

// actsheet 引入的组件实例
actsheet.setSheetCellValue('B10', '11111');

getSheetCellStyle

• 名称：不加载单元格配置文件的时候获取单元格样式
• 定义：sheet.getSheetCellStyle(loaction, sheetFile)
• 说明：表单设计器使用 - 区别 getCellStyle

• 示例：

// actsheet 引入的组件实例
const sheetfiles = actsheet.luckysheet.getLuckysheetfile();

sheetfiles.forEach((sheetfile) => {
	const style = actsheet.getSheetCellStyle('B10', sheetfile);
});

changeSheet

• 名称：切换 sheet
• 定义：sheet.changeSheet(order, handleType = '', options)

• 示例：

// actsheet 引入的组件实例
const sheetfiles = actsheet.luckysheet.getLuckysheetfile();

sheetfiles.forEach((sheetfile) => {
	const style = actsheet.getSheetCellStyle('B10', sheetfile);
});

附录

附录 1：ActsheetConfig

• ActsheetConfig 配置说明

{
    // 需要展示错误信息
	isErrorTip: true,
	// 轻提示配置
	toastDuration: 3000,
	// 是否锁定点击事件
	isLockClick: true,
	// 是否锁定双击点击事件
	isDBLockClick: false,
	// 是否启用自定义工具栏
	showCustomToolBar: false,
	// 图片是否移动
	isMoveImage: true,
	// 单元格的值数据
	cellValueData: {},
	// 单元格的配置数据
	cellConfigData: {},
	// 使用单元格配置方式 user | admin
	useCellConfigType: 'user',
	// 工具栏配置
	toolBarConfig: {
		fontSize: true, // 字号加减
		cancelLine: true, // 删除线
		horizontalType: true, // 水平对齐
		pages: true // 分页
	},
	// 监听外部点击事件 关闭编辑模式
	listenerOutClick: true,
	// 工具栏回调函数
	customToolBarCallback: {
		// 字号加
		fontAdd: function (data, value) {},
		// 字号减
		fontSub: function (data, value) {},
		// 删除线
		textStrikethrough: function (data, value) {},
		// 下划线
		textUnderline: function (data, value) {},
		// 文字横向
		textHorizontalAlign: function (data, value) {}
	},
	// 错误捕获的回调
	errCallback: function (err) {
		console.error(err);
	},
	// Luckysheet的原生配置 见下表
	...LuckysheetConfig
}

• Luckysheet 原生配置项

{
    column: 60, //空表格默认的列数量
    row: 84, //空表格默认的行数据量
    allowCopy: true, //是否允许拷贝
    showtoolbar: true, //是否第二列显示工具栏
    showinfobar: true, //是否显示顶部名称栏
    showsheetbar: true, //是否显示底部表格名称区域
    showstatisticBar: true, //是否显示底部计数栏
    pointEdit: false, //是否是编辑器插入表格模式
    pointEditUpdate: null, //编辑器表格更新函数
    pointEditZoom: 1, //编辑器表格编辑时缩放比例
    data: [],
    title: "Luckysheet Demo", //表格的名称
    userInfo:false,// 右上角的用户信息展示样式，支持 1. boolean类型：false:不展示，ture:展示默认 '<i style="font-size:16px;color:#ff6a00;" class="fa fa-taxi" aria-hidden="true"></i> rabbit' ，2. HTML模板字符串或者普通字符串，如：'<i style="font-size:16px;color:#ff6a00;" class="fa fa-taxi" aria-hidden="true"></i> Lucky'或者'用户名'， 3. 对象格式，设置 userImage：用户头像地址 和 userName：用户名 4. 不设置或者设置undefined同设置false
    userMenuItem: [{url:"www.baidu.com", "icon":'<i class="fa fa-folder" aria-hidden="true"></i>', "name":"我的表格"}, {url:"www.baidu.com", "icon":'<i class="fa fa-sign-out" aria-hidden="true"></i>', "name":"退出登陆"}], //点击右上角的用户信息弹出的菜单
    myFolderUrl: "www.baidu.com", //左上角<返回按钮的链接
    config: {}, //表格行高、列宽、合并单元格、公式等设置
    fullscreenmode: true, //是否全屏模式，非全屏模式下，标记框不会强制选中。
    devicePixelRatio: window.devicePixelRatio, //设备比例，比例越大表格分标率越高
    allowEdit: true, //是否允许前台编辑
    loadUrl: "", // 配置loadUrl的地址，luckysheet会通过ajax请求表格数据，默认载入status为1的sheet数据中的所有data，其余的sheet载入除data字段外的所有字段
    loadSheetUrl: "", //配置loadSheetUrl的地址，参数为gridKey（表格主键） 和 index（sheet主键合集，格式为[1,2,3]），返回的数据为sheet的data字段数据集合
    gridKey: "", // 表格唯一标识符
    updateUrl: "", //表格数据的更新地址
    updateImageUrl: "", //缩略图的更新地址
    allowUpdate: false, //是否允许编辑后的后台更新
    functionButton: "", //右上角功能按钮，例如'<button id="" class="btn btn-primary" style="padding:3px 6px;font-size: 12px;margin-right: 10px;">下载</button>    <button id="" class="btn btn-primary btn-danger" style="    padding:3px 6px;    font-size: 12px;    margin-right: 10px;">分享</button>    <button id="luckysheet-share-btn-title" class="btn btn-primary btn-danger" style="    padding:3px 6px;    font-size: 12px;    margin-right: 10px;">秀数据</button>'
    showConfigWindowResize: true, //图表和数据透视表的配置会在右侧弹出，设置弹出后表格是否会自动缩进
    enableAddRow: true,//允许添加行
    enableAddBackTop: true,//允许回到顶部
    // enablePage: false,//允许加载下一页
    autoFormatw: false,  //自动格式化超过4位数的数字为 亿万格式 例：true or "true" or "TRUE"
    accuracy: undefined,  //设置传输来的数值的精确位数，小数点后n位 传参数为数字或数字字符串，例： "0" 或 0
    pageInfo:{
        'queryExps':'',
        'reportId':'',
        'fields':'',
        'mobile':'',
        'frezon':'',
        'currentPage':'',
        "totalPage":10,
        "pageUrl":"",
    },
    editMode: false, //是否为编辑模式
    beforeCreateDom: null,//表格创建之前的方法
    fireMousedown: null, //单元格数据下钻
    lang: 'en', //language
    plugins: [], //plugins, e.g. ['chart']
    forceCalculation:false,//强制刷新公式，公式较多会有性能问题，慎用
    rowHeaderWidth: 46,
    columnHeaderHeight: 20,
    defaultColWidth:73,
    defaultRowHeight:19,
    defaultFontSize:10,
    limitSheetNameLength:true,    //是否限制工作表名的长度
    defaultSheetNameMaxLength:31,  //默认工作表名称的最大长度
    sheetFormulaBar:true, //是否显示公式栏
    showtoolbarConfig:{}, //自定义工具栏
    showsheetbarConfig:{}, //自定义底部sheet页
    showstatisticBarConfig:{}, //自定义计数栏
    cellRightClickConfig:{}, //自定义单元格右键菜单
    sheetRightClickConfig:{}, //自定义底部sheet页右击菜单
}

附录 2：Request

• 示例：

{
    url: ''
    method: "GET",
	data: {},
	headers: {},
	contentType: "application/json",
	success: () => {
		console.log('加载成功');
	},
	error: (status, message) => {
		console.log(status, message);
	}
}

附录 3：Actsheet

附录 4：事件监听

• 示例

// sheet 为加载表格之后的实例

// 单元格点击之前
sheet.listener.on('cellMousedownBefore', function ({ cell, cellName, sheetFile }) {
	console.log('cellMousedownBefore', cell, cellName, sheetFile);
});

// 单元格点击
sheet.listener.on('cellMouseClick', function ({ cell, cellName, sheetFile }) {
	console.log('cellMouseClick', cell, cellName, sheetFile);
});

// 单元格双击
sheet.listener.on('cellDblClick', function ({ cell, cellName }) {
	console.log('cellDblClick', cell, cellName);
});

// 监听下拉选择
sheet.listener.on('selectedChanged:contractPrjMgmtOrg', function (oldValue, newValue, cell) {
	console.log('selectedChanged:contractPrjMgmtOrg', oldValue, newValue, cell);
});

// 监听图片移动
sheet.listener.on('imageMoveCallback', function (data, item, imageCtrl) {
	console.log('imageMoveCallback', data, item, imageCtrl);
});

// 监听图片缩放
sheet.listener.on('imageResizeCallback', function (data, item, imageCtrl) {
	console.log('imageResizeCallback', data, item, imageCtrl);
});

// 监听图片点击
sheet.listener.on('imageMousedownCallback', function (img, imageCtrl) {
	console.log('imageMousedownCallback', img, imageCtrl);
});