快速开始

在开始之前，推荐先学习 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环境（建议安装node22版本）。安装完成后可以通过以下命令验证是否安装成功。

   node -v

2. git

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

   git --version

3. （可选）包管理工具

   您可以选择Node自带的npm包管理工具，但更推荐使用现代化、高性能的包管理工具pnpm来安装依赖。

   1. pnpm

      安装方式如下：

      npm install -g pnpm

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

      pnpm config set registry https://registry.npmmirror.com/

   2. yarn

      您也可以选择yarn作为包管理工具，安装方式如下：

      npm i -g yarn

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

      yarn config set registry https://registry.npmmirror.com/

4. vscode

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

二.创建开发项目

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

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

   npm init qbi-app@latest my-app

   执行之后会提示选择一个模板类型，如下图所示，分别表示自定义组件、自定义图表卡片菜单、自定义仪表板菜单和自定义电子表格菜单。

   

   选择Custom Chart自定义组件类型后，会再进行框架选择，其中Vanilla表示框架无关。

   

   选择后回车确认，显示以下页面就成功创建了模板代码。

   

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

   cd my-app
   pnpm install

4. 启动本地服务。

   pnpm run start

   启动成功后，会显示该页面，然后前往Quick BI仪表板中调试组件。其中，首次调试时，需要如下图所示点击继续前往。

   

   说明

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

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

1. 注册组件

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

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

   

   说明

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

2. 调试组件

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

   

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

   

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

   

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