：快速開始

在開始之前，推薦先學習 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. 調試組件

   點擊組件卡片上的調試組件表徵圖

   

   在彈出的對話方塊中, 選擇您想要調試的調試範圍, 工作空間和對應的儀表板頁面, 單擊前往調試。

   

   在開啟的儀表板編輯頁面中，單擊添加圖表>自訂，可以看到您建立的自訂群組件。

   

   現在, 您就可以根據自己的需求開發和調試自訂群組件了。