小智BI开发文档
李怡甜 于2024/05/11 18:21:52创建
扬起你的笑脸 于2026/06/30 11:34:14修改
展开目录
## 小智BI简介 小智BI是一款 UMD 编译文件，在webpack和vite等项目中无需再次编译。直接将开发包库文件放入项目目录下。小智BI分为设计器端与展示端。小智BI的使用分为以下部分。目录为1-4为设计器端部分，目录为5-7为展示端部分。 ## 小智BI设计器开发手册 ## 1.SDK的下载与嵌入 引入 XZChartDesigner/report.js , 可访问全局变量 window.designer。小智BI内置了多种控件以及可以根据您的需求，完成一种新的控件来展现数据，实现数据的可视化展示。 ### 1.1 SDK获取 开发文件是一款 UMD 编译文件，在webpack和vite等项目中无需再次编译。 开发包文件，可以在小智BI官网进行下载：[https://tizdata.com/xzdownload](https://tizdata.com/xzdownload) ### 1.2 嵌入 开发文件XZChartDesigner/report.js 引入后, 可访问全局变量 window.XZChartDesigner。在调用设计器XZChartDesigner时，需先调XZChartDesigner.setKey(授权码)方法，使用授权码。小智BI设计器需要一个dom元素来实现画布的初始化，小智BI在初始化方法中有一个option字段，我们通过该option字段来对设计器进行参数设置，其它更多的参数请查看注释里的说明。 实例化XZChartDesigner后就可以在dom中看到设计器了，到此已嵌入成功。 ### 原生js嵌入示例 ```javascript <div id="chartDesigner" class="chartDesigner"></div> import '@/assets/danfojsCore/danfojsCore.js'; import '@/assets/danfojsCore/danfojsCore.css'; import '@/assets/echarts/echarts.js'; import '@/assets/echarts/echarts.css'; import '@/assets/params/params.js'; import '@/assets/params/params.css'; import '@/assets/xztable/xztable.js'; import '@/assets/xztable/xztable.css'; import '@/assets/XZChart/xzchart.js'; import '@/assets/XZChart/xzchart.css'; import '@/assets/XZChartDesigner/report.js'; import '@/assets/XZChartDesigner/report.css'; //也可以采用下方两种方式引入 //<style type="text/css">@import"./danfojsCore/danfojsCore.css";</style> //<style type="text/css">@import"./echarts/echarts.css";</style> //<style type="text/css">@import"./params/params.css";</style> //<style type="text/css">@import"./xztable/xztable.css";</style> //<style type="text/css">@import"./XZChart/xzchart.css";</style> //<style type="text/css">@import"./XZChartDesigner/report.css";</style> //<script src="./danfojsCore/danfojsCore.js"> </script> //<script src="./echarts/echarts.js"> </script> //<script src="./params/params.js"> </script> //<script src="./xztable/xztable.js"> </script> //<script src="./XZChart/xzchart.js"> </script> //<script src="./XZChartDesigner/report.js"> </script> let option = {} // 绑定授权码 XZChartDesigner.setKey(授权码) //调用设计器 const designer = new XZChartDesigner("#chartDesigner",option); /* option = { //参数配置说明 根据您的需求填写option uploadImage: { //上传图片相关信息 如果不传该字段时，设计器用到的所有上传图片配置项均不显示。 server: "url",//上传图片地址 method: "post",//上传图片请求方式 headers: { //上传图片请求头 "Authorization": "Token XXXXXXXX" }, fieldName: "file", resultField:"file" }, pageData:{ //画布初始化时的宽高 width:'1920px', height:'1080px' }, canvasScale:50,//画布初始化时的缩放比 dataSet:[ //数据集按钮的方式 如果不传该字段时，数据集支持默认的Json数据 { //Json数据 id:1, value:"新建Json数据集" }, { //http请求数据 id:2, value:"新建Http接口数据集" }, { //API服务数据 id:3, value:"API服务数据集" }, {//外部数据集 id:4, value:"外部数据集" } ] } */ ``` ### Vue嵌入示例 ```javascript <template> <div id="chartDesigner" style="width: 100%; height: 100%"></div> </template> <script setup> import { ref, onMounted } from 'vue'; import '@/assets/danfojsCore/danfojsCore.js'; import '@/assets/danfojsCore/danfojsCore.css'; import '@/assets/echarts/echarts.js'; import '@/assets/echarts/echarts.css'; import '@/assets/params/params.js'; import '@/assets/params/params.css'; import '@/assets/xztable/xztable.js'; import '@/assets/xztable/xztable.css'; import '@/assets/XZChart/xzchart.js'; import '@/assets/XZChart/xzchart.css'; import '@/assets/XZChartDesigner/report.js'; import '@/assets/XZChartDesigner/report.css'; let designer = null; onMounted( () => { let option = {} designer = new XZChartDesigner("#chartDesigner", option); }); ``` ### React嵌入示例 ### **Angular**嵌入示例  ## 2.画布设计器的操作 ### 2.1 画布属性部分 画布属性部分位于画布的右侧，画布属性可根据您展示数据的设备尺寸来调整画布设计器的属性。目前支持修改画布的宽度、高度、单屏高度、内边距、背景颜色、背景图等。单屏高度主要是用于设计的画布在滚屏时更好的操作。可在小智BI初始化方法时设置option字段来改变画布的初始化宽高。 ```javascript let option = { pageData:{ //画布初始化时的宽高 width:'1920px', height:'1080px' }, } ```  ### 2.2 控件属性部分 控件属性部分位于画布的上方，在画布设计器的左侧控件栏中将控件添加到画布后支持拖动、改变控件的大小、位置、层次等属性来更精确的修改控件属性，实现数据的图表化。  ### 2.3 画布目录部分 目录是将画布中的控件进行分组、锁定、是否显示等功能对控件进行更方便快捷的管理与使用。可对目录列表中的控件进行拖动来实现控件层次改变、控件分组等。支持单、多个控件的操作。  ### 2.4 数据来源部分 数据来源目前支持选择Json数据、http请求数据、API服务数据三种数据集类型。可以支持接收外部Json数据。可在小智BI初始化方法时设置option字段来选择数据集的可选择方式。 以Json数据为实例来演示。 ```javascript let option = { dataSet:[ //数据集按钮的方式 { //Json数据 id:1, value:"新建Json数据集" }, { //http请求数据 id:2, value:"新建Http接口数据集" }, { //API服务数据 id:3, value:"API服务数据集" } ] } ```   点击保存并更新按钮后，该数据会出现 添加数据集 按钮下方列表中。  可以支持接收外部Json数据。在小智BI初始化方法时设置option字段来实现接收外部数据。 ```javascript let onUpdateDatasetList = ()=>{ return new Promise((resolve, reject)=>{ // resolve的数据格式 let results = [ { name:"测试", //必填项 id:"测试", //必填项 fields:[], // 数据表中字段 字段的数据结构 {name:"字段名称",data_type:"字段类型"} data_type => 1日期 2数字 3字符串 params:[], // 数据表中参数 参数耳朵数据结构 {name:"参数名称",data_type:"参数类型"} data_type => 1日期 2数字 3字符串 } ] resolve(results) }) } let option = { onUpdateDatasetList } ``` 可以同onUpdateDatasetList方法一起使用，在控件刷新时会执行回调该方法。在小智BI初始化方法时设置option字段来实现。 ```javascript // datasets => [{name:"数据表名称",id:"数据表id"...}] 参与获取数据的数据集 // params => [{name:"参数名称",value:"参数值"}] value的类型是字符串或者数组 // 该方法的返回值是一个Promise const onUpdateData = (datasets,params)=>{ ... return new Promise((resolve, reject)=>{ // resolve的数据格式 let results = [ { name:"测试", //必填项 id:"测试" //必填项 response_data:[] // [{a:1,b:2}] } ] resolve(results) }) let option = { onUpdateDatasetList, onUpdateData } ``` ## 3.控件设计器的操作 控件设计器是对控件本身进行数据、样式、事件等编辑。以控件类型为柱状图来演示控件设计器的使用。![image] ### 3.1 数据的使用 在控件设计器的左侧可以选择数据集来实现对数据的选择及使用。在这个例子中我们选择了在上面填写名称为测试的数据集，可以展示出该数据集的字段、参数信息。对应的字段栏中支持对字段的拖动到数据配置栏中实现数据的使用。  ### 3.2 控件数据属性 控件数据属性包含维度、度量、选择器、数据过滤器、便签提示字段等字段。数据属性是根据控件类型的不同所需要的字段配置项也不同。维度支持钻取、排序、格式化、字段切换等功能。度量支持排序、格式化、字段切换、汇总方式等功能。例子中我们配置了以a字段为维度、b字段为度量的展示。  ### 3.3 控件样式属性 控件样式属性包含了 控件基础、控件标题、控件选择器 三大基础属性以及控件自身特定的样式属性。可以通过修改各个样式属性来对控件的编辑。控件样式是实时的回显到控件上，更加直观的观察控件。 例子中我们修改了样式中的控件标题栏下内容配置项。 #### 修改前展示  #### 修改后展示  ### 3.4 控件事件属性 控件事件属性可以实现 控件响应事件包含是否参与联动、控件的点击事件、控件工具栏（控件放大、导出图片、导出Excel）。 例子中我们添加控件工具栏中的控件放大按钮。  ## 4 画布设计器的保存 ### 4.1 画布设计器的数据保存 画布设计器暴露了保存的方法，在编辑完画布设计器时可以调用getSaveData事件拿到画布设计器的全部数据。用于展示端的使用或回显设计器进行再次的设计。 ```javascript const data = designer.getSaveData();//画布设计器的保存事件 ``` ### 4.2 画布设计器的数据回显 在调用画布设计器保存方法后拿到的数据，可在调用window.XZChartDesigner时传入data字段实现数据的回显。option字段是data 为上方数据保存时拿到的数据。 ```javascript let option = {}; const designer = new XZChartDesigner("#chartDesigner",option，data); ``` ## 小智BI展示端开发手册 ## 5.展示端SDK的下载与嵌入 引入 XZChart/xzchart.js , 可访问全局变量 window.XZDashboard。可将小智BI设计器端创建的报表展示出来。 ### 5.1 SDK获取 开发文件是一款 UMD 编译文件，在webpack和vite等项目中无需再次编译。 开发包文件，可以在小智BI官网进行下载：[https://tizdata.com/xzdownload](https://tizdata.com/xzdownload) ### 5.2 嵌入 开发文件XZChart/xzchart.js 引入后, 可访问全局变量 window.XZDashboard。在调用展示端XZDashboard时，需先调XZDashboard.setKey(授权码)方法，使用授权码。 实例化XZDashboard后就可以在dom中看到展示效果了，到此已嵌入成功。 ### 原生js嵌入示例 ```javascript <div id="chartContainer" style="width:100%;height:100%;"></div> import '@/assets/danfojsCore/danfojsCore.js'; import '@/assets/danfojsCore/danfojsCore.css'; import '@/assets/params/params.css'; import '@/assets/params/params.js'; import '@/assets/params/params.css'; import '@/assets/xztable/xztable.js'; import '@/assets/xztable/xztable.css'; import '@/assets/XZChart/xzchart.js'; import '@/assets/XZChart/xzchart.css'; //html文件引入方式 //<style type="text/css">@import"./danfojsCore/danfojsCore.css";</style> //<style type="text/css">@import"./params/params.css";</style> //<style type="text/css">@import"./xztable/xztable.css";</style> //<style type="text/css">@import"./XZChart/xzchart.css";</style> //<script src="./danfojsCore/danfojsCore.js"> </script> //<script src="./params/params.js"> </script> //<script src="./xztable/xztable.js"> </script> //<script src="./XZChart/xzchart.js"> </script> // reportConfig 图表配置项 reportData 控件初始化数据 paramsConfig 参数面板配置项 let config = { //等同于 4.1设计器保存时调用方法返回数据中的 config字段 "child": [ { "id": "d5384ef3-4c40-4f28-af88-383b42bda1c4", "type": "standardBar", "option": { "chartConfig": { "chartBasic": { "grid__top": 35, "grid__bottom": 35, "grid__left": 35, "grid__right": 35 }, "xAxis": { "axisLine__show": true, "axisLine__lineStyle__width": 1, "axisLine__lineStyle__color": "rgba(0, 0, 0, 1)", "axisTick__show": true, "axisTick__length": 5, "axisTick__lineStyle__width": 1, "axisTick__lineStyle__color": "rgba(0, 0, 0, 1)", "axisLabel__show": true, "axisLabel__rotate": 0, "axisLabel__interval": 0, "axisLabel__margin": 10, "axisLabel__color": "rgba(0, 0, 0, 1)", "axisLabel__fontSize": 12, "splitLine__show": false, "splitLine__lineStyle__width": 1, "splitLine__lineStyle__color": "rgba(80, 80, 80, 1)" }, "yAxis": { "FormatObj__dataFormat__rateValue": -1, "FormatObj__dataFormat__decimalValue": 0, "splitNumber": 0, "axisLine__show": true, "axisLine__lineStyle__width": 1, "axisLine__lineStyle__color": "rgba(0, 0, 0, 1)", "axisTick__show": true, "axisTick__length": 5, "axisTick__lineStyle__width": 1, "axisTick__lineStyle__color": "rgba(0, 0, 0, 1)", "axisLabel__show": true, "axisLabel__rotate": 0, "axisLabel__color": "rgba(0, 0, 0, 1)", "axisLabel__fontSize": 12, "splitLine__show": false, "splitLine__lineStyle__width": 1, "splitLine__lineStyle__color": "rgba(80, 80, 80, 1)", "useYAxisMinMax": false, "yAxisMin": 0, "yAxisMax": 100 }, "customSeries": { "content": "", "show": true, "position": "top", "align": "center", "color": "rgba(0, 0, 0, 1)", "fontSize": 12, "rotate": 0, "distance": 0 }, "tooltip": { "content": "", "showContent": true, "backgroundColor": "rgba(0, 0, 0, 1)", "textStyle__color": "rgba(255, 255, 255, 1)", "textStyle__fontSize": 12, "axisPointer__lineStyle__color": "rgba(0, 0, 0, 0.6)" }, "barStyle": { "showBackground": false, "backgroundColor": "#409EFF", "barBorRadius": 0, "barWidth": "50%" } }, "dataConfig": { "data_name": "测试", "indexs": [ { "name": "a", "sort": 0, "format": null, "type": "2" } ], "columns": [ { "name": "b", "sort": 0, "format": null, "aggregate": 1, "type": "2" } ], "selectors": [], "filters": [], "tooltips": [], "type": 1 }, "eventConfig": { "linkage": { "open": true, "errorType": 1, "promptText": "无此联动值" } }, "dynamicConfig": { "marquee": { "open": false, "interval": 1000 }, "refresh": { "open": false, "type": 1, "time": [ 0 ], "interval": "10" } }, "generalConfig": { "base": { "backgroundColor": "#00000000", "background": { "show": false, "value": "" }, "backgroundImage": "", "backgroundSize": 1, "borderRadius": "0px", "boxShadow": false, "boxShadowLevel": "0px", "boxShadowVertical": "0px", "boxShadowColor": "#fff", "boxShadowLength": "2px", "boxShadowBlur": "5px", "borderWidth": "0px", "borderColor": "#eee", "padding": "0px" }, "title": { "show": true, "height": "30px", "backgroundColor": "rgba(0, 0, 0, 0)", "background": { "show": false, "value": "" }, "backgroundImage": "", "content": "标准柱状图", "hyperlink": "", "fontFamily": "", "fontSize": "16px", "color": "#666", "textAlign": "center", "textStyle": [] }, "select": { "show": true, "height": "30px", "backgroundColor": "rgba(0, 0, 0, 0)", "background": { "show": false, "value": "" }, "backgroundImage": "", "borderWidth": "1px", "borderColor": "#eee", "fontSize": "16px", "color": "#666", "selectBackgroundColor": "#fff", "method": 1, "proportion": "", "absolute": "", "spacing": "0px" } } } } ], "layout": { "report": { "width": "1920px", "height": "1080px", "padding": "0px", "single_height": "1080px", "backgroundColor": "#fff", "backgroundImage": "", "backgroundSize": 1 }, "d5384ef3-4c40-4f28-af88-383b42bda1c4": { "width": "960px", "height": "540px", "zIndex": "99", "transform": "translate(0px, 0px)" } } } // 绑定授权码 XZDashboard.setKey(授权码) let option = {reportConfig:config,reportData:[],paramsConfig:[]} const reportInstance = new XZDashboard("#chartContainer", option); reportInstance.on('onLoadDataStart', (fn) => { import(/* webpackChunkName: "external-echarts" */ '@/assets/echarts/echarts.css'); import(/* webpackChunkName: "external-echarts" */ '@/assets/echarts/echarts.js') .then((res) => { // 加载成功 fn(); }) .catch((error) => {}); }); let data = [ //等同于 4.1设计器保存时调用方法返回数据中的 data.dataConfig字段 { name:"测试", type:1, // 1 Json数据 3 API数据 response_data:[ //Json数据格式 { a:1, b:2 } ] } ] reportInstance.updateData(data); // 数据改变时 需要使用 updateData 方法更新 data,apiConfig 都是可选参数 // type 1 json数据 reportInstance.updateData(data?) // type 3 API服务 reportInstance.updateData(data?,apiConfig?) //画布显示自适应事件 有需要时在执行 // reportInstance.initView(); ``` ### Vue嵌入示例 ```javascript <template> <div id="chartContainer" style="width:100%;height:100%;"></div> </template> <script setup> import { ref, onMounted } from 'vue'; import '@/assets/danfojsCore/danfojsCore.js'; import '@/assets/danfojsCore/danfojsCore.css'; import '@/assets/params/params.css'; import '@/assets/params/params.js'; import '@/assets/params/params.css'; import '@/assets/xztable/xztable.js'; import '@/assets/xztable/xztable.css'; import '@/assets/XZChart/xzchart.js'; import '@/assets/XZChart/xzchart.css'; let reportInstance = null; let option = {reportConfig:{},reportData:[],paramsConfig:[]}; onMounted( () => { const reportInstance = new XZDashboard("#chartContainer", option); reportInstance.on('onLoadDataStart', (fn) => { import(/* webpackChunkName: "external-echarts" */ '@/assets/echarts/echarts.css'); import(/* webpackChunkName: "external-echarts" */ '@/assets/echarts/echarts.js') .then((res) => { // 加载成功 fn(); }) .catch((error) => {}); }); reportInstance.updateData(data); }); ``` ### React嵌入示例 ### **Angular**嵌入示例  ## 6. 展示端Json数据回调事件 在设计器端使用的onUpdateDatasetList方法获取Json数据时，在展示端也有onUpdateData来获取外部数据，进行数据的更新。 在小智BI展示端初始化时设置option字段来实现。 ```javascript // datasets => [{name:"数据表名称",id:"数据表id"...}] 参与获取数据的数据集 // params => [{name:"参数名称",value:"参数值"}] value的类型是字符串或者数组 // 该方法的返回值是一个Promise const onUpdateData = (datasets,params)=>{ ... return new Promise((resolve, reject)=>{ // resolve的数据格式 let results = [ { name:"测试", //必填项 id:"测试" //必填项 response_data:[] // [{a:1,b:2}] } ] resolve(results) }) let option = {reportConfig:config,reportData:[],paramsConfig:[],onUpdateData} ```