快速开始

在开始之前，推荐先学习 ES2015。官方指南假设你已了解关于 HTML、CSS 和 JavaScript 的中级知识。如果你刚开始学习前端，将 Quick BI 自定义组件作为你的第一步可能不是最好的主意。开发自定义组件有在线开发和本地开发两种模式, 以下将分别进行说明。

模式一. 在线开发

Quick BI 支持在线开发模式。在该模式下, 自定义组件的开发和调试将在页面中进行, 无需安装开发环境, 适合大部分场景。在开始之前, 你需要使用组织管理员账号登录Quick BI。

一. 注册组件

首先需要注册一个自定义组件。

1. 访问开放平台 > 自定义组件 > 注册组件, 开发模式选择在线编辑, 填好信息后点击确认。

   说明

   开发模式支持在线编辑模式和专业模式，您可以根据实际情况进行选择，

   请参见模式一. 在线开发、模式二. 本地开发。

2. 在注册组件对话框中，配置以下参数。

   界面参数说明

   参数	说明
   组件名称	您可以自定义组件名称。
   图标	支持从本地上传图片作为组件的图标。 说明 图片分辨率大于60×60像素，且小于180×60像素。 单张图片大小不超过100 KB。
   组件类型	支持添加图表类型、图表卡片菜单类型、电子表格菜单类型的组件。
   适用范围	添加组件的应用范围，支持在仪表板、数据大屏和电子表格中添加图表类型的自定义组件。
   开发模式	在线编辑：在页面中编辑调试，适合大部分场景。 专业模式：使用SDK本地调试，适合更专业的场景。
   调试地址	用于调试自定义组件的地址。 说明 仅专业模式需要调试地址。
   平台	支持添加自定义组件的平台，支持PC端和移动端。
   开启ShadowDOM	开启后，组件dom会开启ShadowDOM模式。
   默认宽高	设置自定义组件的宽度和高度。
   依赖的第三方库	可选项，填写CDN地址，用于提升组件性能。
   备注	给自定义组件添加备注。

3. 单击确定。

   此时，您可以在组件管理页面，看到您新注册的组件。

   

4. 添加Demo组件。

   您也可以直接点击“添加Demo组件”来快速创建一个自定义组件。

   

   该Demo自定义组件预置的配置信息如下：

   

   该自定义组件通过在线编辑方式开发了一个基于 echarts 的圆角环形图自定义组件，相关的代码已经通过注册Demo组件写入在qbi内，展示效果如下所示：

   

   您可以直接管理使用该Demo自定义组件，或改造该Demo组件成自己需要的组件。

二. 调试组件

注册好组件后， 点击组件卡片上的调试组件图标进行调试。

在弹出的对话框中, 选择您想要调试的调试范围、工作空间和对应的仪表板, 单击前往调试。

在打开的仪表板编辑页面中，您可以开发自定义组件。

调试后的图表效果如下：

模式二. 本地开发

在该模式下, 自定义组件的开发和调试将在本地环境中进行, 需要先安装和配置好本地环境, 适合更专业的场景。

一.安装环境

在开发前, 您将需要安装以下软件：

1. node.js

   进入nodeJS官网，下载并安装Node环境（建议安装node16版本）。安装完成后可以通过以下命令验证是否安装成功。

   node -v

2. git

   进入Git官网，下载并安装git。安装完成后可以通过以下命令验证是否安装成功。

   git --version

3. yarn

   Quick BI推荐使用yarn安装依赖。安装方式如下：

   npm i -g yarn

   3.1 yarn 镜像

   国内 yarn 默认镜像下载速度可能会比较慢, 推荐使用淘宝镜像。

   yarn config set registry https://registry.npm.taobao.org/

4. vscode

   Quick BI推荐使用Visual Studio Code 作为IDE，Quick BI 种子项目使用了TypeScript特性，为了获得更好的开发体验，推荐您使用vscode完成开发。

二.创建开发项目

1. 首先打开terminal或者powerShell，导航到要在其中创建项目的文件夹。

2. 执行以下命令创建项目：

   npm init qbi-app test

   执行之后会提示选择一个模板，如下图。

   

   • chart开头的为自定义图表模板。

   • menu 开头的为自定义菜单模板。

   可以添加参数 -t 来选择模板创建。

   # 创建一个 "自定义图表" 模板
   npm init qbi-app test -t chart

3. 进入目录并安装依赖。

   cd test
   yarn

4. 启动本地服务。

   yarn run start

   启动成功后，可以看到如下提示。

   

   • 如果浏览器没有自动打开，可能是您未安装Chrome浏览器。建议安装Chrome，完成后用Chrome浏览器手动打开localhost:8001/。

   • 如果您看到端口占用冲突，可能是您的8001端口被别的应用程序占用了。

   • 如果浏览器打开localhost:8001/，显示并没有此服务，可能是您的电脑并未配置hosts localhost指向127.0.0.1，可以在Chrome浏览器中访问127.0.0.1:8001/来预览组件。

   • 第一次打开时可能会遇到https证书问题，请参见常见问题。

5. 打开本地浏览器输入127.0.0.1:8001/。

   当您看到如下界面，表示本地服务启动成功。

   说明

   调试过程中请保持本地服务持续正常启动。

三.在Quick BI仪表板中调试组件

1. 注册组件

   首先需要注册一个自定义组件。

   访问开放平台> 自定义组件> 注册组件, 开发模式选择专业模式, 填好信息后点击确认。

   

   说明

   依赖第三方库：选填，若组件无性能问题可不填。

2. 调试组件

   点击组件卡片上的调试组件图标

   

   在弹出的对话框中, 选择您想要调试的调试范围, 工作空间和对应的仪表板页面, 单击前往调试。

   

   在打开的仪表板编辑页面中，单击添加图表>自定义，可以看到您创建的自定义组件。

   

   现在, 您就可以根据自己的需求开发和调试自定义组件了。