小智报表开发文档
小智报表简介
小智报表是一款纯原生js 构建的智能电子表格，旨在帮助产品高效解决报表问题。小智报表分为设计器端与展示端。
小智报表设计器
1.SDK的下载与嵌入
SDK已经是编译过的文件，在webpack和vite等项目中无需再次编译。将开发包库文件放入项目目录下。引入 XZReportDesigner/xzreportdesigner.js , 可访问全局变量 window.XZReportDesigner。
1.1 SDK获取
开发包文件，可以在小智官网进行下载：https://tizdata.com/xzdownload
1.2 嵌入
因为是原生js构建，所以说和框架无关。可以在vue ,react等任意框架中使用。
开发文件XZReportDesigner/xzreportdesigner.js 引入后, 可访问全局变量 window.XZReportDesigner。在调用设计器XZReportDesigner时，需先调XZReportDesigner.setKey(授权码)方法，使用授权码。小智报表设计器需要一个dom元素来实现画布的初始化，小智报表在初始化方法中有一个option字段，我们通过该option字段来对设计器进行参数设置，其它更多的参数请查看注释里的说明。
实例化XZReportDesigner后就可以在dom中看到设计器了，到此已嵌入成功。
1.2.1 原生js嵌入示例
<div id="chartContainer" style="width:100%;height:100%;"></div>
import "./XZReportDesigner/xzreportdesigner.js";
import "./XZReportDesigner/xzreportdesigner.css";
// options 可选项 设计器配置项
let option = {}
// 绑定授权码
XZReportDesigner.setKey(授权码)
//调用设计器
const sheetDesigner = XZReportDesigner("#container",option);
/*
option = { //参数配置说明 根据您的需求填写option
row：100， number 自定义行数
col:50, number 自定义列数
width function 返回值类型是 number 自定义宽度
height function 返回值类型是 number 自定义高度
onUpdateDatasetList function 返回值是一个promise 外部数据集列表
dataset:[ //数据集按钮的方式 如果不传该字段时，数据集支持默认的外部数据集数据 里面的value值可以随意更改
{
id: 1,
value: "新建Json数据集"
},
{
id: 2,
value: "新建Http接口数据集"
},
{
id: 3,
value: "API服务数据集"
},
{
id: 4,
value: "外部数据集"
}
]}
*/
Vue嵌入示例 （ 以vue 3 为例 ）
<template>
<div id="container" style="width: 100%; height: 100%"></div>
</template>
<script setup>
import { ref, onMounted } from 'vue';
import "@/assets/XZReportDesigner/xzreportdesigner.js";
import "@/assets/XZReportDesigner/xzreportdesigner.css";
let sheetDesigner = null;
onMounted( () => {
let option = {}
sheetDesigner = XZReportDesigner("#container",option);
});
React嵌入示例 ( 以React 16 为例)
import React, { useEffect } from 'react';
import "@/assets/XZReportDesigner/xzreportdesigner.js";
import "@/assets/XZReportDesigner/xzreportdesigner.css";
const example = props => {
let sheetDesigner = null;
useEffect(() => {
let option = {}
sheetDesigner = XZReportDesigner("#container",option);
}, []);
return (
<div id="container" ></div>
);
}
结果
报表设计器
数据来源部分
数据来源目前支持选择Json数据、http请求数据、API服务数据、外部数据 四种数据集类型。可在小智报表初始化方法时设置option字段来选择数据集的可选择方式。
以Json数据为示例来演示
let option = {
dataset:[ //数据集按钮的方式
{
id: 1,
value: "新建Json数据集"
},
{
id: 2,
value: "新建Http接口数据集"
},
{
id: 3,
value: "API服务数据集"
},
{
id: 4,
value: "外部数据集"
}
]
}
点击确定按钮后，该数据会出现 添加数据集 按钮下方列表中。
可以支持接收外部数据。在小智报表初始化方法时设置option中的onUpdateDatasetList来实现接收外部数据。
// 第三方数据集列表
// 该方法的返回值是一个Promise
const onUpdateDatasetList = ()=>{
return new Promise((resolve, reject)=>{
// resolve的数据格式
let results = [
{
name:"数据表名称",
id:"数据表id",
columns:[], // 数据表中字段 字段的数据结构 {name:"字段名称",data_type:"字段类型"} data_type => 1日期 2数字 3字符串
params:[], // 数据表中参数 参数耳朵数据结构 {name:"参数名称",data_type:"参数类型"} data_type => 1日期 2数字 3字符串
}
]
resolve(results)
})
}
let option = {
onUpdateDatasetList
}
如果需要编辑外部数据集 需要监听dataset-edited事件
// 监听 编辑数据集事件
sheetDesign.on("dataset-edited",(dataset)=>{
//dataset 被编辑数据集的配置
})
报表设计器的保存与回显
报表设计器的数据保存
报表设计器暴露了保存的方法，在编辑完报表设计器时可以调用getData事件拿到设计器的全部数据。用于展示端的使用或回显设计器进行再次的设计。
// config 为报表配置 ， data为 数据配置
const {config,data} = sheetDesign.getData(); //报表设计器的保存事件
报表设计器的数据回显
在调用报表设计器保存方法后拿到的数据，可在调用loadData方法实现数据的回显。
sheetDesign.loadData({config:config,data:data});
小智报表展示端
展示端SDK的下载与嵌入
XZReport/xzreport.js , 可访问全局变量 window.XZReport。可将小智报表设计器端创建的报表展示出来。
SDK获取
开发包文件，可以在小智官网进行下载：https://tizdata.com/xzdownload
嵌入
因为是原生js构建，所以说和框架无关。可以在vue ,react等任意框架中使用。
开发文件XZReport/xzreport.js 引入后, 可访问全局变量 window.XZReport。在调用设计器XZReport时，需先调XZReport.setKey(授权码)方法，使用授权码。小智报表展示端需要一个dom元素来实现初始化，小智报表在初始化方法中有一个option字段，我们通过该option字段来对设计器进行参数设置，其它更多的参数请查看注释里的说明。
初始化之前，我们需要先准备一些控件属性、数据和报表配置 （以json数据为例）
const options = {
view: {
width: () => document.documentElement.clientWidth, //设置宽度 function 返回值为number
height: () => document.documentElement.clientHeight //设置高度 function 返回值为number
},
renderArrow:false, // 是否显式 扩展方向图标
showFreeze:false, // 是否显式冻结线
showGrid:false // 是否显式网格线
};
// 现在报表里数据配置分为3种 type 1 json数据 3API服务 4 接入的外部数据集
// API服务的配置是已经存在报表配置信息中的
// json 数据需要初始化控件的时候传入 或者使用 update方法更新
const data = [{
name: "test",
response_data: [{
"商品": "A产品",
"季度": 1,
"销售额": 5890.56
}, {
"商品": "A产品",
"季度": 2,
"销售额": 4566.26
}, {
"商品": "A产品",
"季度": 3,
"销售额": 7861.56
}, {
"商品": "A产品",
"季度": 4,
"销售额": 5654.56
}, {
"商品": "A产品",
"季度": 1,
"销售额": 5820.96
}, {
"商品": "A产品",
"季度": 2,
"销售额": 5666.26
}, {
"商品": "A产品",
"季度": 3,
"销售额": 8661.56
}, {
"商品": "A产品",
"季度": 4,
"销售额": 5254.56
}, {
"商品": "B产品",
"季度": 1,
"销售额": 5890.56
}, {
"商品": "B产品",
"季度": 2,
"销售额": 4456.16
}, {
"商品": "B产品",
"季度": 3,
"销售额": 7561.56
}, {
"商品": "B产品",
"季度": 4,
"销售额": 3554.56
}, {
"商品": "B产品",
"季度": 1,
"销售额": 4620.96
}, {
"商品": "B产品",
"季度": 2,
"销售额": 5456.26
}, {
"商品": "B产品",
"季度": 3,
"销售额": 8891.56
}, {
"商品": "B产品",
"季度": 4,
"销售额": 5623
}, {
"商品": "C产品",
"季度": 1,
"销售额": 4600.78
}, {
"商品": "C产品",
"季度": 2,
"销售额": 5246
}, {
"商品": "C产品",
"季度": 3,
"销售额": 7761.56
}, {
"商品": "C产品",
"季度": 4,
"销售额": 8164
}, {
"商品": "C产品",
"季度": 1,
"销售额": 4645.56
}, {
"商品": "C产品",
"季度": 2,
"销售额": 6579
}, {
"商品": "C产品",
"季度": 3,
"销售额": 7591.56
}, {
"商品": "C产品",
"季度": 4,
"销售额": 7168
}, {
"商品": "D产品",
"季度": 1,
"销售额": 4678.56
}, {
"商品": "D产品",
"季度": 2,
"销售额": 6659
}, {
"商品": "D产品",
"季度": 3,
"销售额": 7567.56
}, {
"商品": "D产品",
"季度": 4,
"销售额": 7498
}, {
"商品": "D产品",
"季度": 1,
"销售额": 5246
}, {
"商品": "D产品",
"季度": 2,
"销售额": 4645
}, {
"商品": "D产品",
"季度": 3,
"销售额": 7561.8
}, {
"商品": "D产品",
"季度": 4,
"销售额": 7941
}],
type:1 // 1 json 数据 3 api服务
}]
const sheetConfig = [{
"name": "sheet1",
"SheetData": {
"freeze": "A1",
"columnHead": [{
"Column": 0
}, {
"Column": 1
}, {
"Column": 2
}],
"rowHead": [{
"Row": 0
}, {
"Row": 1
}, {
"Row": 2
}],
"dataConfig":[],
"apiConfig":[],
"paramsConfig":[],
"stylesConfig": [{
"border": {
"bottom": ["thin", "#666"],
"top": ["thin", "#666"],
"left": ["thin", "#666"],
"right": ["thin", "#666"]
}
}, {
"align": "center",
"valign": "middle"
}, {
"border": {
"bottom": ["thin", "#666"],
"top": ["thin", "#666"],
"left": ["thin", "#666"],
"right": ["thin", "#666"]
},
"align": "center"
}, {
"align": "center"
}, {
"align": "center",
"valign": "middle",
"border": {
"bottom": ["thin", "#666"],
"top": ["thin", "#666"],
"left": ["thin", "#666"],
"right": ["thin", "#666"]
}
}, {
"border": {
"bottom": ["thin", "#666"],
"top": ["thin", "#666"],
"left": ["thin", "#666"],
"right": ["thin", "#666"]
},
"align": "left"
}, {
"border": {
"bottom": ["thin", "#666"],
"top": ["thin", "#666"],
"left": ["thin", "#666"],
"right": ["thin", "#666"]
},
"align": "center",
"bgcolor": "#01B0F1"
}, {
"border": {
"bottom": ["thin", "#666"],
"top": ["thin", "#666"],
"left": ["thin", "#666"],
"right": ["thin", "#666"]
},
"align": "center",
"bgcolor": "#93D051"
}, {
"border": {
"bottom": ["thin", "#666"],
"top": ["thin", "#666"],
"left": ["thin", "#666"],
"right": ["thin", "#666"]
},
"align": "center",
"bgcolor": "#FFC001"
}],
"cellConfig": [{
"column": 0,
"row": 0,
"value": "",
"styleIndex": 5,
"editable": true,
"slash": {
"text": "商品|季度",
"type": 0,
"lineStyle": "thin",
"lineColor": "#000"
},
"dataConfig": {}
}, {
"column": 1,
"row": 0,
"value": "test.商品",
"valueType": 1,
"expansion": 2,
"styleIndex": 2,
"editable": false,
"scaleType": 1,
"dataConfig": {
"value": "test.商品",
"data_type": "3",
"merge": 1,
"axisType": 1,
"order": 0
},
"type": 2,
"dataType": "3"
}, {
"column": 2,
"row": 0,
"value": "合计",
"styleIndex": 6,
"type": 6
}, {
"column": 0,
"row": 1,
"value": "test.季度",
"valueType": 1,
"expansion": 1,
"styleIndex": 2,
"editable": false,
"scaleType": 1,
"dataConfig": {
"value": "test.季度",
"data_type": "2",
"axisType": 1,
"order": 0,
"merge": 1
},
"type": 2,
"dataType": "2"
}, {
"column": 1,
"row": 1,
"value": "test.销售额",
"valueType": 1,
"expansion": 3,
"styleIndex": 2,
"editable": false,
"scaleType": 1,
"dataConfig": {
"value": "test.销售额",
"data_type": "2",
"aggregate": 1,
"axisType": 2,
"order": 0
},
"type": 2,
"dataType": "2"
}, {
"column": 2,
"row": 1,
"value": "=SUM(B2)",
"styleIndex": 6,
"type": 5
}, {
"column": 0,
"row": 2,
"value": "合计",
"styleIndex": 7,
"type": 6
}, {
"column": 1,
"row": 2,
"value": "=SUM(B2)",
"styleIndex": 7,
"warn": [{
"name": "条件1",
"act_on": 1,
"cond_str": "((字段：test.商品) 不为空 )",
"filter": {
"logic": 1,
"params": [{
"logic": 1,
"params": [{
"column": "0:1",
"data_type": 3,
"logic": 1,
"type": 8,
"value": "",
"cname": "test.商品",
"is_req": false
}]
}]
},
"style_str": "小数位：2位； ",
"stylesConfig": {
"format": {
"decimal": 2
}
}
}],
"type": 5
}, {
"column": 2,
"row": 2,
"value": "=SUM(B2)",
"styleIndex": 8,
"warn": [{
"name": "条件1",
"act_on": 1,
"cond_str": "((字段：test.商品) 不为空 )",
"filter": {
"logic": 1,
"params": [{
"logic": 1,
"params": [{
"column": "0:1",
"data_type": 3,
"logic": 1,
"type": 8,
"value": "",
"cname": "test.商品",
"is_req": false
}]
}]
},
"style_str": "小数位：2位； ",
"stylesConfig": {
"format": {
"decimal": 2
}
}
}],
"type": 5
}],
"groupConfig": [{
"label": "A1-C3",
"children": [{
"label": "A2-C3",
"children": [{
"label": "A2-B3",
"borderColor": "rgba(255, 115, 191)",
"bgColor": "rgba(255, 115, 191,0.5)",
"noagg": false,
"no_agg": false,
"repeat": {
"isRepeat": false,
"repeatKey": "",
"repeatValue": ""
},
"position": "A2:B3"
}],
"borderColor": "rgba(115, 187, 255)",
"bgColor": "rgba(115, 187, 255,0.5)",
"noagg": false,
"no_agg": false,
"repeat": {
"isRepeat": false,
"repeatKey": "",
"repeatValue": ""
},
"position": "A2:C3"
}],
"borderColor": "rgba(94, 255, 215)",
"bgColor": "rgba(94, 255, 215,0.5)",
"noagg": false,
"no_agg": false,
"repeat": {
"isRepeat": false,
"repeatKey": "",
"repeatValue": ""
},
"position": "A1:C3"
}],
"collapse": [],
"toolbarButtonList": [{
"showIcon": true,
"showText": true,
"text": "首页",
"icon": "fa fa-step-backward",
"color": "#2c3e50",
"show": true,
"type": 1
}, {
"showIcon": true,
"showText": true,
"text": "上一页",
"icon": "xzreport-icon-arrow-left-filling",
"color": "#2c3e50",
"show": true,
"type": 2
}, {
"showIcon": true,
"showText": true,
"text": "当前页/总页数",
"icon": "",
"color": "#2c3e50",
"show": true,
"type": 3
}, {
"showIcon": true,
"showText": true,
"text": "下一页",
"icon": "xzreport-icon-arrow-right-filling",
"color": "#2c3e50",
"show": true,
"type": 4
}, {
"showIcon": true,
"showText": true,
"text": "末页",
"icon": "fa fa-step-forward",
"color": "#2c3e50",
"show": true,
"type": 5
}, {
"showIcon": true,
"showText": true,
"text": "打印",
"color": "#2c3e50",
"icon": "fa fa-print",
"show": true,
"type": 6
}, {
"showIcon": true,
"showText": true,
"text": "导出",
"icon": "fa fa-download",
"color": "#2c3e50",
"show": true,
"type": 7
}]
}
}]
原生js嵌入示例
<div id="chartContainer"></div>
import "./XZReport/xzreport.js";
import "./XZReport/xzreport.css";
XZReport.setKey(授权码)
// options控件的配置项 sheetConfig 报表信息 data数据
const sheet = XZReport("#container", options,sheetConfig,data);
// 配置改变时 需要使用 update 方法更新 sheetConfig,data 都是可选参数
//spreadSheet.update(sheetConfig?,data?)
Vue嵌入示例 （ 以vue 3 为例 ）
<template>
<div id="container" style="width: 100%; height: 100%"></div>
</template>
<script setup>
import { ref, onMounted } from 'vue';
import "@/assets/XZReport/xzreport.js";
import "@/assets/XZReport/xzreport.css";
let sheet = null;
onMounted( () => {
sheet = XZReport("#container", options,sheetConfig,data);
});
React嵌入示例 ( 以React 16 为例)
import React, { useEffect } from 'react';
import "@/assets/XZReport/xzreport.js";
import "@/assets/XZReport/xzreport.css";
const example = props => {
let sheet = null;
useEffect(() => {
sheet = XZReport("#container", options,sheetConfig,data);
}, []);
return (
<div id="container" ></div>
);
}
结果
展示端外部数据回调事件
需要外部传入数据时应该在表格配置项 options 中配置 onUpdateData
注意！ 只有报表配置了外部数据集时才会触发此方法 （外部数据集：类型为4的数据集）
options.onUpdateData = onUpdateData
// 获取数据表数据
// datasets => [{name:"数据表名称",id:"数据表id"...}] 参与获取数据的数据集
// params => [{name:"参数名称",value:"参数值"}] value的类型是字符串或者数组
// 该方法的返回值是一个Promise
const onUpdateData = (datasets,params)=>{
return new Promise((resolve, reject)=>{
// resolve的数据格式
let results = [
{
name:"数据表名称",
response_data:[] // 支持两种数据格式 1.{columns:[a,b],data:[[1,2]]} 2. [{a:1,b:2}]
}
]
resolve(results)
})
}
展示端打印功能方案
帮助产品快速获得 按格式套打、按模板打印、按显示打印、按列表一键批量打印、自定义打印、打印模板设置 等能力，节约大量开发时间成本，提高产品体验和竞争力
需要调用XZReportPrint 方法生成打印模板实例 然后调用实例上的方法快速完成功能实现
// 打印模板需要调用 XZReportPrint 方法生成 打印模板实例
const reportPrint = XZReportPrint()
按模板打印
需要先调用 setTemplate方法设置打印模板 （打印模板可以通过设计器快速生成）然后在调用 print方法
// options 打印模板列表
// [{name:'模板名称',print:sheetConfig}] name：模板名称， print：对应的是报表配置项
// 设置模板
reportPrint.setTemplate(options)
// data //打印报表数据 data支持传入二维数组，二维数组为批量数据打印
reportPrint.print(data)
按模板预览打印
需要先调用 setTemplate方法设置打印模板 （打印模板可以通过设计器快速生成）然后在调用 previewPrint方法
// 参数对应 print方法中的参数
// 效果如下图
// 设置模板
reportPrint.setTemplate(options)
reportPrint.previewPrint(data)
实现自定义打印
直接调用 customPrint方法即可。
// data 同print方法中的参数data
// 效果如下图
// template => {name:'模板名称',print:print}
reportPrint.customPrint(data,template)
报表效果展示
更多效果和具体配置可点击连接查看 https://www.yuque.com/tizdata/report/tiggfu7pa8maemn7
横纵向报表
双向扩展
横向分组小计
纵向分组小计
双向分组小计
分片重复
标签打印
客户订单打印
自由报表