开发流程-智能商业分析 Quick BI(Quick BI)-阿里云帮助中心

开发Quick BI自定义可视化组件有两种方式：在线编辑、专业模式。在线编辑即在Quick BI控制台内通过页面编辑器直接编写代码，无需安装开发环境，所有操作在浏览器中完成，适合编写简单的可视化类型；专业模式即在本地开发环境中，使用前端工程体系（例如：React、Vue、TypeScript）开发自定义可视化代码，并打包上传至Quick BI，适合更复杂的开发需求。本文将以开发一个自定义组件为例，为您介绍开发自定义可视化的具体流程。

前置条件

进行代码开发前，您首先需要在Quick BI开放平台中注册一个自定义可视化组件。具体操作说明请参见注册。

步骤一：开发调试

根据实际需求与技术偏好，选择对应模式进行可视化开发。

说明

自定义页面暂不支持使用在线编辑模式开发。

在线编辑

注册完在线编辑开发模式的可视化组件后，您需要在Quick BI控制台内的页面编辑器中，对其进行进一步的开发与调试。不同可视化组件的在线编辑调试流程基本一致，此处以调试自定义组件为例进行说明，其他类型以此类推。

登录Quick BI开放平台的自定义可视化管理页面，在组件页签下找到目标组件，点击其卡片上的调试按钮。

在调试组件弹窗中，设置以下信息：

配置项	说明
组件名称	默认读取注册当前组件时设置的名称。
调试环境	选择组件的调试环境。在线开发环境：即选择在线编辑的组件源码进行调试，其他配置使用待发布包配置。待发布环境：即选择已保存但尚未正式发布的组件代码进行调试，其他配置使用待发布配置。推荐选择在线开发环境进行组件开发。不同运行状态下，可选择的调试环境不同，具体说明请参见运行状态。
调试范围	选择调试组件的宿主页面类型。此处可选的类型取决于注册当前组件时，适用范围的配置情况，具体说明请参见注册。
工作空间	选择调试组件的工作空间。
仪表板/数据大屏	选择调试组件的具体资源。当调试范围选择为仪表板时，可在此处下拉列表中选择具体的调试仪表板；当调试范围选择为数据大屏时，可在此处下拉列表中选择具体的调试大屏。若不指定具体的仪表板/数据大屏，则在跳转调试时，系统将默认为您在已指定的工作空间下，新建仪表板/数据大屏进行调试。

调试信息配置完成后，点击前往调试按钮即可自动跳转至宿主页面，此时宿主页面会自动打开代码编辑面板。在页面上修改代码后，点击运行按钮可进行效果调试；当您完成组件代码开发后，点击保存按钮即可保存组件代码内容。

专业模式

在专业模式下，创建Quick BI自定义可视化工程项目的最佳方式是使用create-qbi-app脚手架工具创建模板项目。具体操作步骤如下：

安装环境
在开发前，您需要安装和设置以下软件：
- Node.js
  进入nodeJS官网，下载并安装Node环境（建议安装 >= node22版本）。安装完成后可以通过以下命令验证是否安装成功。
```
node -v
```
- 设置镜像
  国内 npm 默认镜像下载速度可能会比较慢，推荐使用淘宝镜像。
```
# npm 
npm config set registry https://registry.npmmirror.com/

# pnpm (推荐）
npm install -g pnpm
pnpm config set registry https://registry.npmmirror.com/

# yarn
npm i -g yarn
yarn config set registry https://registry.npmmirror.com/
```

创建模板项目

首先打开Terminal或者PowerShell，导航到要创建项目的文件夹。执行 npx create-qbi-app@latest <project-name> -t <template-type>命令创建模板项目，例如：

# npm
npx create-qbi-app@latest my-chart -t chart-react-ts

# pnpm (推荐）
pnpm create qbi-app@latest my-chart -t chart-react-ts

# yarn
yarn create qbi-app@latest my-chart -t chart-react-ts

其中 my-chart为项目名称， -t 为模板类型参数，其预设值如下：

模板类型	框架	说明
chart-react-ts	React + TypeScript	自定义组件
chart-vue-ts	Vue + TypeScript
chart-vanilla-ts	无框架 + TypeScript
menu-chart-react-ts	React + TypeScript	图表卡片自定义菜单
menu-dashboard-react-ts	React + TypeScript	仪表板自定义菜单
menu-workbook-react-ts	React + TypeScript	电子表格自定义菜单
page-react-ts	React + TypeScript	自定义页面
page-vue-ts	Vue + TypeScript
page-vanilla-ts	无框架 + TypeScript

如果不填 -t 参数，则根据提示选择模板类型即可。得到的模板项目目录结构如下

├── dist                 # 构建产出目录
├── node_modules         # 项目相关包依赖
├── public               # 本地调试静态资源
│    └──index.html
├── src                  # 源码目录
│    ├──Component.tsx    # 组件具体实现
│    ├──index.scss       # 样式文件
│    ├──index.ts         # 组件生命周期入口, 一般无需关注
|    └──meta.ts          # 元信息
├── qbi.config.ts        # 构建配置
├── package.json         # 依赖包管理
├── README.md            # 项目说明文档
└── tsconfig.json        # typescript配置文件

您可以在此按需执行以下命令：

npm run start - 启动本地开发服务器。
npm run build - 构建项目。
npm run bundle - 将构建结果打包为Quick BI开发包。

启动 devServer
目标项目创建成功后，进入目录安装依赖并启动，在开发过程中请保持本地服务持续正常启动。
```
# npm
cd my-chart && npm i && npm run start

# pnpm
cd my-chart && pnpm i && pnpm run start

# yarn
cd my-chart && yarn && yarn run start
```
默认开发端口为 8001 , 可以在 qbi.config.ts中修改本地开发端口
```
import { defineConfig } from '@quickbi/qbi-dev-tools';

export default defineConfig({
  devServer: {
    port: 8001,
    host: '127.0.0.1',
    server: {
      type: 'https',
    },
  },
});
```
说明
- 端口修改后还需要在自定义可视化管理页同步调整，以自定义组件为例：
- 首次启动开发服务器时，可能需要如下图所示点击继续前往。
  启动成功后，会自动打开以下页面：

进入宿主页调试

不同自定义可视化类型在专业模式下的调试流程基本一致，此处以调试自定义组件为例，其他类型以此类推。

登录Quick BI开放平台的自定义可视化管理页面，在组件页签下找到需要调试的目标组件，点击其卡片上的调试按钮。

在调试组件弹窗中，设置以下信息：

配置项	说明
组件名称	默认读取注册当前组件时设置的名称。
调试环境	选择组件的调试环境。在专业模式下，当仅注册了组件但未上传开发包时，仅支持选择在本地开发环境调试，即：从本地服务中读取组件资源，其他配置使用待发布包配置。关于组件状态及支持选择的调试环境说明，请参见运行状态。
调试范围	选择调试组件的宿主页面类型。此处可选的类型取决于注册当前组件时，适用范围的配置情况，具体说明请参见注册。
工作空间	选择调试组件的工作空间。
仪表板/数据大屏	选择调试组件的具体资源类型。当调试范围选择为仪表板时，可在此处下拉列表中选择具体的调试仪表板；当调试范围选择为数据大屏时，可在此处下拉列表中选择具体的调试大屏。若不指定具体的仪表板/数据大屏，则在跳转调试时，系统将默认为您在已指定的工作空间下，新建仪表板/数据大屏进行调试。

完成信息设置后点击前往调试按钮，即可自动跳转至宿主页面。此时宿主页面已经代理上本地的开发服务，修改本地代码后，刷新宿主页面即可进行调试。

打包
开发完成后，执行以下命令，将会得到类似 my-component-1.0.0.zip 的开发包。
```
npm run build && npm run bundle
```
上传开发包
将上一步中获取的开发包上传至Quick BI，以自定义组件为例：
1. 在Quick BI开放平台的自定义可视化管理页面中，找到待上传开发包的目标组件并点击其卡片图标。
2. 在更新组件弹窗中点击请选择文件，上传压缩包文件。
3. 点击确定按钮即可上传开发包，完成后组件即由开发中转为待发布状态。