本文將介紹 Quick BI 自訂群組件的基本概念。
自訂群組件
在 Quick BI 中，自訂群組件 (CustomComponent) 定義是一個包含了bootstrap、mount、unmount、update屬性的對象，包含了自訂群組件具體的實現的邏輯。詳細資料請參考Lifecycle。
舉例
// 這是一個自訂群組件
const CustomComponent = {
bootstrap: (props) => {},
mount: (props) => {},
unmount: (props) => {},
update: (props) => {},
}在大多數情況下，您無需關心自訂群組件的生命週期，bi-open-sdk和bi-open-react-sdk提供了建立自訂群組件的createBIComponent函數，直接調用即可。
自訂群組件元資訊
自訂群組件元資訊（ComponentMeta） 是一個包含了propsSchema等屬性的對象。通過元資訊可以定製 Quick BI 自訂群組件的資料面板/樣式面板/進階面板等功能，詳細資料請參考ComponentMeta。
舉例
const meta = {
propsSchema: {
dataSchema: {
schema: {}
},
styleSchema: {
schema: {}
},
}
}專案結構
建立Quick BI自訂群組件的最佳方式是使用create-qbi-app命令建立種子專案。通過npm init qbi-app <project name>命令建立，請參見快速開始。
檔案目錄
產生好種子專案後，檔案目錄結構如下：
├── build # 構建產出目錄 ├── node_modules # 專案相關包依賴 ├── public # 本地調試入口 │ └──index.html ├── src # 源碼 │ ├──index.tsx # 組件入口 │ ├──index.scss # 組件樣式檔案 │ └──meta.ts # 組件屬性配置，包括資料、樣式以及資料到視圖的映射關係等。 ├── .eslintrc # eslint外掛程式的設定檔 ├── config-overrides.js # webpack設定檔 ├── package.json # 依賴包管理 ├── README.md # 專案說明文檔 └── tsconfig.json # typescript設定檔相關命令
npm run start：啟動本地調試npm run build：構建專案npm run pack：將構建結果打包為Quick BI開發包，會預設先執行npm run build。
src目錄
該檔案夾包含自訂群組件的原始碼。包含：
meta.ts：自訂群組件元資訊, 用於配置資料面板和樣式面板。index.tsx：自訂群組件。index.scss：自訂群組件樣式檔案。
public目錄
該檔案夾包含了
devserver的html模板和mock資料。build目錄
該檔案夾包含了構建產出以及打包的結果。
執行
npm run build後，會產出如下模組：檔案名稱
模組類型
模組名稱
main.js
umd
BIComponent
meta.js
umd
BIComponentMeta
main.css
-
-
說明為了確保產出結果的正確性，請不要隨意更改webpack的配置。
自訂群組件狀態
Quick BI 自訂群組件有運行狀態和顯隱狀態兩種維度狀態。
運行狀態
運行狀態是描述自訂群組件從建立到銷毀的一系列狀態, 根據組件的開發模式的不同而有所不同。通過自訂群組件管理平台可以維護組件的運行狀態, 其路徑為開放平台>自訂群組件。
線上編輯
待發布 - 剛註冊, 或發行且資訊有修改, 但未同步到線上的狀態。
發行 - 線上運行中的狀態。
專業模式
開發中 - 剛註冊但未上傳開發包的狀態。
待發布 - 上傳了開發包, 或發行且資訊有調整, 但未同步到線上的狀態。
發行 - 線上運行中的狀態。
註冊組件
點擊註冊組件, 填好資訊後點擊確定按鈕。
提示註冊組件成功後, 會在頁面中顯示該組件的卡片。
開發模式會影響自訂群組件後續的開發流程且不可修改, 請按需選擇。
調試組件
在組件列表中, 點擊組件卡片的調試按鈕。
會彈出調試組件的對話方塊。
線上編輯下, 組件調試環境有3種：
線上開發環境 - 組件源碼可以線上編輯，其他配置使用待發布包配置。
待發布環境 - 組件資源會從待發布包讀取，其他配置使用待發布配置。
線上環境 - 組件資源會從發行包讀取，其他配置使用發行配置。
專業模式下, 組件調試環境有3種：
本地開發環境 - 組件資源會從本地服務中讀取，其他配置使用待發布包配置。
待發布環境 - 組件資源會從待發布包讀取，其他配置使用待發布配置。
線上環境 - 組件資源會從發行包讀取，其他配置使用發行配置。
在調試組件的對話方塊中, 選擇要調試的調試範圍、工作空間和對應的儀表板,單擊前往調試, 會跳轉到對應的儀表板頁面。
線上編輯
在線上編輯模式下, 頁面物料欄中會顯示組件的icon, 頁面下方會出現代碼編輯器, 可以選擇左側src下的檔案進行編輯, 修改代碼後, 點擊運行按鈕可以即時運行代碼。
代碼編輯面板可以手動關閉, 如果想再次進入編輯, 可以點擊自訂群組件卡片右上方的下拉式功能表, 點擊編輯自訂群組件喚出代碼編輯面板。
需要注意：
偵錯模式下，儀表板自訂群組件總是會在物料欄中顯示, 即組件的顯隱狀態失效。
偵錯模式下，儀表板可以儲存但無法發布。
線上編輯下組件開發完成後, 點擊儲存按鈕即可儲存自訂群組件代碼, 組件會進入待發布狀態。
專業模式
在專業模式下, 儀表板頁面點擊添加圖表->自訂，會顯示組件的icon, 將其拖動到儀表板中, 配置好資料面板並進行取數, 本地修改代碼後, 通過重新整理頁面的方式進行開發調試。
需要注意：
專業模式下請確保組件本地服務已經啟動。
偵錯模式下, 儀表板自訂群組件總是會在物料欄中顯示, 即組件的顯隱狀態失效。
偵錯模式下, 儀表板可以儲存但無法發布。
專業模式下組件開發完成後, 需要將組件打包並上傳, 路徑是 開放平台 > 自訂群組件。
點擊修改按鈕, 會彈出修改組件資訊的對話方塊。
修改好相應資訊後, 點擊確定按鈕。完成修改後, 組件會進入待發布狀態。
開發可以通過種子專案中執行 yarn run pack 產出。
發布組件
當組件處於待發布狀態時, 組件卡片上的發布按鈕會變成可點擊狀態。
點擊發布按鈕, 會彈出組件變更詳情, 有變更的屬性會標紅。
如果是線上編輯模式, 點擊查看代碼比對查看具體的代碼變動。
點擊確認發布, 組件就正式發布到生產環境, 並進入發行狀態。
刪除群組件
在組件列表中, 點擊組件卡片的刪除按鈕, 可以刪除自訂群組件。
刪除後：
自訂群組件將無法新增
先前已經儲存過該自訂群組件的圖表也將不能顯示改組件, 並在原來的該組件的位置提示 "該圖表元資訊異常或已被刪除"。
顯隱狀態
顯隱狀態原因自訂群組件是否在儀表板中展示出來，共有兩種：
隱藏：隱藏狀態下，自訂群組件不展示在儀表板編輯頁的添加圖表->自訂中, 也無法切換圖表, 但可以顯示之前儲存過的圖表。
顯示：顯示狀態下，自訂群組件展示在儀表板編輯頁的添加圖表->自訂中，支援切換圖表。
需要注意：
修改組件顯示狀態不會讓組件進入待發布狀態, 而是直接線上生效。
在開發模式下, 組件將會一直顯示。
在自訂群組件平台中點擊隱藏或顯示按鈕即可修改組件顯示狀態。
體現在儀表板上則是該組件的入口顯示或者隱藏。
