uni-app & uCharts 踩坑 readme All In One
uCharts readme.md 💩
uCharts官方網站
DEMO演示及在線生成工具（v2.0文檔）https://demo.ucharts.cn
優秀的nvue全端組件與模版庫nPro
圖表組件在項目中的應用 UReport數據報表
v1.0文檔（將在9月30日作廢，請盡快轉v2.0）
如何安裝、更新 uni_modules 插件點這里，必看，必看，必看
點擊右側綠色【使用HBuilderX導入插件】即可使用，示例項目請點擊右側藍色按鈕【使用HBuilderX導入示例項目】。
初次使用不顯示問題詳見常見問題選項卡
新手請先完整閱讀【幫助文檔】及【常見問題】3遍，右側藍色按鈕【示例項目】請看2遍！
關於NVUE兼容的說明： uCharts.js從2.3.0開始支持nuve（暫時只能通過原生canvas寫法調用uCharts，nuve版本組件請見碼雲示例項目uCharts-demo-nvue），因其渲染方式是通過nvue的gcanvas組件來渲染，理論上性能不及renderjs的qiun-data-charts組件性能。官方仍然建議NVUE使用圖表的頁面改為vue頁面，在App端，從性能來講，由於通訊阻塞的問題，nvue的canvas性能不可能達到使用renderjs的vue頁面的canvas。在App端，仍然推薦使用qiun-data-charts組件。詳見uni-app官方說明
秋雲圖表組件使用幫助
全新圖表組件，全端全平台支持，開箱即用，可選擇uCharts引擎全端渲染，也可指定PC端或APP端單獨使用ECharts引擎渲染圖表。支持極簡單的調用方式，只需指定圖表類型及傳入符合標准的圖表數據即可，使開發者只需專注業務及數據。同時也支持datacom組件讀取uniClinetDB，無需關心如何拼接數據等不必要的重復工作，大大縮短開發時間。
為何使用官方封裝的組件？
封裝組件並不難，誰都會，但組件調試卻是一件令人掉頭發的事，尤其是canvas封裝成組件會帶來一系列問題：例如封裝后不顯示，圖表多次初始化導致抖動問題，單頁面多個圖表點擊事件錯亂，組件放在scroll-view中無法點擊，在圖表上滑動時頁面無法滾動等等一系列問題。為解決開發者使用可視化組件的困擾，uCharts官方特推出可視化通用組件，本組件具備以下特點：
- 極簡單的調用方式，默認配置下只需要傳入
圖表類型及圖表數據即可全端顯示。 - 提供強大的
在線配置生成工具，可視化中的可視化，鼠標點一點就可以生成圖表，可視化從此不再難配。 - 兼容ECharts，可選擇
PC端或APP端單獨使用ECharts引擎渲染圖表。 - H5及App采用
renderjs渲染圖表，動畫流暢、性能翻倍。 - 根據父容器尺寸
彈性顯示圖表，再也不必為寬高匹配及多端適配問題發愁。 - 支持
加載狀態loading及error展示，避免數據讀取顯示空白的尷尬。 - chartData
配置與數據解耦，即便使用ECharts引擎也不必擔心拼接option的困擾。 - localdata
后端數據直接渲染，無需自行拼接chartData的categories及series，從后端拿回的數據簡單處理即可生成圖表。 - 小程序端不必擔心包體積過大問題，ECharts引擎將不會編譯到各小程序端，u-charts.js編譯后
僅為93kb。 - 未來將支持通過HbuilderX的schema2code自動生成全端全平台圖表，敬請期待！！！
- uCharts官方擁有3個2000人的QQ群支持，龐大的用戶量證明我們一直在努力，本組件將持續更新，請各位放心使用，本組件問題請在
QQ3群反饋，您的寶貴建議是我們努力的動力！！
致開發者
感謝各位開發者兩年來對秋雲及uCharts的支持，uCharts的進步離不開各位開發者的鼓勵與貢獻，為更好的幫助各位開發者在uni-app生態系統更好的應用圖表，uCharts始終堅持開源，並提供社群幫助開發者解決問題。 為確保您能更好的應用圖表組件，建議您先仔細閱讀本頁文檔以及uCharts官方文檔，而不是下載下來直接使用。 如遇到問題請先閱讀文檔，如仍然不能解決，請加入QQ群咨詢，如群友均不能解決或者您有特殊需求，請在群內私聊我，因工作原因，回復不一定很及時，您可直接說問題，有時間一定會回復您。
uCharts的開源圖表組件的開發，付出了大量的個人時間與精力，經過兩年來的考驗，不會有比較明顯的bug，請各位放心使用。不求您5星評價，也不求您贊賞，只求您對開源貢獻的支持態度，所以，當您想給1星評價的時候，秋雲真的會含淚希望您繞路而行……。如果您有更好的想法，可以在碼雲提交Pull Requests以幫助更多開發者完成需求，再次感謝各位對uCharts的鼓勵與支持！
快速體驗
一套代碼編到7個平台，依次掃描二維碼，親自體驗uCharts圖表跨平台效果！IOS因demo比較簡單無法上架，請自行編譯。
快速上手
注意前提條件【版本要求：HBuilderX 3.1.0+】
- 1、插件市場點擊右側綠色按鈕【使用HBuilderX導入插件】，或者【使用HBuilderX導入示例項目】查看完整示例工程
- 2、依賴uniapp的vue-cli項目：請將uni-modules目錄復制到src目錄，即src/uni_modules。（請升級uniapp依賴為最新版本）
- 3、頁面中直接按下面用法直接調用即可，無需在頁面中注冊組件qiun-data-charts
- 4、注意父元素class='charts-box'這個樣式需要有寬高
基本用法
- template代碼：（建議使用在線工具生成）
<view class="charts-box">
<qiun-data-charts type="column" :chartData="chartData" />
</view>
- 標准數據格式1：（折線圖、柱狀圖、區域圖等需要categories的直角坐標系圖表類型）
chartData:{
categories: ["2016", "2017", "2018", "2019", "2020", "2021"],
series: [{
name: "目標值",
data: [35, 36, 31, 33, 13, 34]
}, {
name: "完成量",
data: [18, 27, 21, 24, 6, 28]
}]
}
- 標准數據格式2：（餅圖、圓環圖、漏斗圖等不需要categories的圖表類型）
chartData:{
series: [{
data: [
{
name: "一班",
value: 50
}, {
name: "二班",
value: 30
}, {
name: "三班",
value: 20
}, {
name: "四班",
value: 18
}, {
name: "五班",
value: 8
}
]
}]
}
注：其他特殊圖表類型，請參考mockdata文件夾下的數據格式，v2.0版本的uCharts已兼容ECharts的數據格式，v2.0版本仍然支持v1.0版本的數據格式。
localdata數據渲染用法
-
使用localdata數據格式渲染圖表的優勢：數據結構簡單，無需自行拼接chartData的categories及series，從后端拿回的數據簡單處理即可生成圖表。
-
localdata數據的缺點：並不是所有的圖表類型均可通過localdata渲染圖表，例如混合圖，組件並不能識別哪個series分組需要渲染成折線還是柱狀圖，涉及到復雜的圖表，仍需要由chartData傳入。
-
template代碼：（建議使用在線工具生成）
<view class="charts-box">
<qiun-data-charts type="column" :localdata="localdata" />
</view>
- 標准數據格式1：（折線圖、柱狀圖、區域圖等需要categories的直角坐標系圖表類型）
其中value代表數據的數值，text代表X軸的categories數據點，group代表series分組的類型名稱即series[i].name。
localdata:[
{value:35, text:"2016", group:"目標值"},
{value:18, text:"2016", group:"完成量"},
{value:36, text:"2017", group:"目標值"},
{value:27, text:"2017", group:"完成量"},
{value:31, text:"2018", group:"目標值"},
{value:21, text:"2018", group:"完成量"},
{value:33, text:"2019", group:"目標值"},
{value:24, text:"2019", group:"完成量"},
{value:13, text:"2020", group:"目標值"},
{value:6, text:"2020", group:"完成量"},
{value:34, text:"2021", group:"目標值"},
{value:28, text:"2021", group:"完成量"}
]
- 標准數據格式2：（餅圖、圓環圖、漏斗圖等不需要categories的圖表類型）
其中value代表數據的數值，text代表value數值對應的描述。
localdata:[
{value:50, text:"一班"},
{value:30, text:"二班"},
{value:20, text:"三班"},
{value:18, text:"四班"},
{value:8, text:"五班"},
]
- 注意，localdata的數據格式必需要符合datacom組件規范【詳見datacom組件】。
進階用法讀取uniCloud數據庫並渲染圖表
-
組件基於uniCloud的clientDB技術，無需雲函數，在前端對數據庫通過where查詢條件及group和count統計即可渲染圖表。
-
具體可參考/pages/unicloud/unicloud.vue中的demo例子，使用前，請先關聯雲服務空間，然后在uniCloud/database/db_init.json文件上點右鍵，初始化雲數據庫，當控制台顯示“初始化雲數據庫完成”即完成示例數據的導入，之后方可運行uniCloud的demo。
-
template代碼：
<qiun-data-charts
type="line"
:chartData="demoData"
collection="uni-id-users"
field="register_date,status"
:where="'publish_date >= ' + new Date(startDate).getTime() + ' && publish_date <= ' + new Date(endDate).getTime()"
groupby="dateToString(add(new Date(0),register_date),'%Y-%m-%d','+0800') as text,status as group"
group-field="count(*) as value"
/>
- 注意，從uniCloud讀取出的數據，需要符合localdata的標准結果數據格式（參考上部分localdata），並需要把輸出的字段as成規定的別名（value、text、group）。
示例文件地址：
強烈建議先看本頁幫助，再看下面示例文件源碼！
/pages/ucharts/ucharts.vue（展示用uCharts全端運行的例子）
/pages/echarts/echarts.vue（展示H5和App用ECharts，小程序端用uCharts的例子）
/pages/unicloud/unicloud.vue（展示讀取uniCloud數據庫后直接渲染圖表的例子）
/pages/updata/updata.vue（展示動態更新圖表數據的例子）
/pages/other/other.vue（展示圖表交互的例子：動態更新圖表數據，渲染完成事件，獲取點擊索引，自定義tooltip，圖表保存為圖片，強制展示錯誤信息等）
/pages/format-u/format-u.vue（展示uCharts的formatter用法的例子）
/pages/format-e/format-e.vue（展示ECharts的formatter用法的例子）
/pages/tab/tab.vue（展示再tab選項卡中用法的例子，即父容器采用v-show或v-if時需要注意的問題）
/pages/layout/layout.vue（展示特殊布局用法的例子：swiper、scroll-view、絕對定位等布局）
/pages/canvas/canvas.vue（展示uCharts v2.0版本原生js用法的例子）
組件基本API參數
| 屬性名 | 類型 | 默認值 | 必填 | 說明 |
|---|---|---|---|---|
| type | String | null | 是 |
圖表類型，如全端用uCharts，可選值為pie、ring、rose、word、funnel、map、arcbar、line、column、bar、area、radar、gauge、candle、mix、tline、tarea、scatter、bubble （您也可以根據需求自定義新圖表類型，需要在config-ucharts.js或config-echarts.js內添加，可參考config-ucharts.js內的"demotype"類型） |
| chartData | Object | 見說明 | 是 |
圖表數據，常用的標准數據格式為{categories: [],series: []}，請按不同圖表類型傳入對應的標准數據。 |
| localdata | Array | [] | 是 |
圖表數據，如果您覺得拼接上面chartData比較繁瑣，可以通過使用localdata渲染，組件會根據傳入的type類型，自動拼接categories或series數據（使用localdata就不必再傳入chartData，詳見 /pages/other/other.vue 中使用localdata渲染圖表的例子）。【localdata和collection（uniCloud數據庫）同時存在，優先使用localdata；如果localdata和chartData同時存在，優先使用chartData。 即chartData>localdata>collection的優先級渲染圖表】。 |
| opts | Object | {} | 否 | uCharts圖表配置參數(option)，請參考【在線生成工具】注：傳入的opts會覆蓋默認config-ucharts.js中的配置，只需傳入與config-ucharts.js中屬性不一致的opts即可實現【同類型的圖表顯示不同的樣式】。 |
| eopts | Object | {} | 否 | ECharts圖表配置參數(option)，請參考【ECharts配置手冊】傳入eopts。注：1、傳入的eopts會覆蓋默認config-echarts.js中的配置，以實現同類型的圖表顯示不同的樣式。2、eopts不能傳遞function，如果option配置參數需要function，請將option寫在config-echarts.js中即可實現。 |
| loadingType | Number | 2 | 否 | 加載動畫樣式，0為不顯示加載動畫，1-5為不同的樣式，見下面示例。 |
| errorShow | Boolean | true | 否 | 是否在頁面上顯示錯誤提示，true為顯示錯誤提示圖片，false時會顯示空白區域 |
| errorReload | Boolean | true | 否 | 是否啟用點擊錯誤提示圖表重新加載，true為允許點擊重新加載，false為禁用點擊重新加載事件 |
| errorMessage | String | null | 否 | 自定義錯誤信息，強制顯示錯誤圖片及錯誤信息，當上面errorShow為true時可用。（組件會監聽該屬性的變化，只要有變化，就會強制顯示錯誤信息！）。說明：1、一般用於頁面網絡不好或其他情況導致圖表loading動畫一直顯示，可以傳任意(不為null或者"null"或者空"")字符串強制顯示錯誤圖片及說明。2、如果組件使用了data-come屬性讀取uniCloud數據，組件會自動判斷錯誤狀態並展示錯誤圖標，不必使用此功能。3、當狀態從非null改變為null或者空時，會強制調用reload重新加載並渲染圖表數據。 |
| echartsH5 | Boolean | false | 否 | 是否在H5端使用ECharts引擎渲染圖表 |
| directory | String | '/' | 否 | 二級目錄名稱，如果開啟上面echartsH5即H5端用ECharts引擎渲染圖表，並且項目未發布在website根目錄，需要填寫此項配置。例如二級目錄是h5，則需要填寫/h5/，左右兩側需要帶/，發布到三級或更多層目錄示例/web/v2/h5/ |
| echartsApp | Boolean | false | 否 | 是否在APP端使用ECharts引擎渲染圖表 |
| canvasId | String | 見說明 | 否 | 默認生成32位隨機字符串。如果指定canvasId，可方便后面調用指定圖表實例，否則需要通過渲染完成事件獲取自動生成隨機的canvasId |
| canvas2d | Boolean | false | 否 | 是否開啟canvas2d模式，用於解決微信小程序層級過高問題，僅微信小程序端可用，其他端會強制關閉canvas2d模式。注：開啟canvas2d模式，必須要傳入上面的canvasId（隨機字符串，不能是動態綁定的值，不能是數字），否則微信小程序可能會獲取不到dom導致無法渲染圖表！開啟后，開發者工具顯示不正常，預覽正常（不能“真機調試”,不能“真機調試”,不能“真機調試”） |
| background | String | none | 否 | 背景顏色，默認透明none，可選css的16進制color值，如#FFFFFF |
| animation | Boolean | true | 否 | 是否開啟圖表動畫效果 |
| inScrollView | Boolean | false | 否 | 圖表組件是否在scroll-view中，如果在請傳true，否則會出現點擊事件坐標不准確的現象 |
| pageScrollTop | Number | 0 | 否 | 如果圖表組件是在scroll-view中，並且整個頁面還存在滾動條，這個值應為綁定為頁面滾動條滾動的距離，否則會出現點擊事件坐標不准確的現象 |
| reshow | Boolean | false | 否 | 強制重新渲染屬性，如果圖表組件父級用v-show包裹，初始化的時候會獲取不到元素的寬高值，導致渲染失敗，此時需要把父元素的v-show方法復制到reshow中，組件檢測到reshow值變化並且為true的時候會強制重新渲染 |
| reload | Boolean | false | 否 | 強制重新加載屬性，與上面的reshow區別在於：1、reload會重新顯示loading動畫；2、如果組件綁定了uniCloud數據查詢，通過reload會重新執行SQL語句查詢，重新請求網絡。而reshow則不會顯示loading動畫，只是應用現有的chartData數據進行重新渲染 |
| disableScroll | Boolean | false | 否 | 當在canvas中移動時，且有綁定手勢事件時，禁止屏幕滾動以及下拉刷新（賦值為true時，在圖表區域內無法拖動頁面滾動） |
| tooltipShow | Boolean | true | 否 | 點擊或者鼠標經過圖表時，是否顯示tooltip提示窗，默認顯示 |
| tooltipFormat | String | undefined | 否 | 自定義格式化Tooltip顯示內容，詳見下面【tooltipFormat格式化】 |
| tooltipCustom | Object | undefined | 否 | （僅uCharts）如果以上系統自帶的Tooltip格式化方案仍然不滿足您，您可以用此屬性實現更多需求，詳見下面【tooltipCustom自定義】 |
| startDate | String | undefined | 否 | 需為標准時間格式，例如"2021-02-14"。用於配合uniClinetDB自動生成categories使用 |
| endDate | String | undefined | 否 | 需為標准時間格式，例如"2021-03-31"。用於配合uniClinetDB自動生成categories使用 |
| groupEnum | Array | [] | 否 | 當使用到uniCloud數據庫時，group字段屬性如果遇到統計枚舉屬性的字段，需要通過將DB Schema中的enum的描述定義指派給該屬性，具體格式為[{value: 1,text: "男"},{value: 2,text: "女"}] |
| textEnum | Array | [] | 否 | 當使用到uniCloud數據庫時，text字段屬性如果遇到統計枚舉屬性的字段，需要通過將DB Schema中的enum的描述定義指派給該屬性，具體格式為[{value: 1,text: "男"},{value: 2,text: "女"}] |
| ontap | Boolean | true | 否 | 是否監聽@tap@cilck事件，禁用后不會觸發組件點擊事件 |
| ontouch | Boolean | false | 否 | （僅uCharts）是否監聽@touchstart@touchmove@touchend事件（賦值為true時，非PC端在圖表區域內無法拖動頁面滾動） |
| onmouse | Boolean | true | 否 | 是否監聽@mousedown@mousemove@mouseup事件，禁用后鼠標經過圖表上方不會顯示tooltip |
| on movetip | Boolean | false | 否 | （僅uCharts）是否開啟跟手顯示tooltip功能（前提條件，1、需要開啟touch功能，即:ontouch="true"；2、並且opts.enableScroll=false即關閉圖表的滾動條功能）（建議微信小程序開啟canvas2d功能，否則原生canvas組件會很卡） |
| tapLegend | Boolean | true | 否 | （僅uCharts）是否開啟圖例點擊交互事件 |
組件事件及方法
| 事件名 | 說明 |
|---|---|
| @complete | 圖表渲染完成事件，渲染完成會返回圖表實例{complete: true, id:"xxxxx"(canvasId), type:"complete"}。可以引入config-ucharts.js/config-echarts.js來根據返回的id，調用uCharts或者ECharts實例的相關方法，詳見other.vue其他圖表高級應用。 |
| @getIndex | 獲取點擊數據索引，點擊后返回圖表索引currentIndex，圖例索引（僅uCharts）legendIndex，等信息。返回數據：{type: "getIndex", currentIndex: 3, legendIndex: -1, id:"xxxxx"(canvasId), event: {x: 100, y: 100}（點擊坐標值）} |
| @error | 當組件發生錯誤時會觸發該事件。返回數據：返回數據：{type:"error",errorShow:true/false(組件props中的errorShow狀態值) , msg:"錯誤消息xxxx", id: "xxxxx"(canvasId)} |
| @getTouchStart | （僅uCharts）拖動開始監聽事件。返回數據：{type:"touchStart",event:{x: 100, y: 100}（點擊坐標值）,id:"xxxxx"(canvasId)} |
| @getTouchMove | （僅uCharts）拖動中監聽事件。返回數據：{type:"touchMove",event:{x: 100, y: 100}（點擊坐標值）,id:"xxxxx"(canvasId)} |
| @getTouchEnd | （僅uCharts）拖動結束監聽事件。返回數據：{type:"touchEnd",event:{x: 100, y: 100}（點擊坐標值）,id:"xxxxx"(canvasId)} |
| @scrollLeft | （僅uCharts）開啟滾動條后，滾動條到最左側觸發的事件，用於動態打點，需要自行編寫防抖方法。返回數據：{type:"scrollLeft", scrollLeft: true, id: "xxxxx"(canvasId)} |
| @scrollRight | （僅uCharts）開啟滾動條后，滾動條到最右側觸發的事件，用於動態打點，需要自行編寫防抖方法。返回數據：返回數據：{type:"scrollRight", scrollRight: true, id: "xxxxx"(canvasId)} |
tooltipFormat格式化（uCharts和ECharts）
tooltipFormat類型為string字符串類型，需要指定config-ucharts.js/config-echarts.js中formatter下的屬性值。因各小程序及app端通過組件均不能傳遞function類型參數，因此請先在config-ucharts.js/config-echarts.js內定義您想格式化的數據，然后在這里傳入formatter下的key值，組件會自動匹配與其對應的function。如不定義該屬性，組件會調用默認的tooltip方案，標准的tooltipFormat使用姿勢如下：
<qiun-data-charts
type="column"
:chartData="chartData"
tooltipFormat="tooltipDemo1"
⁄>
==================
config-ucharts.js
formatter:{
tooltipDemo1:function(item, category, index, opts){return item.data+'天'}
}
==================
config-echarts.js
formatter:{
tooltipDemo1:function(){
}
}
注意，config-ucharts.js內的formatter下的function需要攜帶(item, category, index, opts)參數，這4個參數都是uCharts實例內傳遞過來的數據，具體定義如下：
| 屬性名 | 說明 |
|---|---|
| item | 組件內計算好的當前點位的series[index]數據，其屬性有data(繼承series[index].format屬性),color,type,style,pointShape,disableLegend,name,show |
| category | 當前點位的X軸categories[index]分類名稱（如果圖表類型沒有category，其值則為undefined） |
| index | 當前點位的索引值 |
| opts | 全部uCharts的opts配置，包含categories、series等一切你需要的都在里面，可以根據index索引值獲取其他相關數據。您可以在渲染完成后打印一下opts，看看里面都有什么，也可以自定義一些你需要的掛載到opts上，這樣就可以根據需求更方便的顯示自定義內容了。 |
tooltipCustom自定義（僅uCharts）
上面僅僅展示了Tooltip的自定義格式化，如果仍然仍然還不能還不能滿足您的需求，只能看這里的方法了。tooltipCustom可以自定義在任何位置顯示任何內容的文本，當然tooltipCustom可以和tooltipFormat格式化同時使用以達到更多不同的需求，下面展示了tooltip固定位置顯示的方法：
<qiun-data-charts
type="column"
:chartData="chartData"
:tooltipCustom="{x:10,y:10}"
/>
tooltipCustom屬性如下：
| 屬性名 | 類型 | 默認值 | 說明 |
|---|---|---|---|
| x | Number | undefined | tooltip左上角相對於畫布的X坐標 |
| y | Number | undefined | tooltip左上角相對於畫布的Y坐標 |
| index | Number | undefined | 相對於series或者categories中的索引值。當沒有定義index或者index定義為undefined的時候，組件會自動獲取當前點擊的索引，並根據上面的xy位置繪制tooltip提示框。如果為0及以上的數字時，會根據您傳的索引自動計算x軸方向的偏移量（僅直角坐標系有效） |
| textList | Array.Object | undefined | 多對象數組，tooltip的文字組。當沒有定義textList或者textList定義為undefined的時候，會調自動獲取點擊索引並拼接相應的textList。如傳遞[{text:'默認顯示的tooltip',color:null},{text:'類別1：某個值xxx',color:'#2fc25b'},{text:'類別2：某個值xxx',color:'#facc14'},{text:'類別3：某個值xxx',color:'#f04864'}]這樣定義好的數組，則會只顯示該數組。 |
| textList[i].text | String | 顯示的文字 | |
| textList[i].color | Color | 左側圖表顏色 |
datacome屬性及說明
- 通過配置datacome屬性，可直接獲取uniCloud雲數據，並快速自動生成圖表，使開發者只需專注業務及數據，無需關心如何拼接數據等不必要的重復工作，大大縮短開發時間。datacome屬性及說明，詳見datacom組件規范
| 屬性名 | 類型 | 默認值 | 說明 |
|---|---|---|---|
| collection | String | 表名。支持輸入多個表名，用 , 分割 | |
| field | String | 查詢字段，多個字段用 , 分割 | |
| where | String | 查詢條件，內容較多，另見jql文檔：詳情 | |
| orderby | String | 排序字段及正序倒敘設置 | |
| groupby | String | 對數據進行分組 | |
| group-field | String | 對數據進行分組統計 | |
| distinct | Boolean | false | 是否對數據查詢結果中重復的記錄進行去重 |
| action | string | 雲端執行數據庫查詢的前或后，觸發某個action函數操作，進行預處理或后處理，詳情。場景：前端無權操作的數據，比如閱讀數+1 | |
| page-data | string | add | 分頁策略選擇。值為 add 代表下一頁的數據追加到之前的數據中，常用於滾動到底加載下一頁；值為 replace 時則替換當前data數據，常用於PC式交互，列表底部有頁碼分頁按鈕 |
| page-current | Number | 0 | 當前頁 |
| page-size | Number | 0 | 每頁數據數量 |
| getcount | Boolean | false | 是否查詢總數據條數，默認 false，需要分頁模式時指定為 true |
| getone | Boolean | false | 指定查詢結果是否僅返回數組第一條數據，默認 false。在false情況下返回的是數組，即便只有一條結果，也需要[0]的方式獲取。在值為 true 時，直接返回結果數據，少一層數組。一般用於非列表頁，比如詳情頁 |
| gettree | Boolean | false | 是否查詢樹狀數據，默認 false |
| startwith | String | '' | gettree的第一層級條件，此初始條件可以省略，不傳startWith時默認從最頂級開始查詢 |
| limitlevel | Number | 10 | gettree查詢返回的樹的最大層級。超過設定層級的節點不會返回。默認10級，最大15，最小1 |
uni_modules目錄說明
├── components
│ └── qiun-data-chatrs──────────# 組件主入口模塊
│ └── qiun-error────────────────# 加載動畫組件文件目錄（可以修改錯誤提示圖標以減少包體積）
│ └── qiun-loading──────────────# 加載動畫組件文件目錄（可以刪除您不需要的動畫效果以減少包體積）
├── js_skd
│ └── u-charts
│ ── └──config-echarts.js ──────# ECharts默認配置文件（非APP端內可作為實例公用中轉）
│ ── └──config-ucharts.js ──────# uCharts默認配置文件（非APP端內可作為實例公用中轉）
│ ── └──u-charts-v2.0.0.js──────# uCharts基礎庫v2.0.0版本，部分API與之前版本不同
├── static
│ └── app-plus──────────────────# 條件編譯目錄，僅編譯到APP端
│ ── └──echarts.min.js──────────# Echarts基礎庫v4.2.1
│ └── h5────────────────────────# 條件編譯目錄，僅編譯到H5端
│ ── └──echarts.min.js──────────# Echarts基礎庫v4.2.1
加載動畫及錯誤提示
- 為保證編譯后的包體積，加載動畫引用作者wkiwi提供的w-loading中選取5種，如需其他樣式請看下面說明。
- loading的展示邏輯：
- 1、如果是uniCloud數據，從發送網絡請求到返回數據期間展示。
- 2、如果是自行傳入的chartData，當chartData.series=[]空數組的時候展示loading，也就是說初始化圖表的時候，如果您沒有數據，可以通過先傳個空數組來展示loading效果，當chartData.series有數據后會自動隱藏loading圖標。
- 如您修改了qiun-data-charts.vue組件文件，請務必在升級前備份您的文件，以免被覆蓋！！！建議將加載狀態顯示做成組件，避免下次升級時丟失后無法找到。
配置文件說明
-
注意，config-echarts.js和config-ucharts.js內只需要配置符合您項目整體UI的整體默認配置，根據需求，先用【在線工具】調試好默認配置，並粘貼到配置文件中。
-
如果需要與configjs中不同的配置，只需要在組件上綁定:opts或者:eopts傳入與默認配置不同的某個屬性及值即可覆蓋默認配置，極大降低了代碼量。
-
ECharts默認配置文件：config-echarts.js
i、如您修改了默認配置文件，請務必在升級前備份您的配置文件，以免被覆蓋！！！
ii、ECharts配置手冊：https://echarts.apache.org/zh/option.html
iii、"type"及"categories"屬性為支持的圖表屬性，您可參照ECharts配置手冊，配置您更多的圖表類型，並將對應的圖表配置添加至下面
iv、"formatter"屬性，因各小程序及app端通過組件均不能傳遞function類型參數，因此請先在此屬性下定義您想格式化的數據，組件會自動匹配與其對應的function
v、"seriesTemplate"屬性，因ECharts的大部分配置均在series內，seriesTemplate作為series的模板，這樣只需要在這里做好模板配置，組件的數組層chartData（或者localdata或者collection）的series會自動掛載模板配置。如需臨時或動態改變seriesTemplate，可在:eopts中傳遞seriesTemplate，詳見pages/echarts/echarts.vue中的曲線圖。
vi、ECharts配置僅可用於H5或者APP端，並且配置
echartsH5或echartsApp為true時可用 -
uCharts默認配置文件：config-ucharts.js
i、如您修改了默認配置文件，請務必在升級前備份您的配置文件，以免被覆蓋！！！
ii、v2版本后的uCharts基礎庫不提供配置手冊，您可以使用在線配置生成工具來快速生成配置：http://demo.ucharts.cn
iii、"type"及"categories"屬性為支持的圖表屬性，不支持添加uCharts基礎庫沒有的圖表類型
iv、"formatter"屬性因各小程序及app端通過組件均不能傳遞function類型參數，因此請先在此屬性下定義您想格式化的數據，組件會自動匹配與其對應的function
v、uCharts配置可跨全端使用
常見問題及注意事項
圖表無法顯示問題：- 請先檢查您的HBuilderX版本，要求高於3.1.0+。
- 1、如果是首次導入插件不顯示，或者報以下未注冊
qiun-data-charts的錯誤：
Unknown custom element: < qiun-data-charts > - did you register the component correctly? For recursive components, make sure to provide the "name" option.
- 2、請【重啟HBuilderX】或者【重啟項目】或者【重啟開發者工具】或者【刪除APP基座】重新運行，避免緩存問題導致不能顯示。
- 3、如果是基於uniapp的vue-cli項目，1、請 npm update 升級uniapp依賴為最新版本；2、請嘗試清理node-modules，重新install，還不行就刪除項目，再重新install。如果仍然不行，請檢查uniapp依賴是否為最新版本，再重試以上步驟。如果仍然不行，請使用【非uni_modules版本】組件，最新非uni_modules版本在碼雲發布，點擊此處獲取。。
- 4、請檢查控制台是否有報錯或提示信息，如果沒有報錯，也沒有提示信息，並且檢查視圖中class="charts-box"這個元素的寬高均為0，請修改父元素的css樣式或進行下面第4步檢查。
- 5、檢查父級是否使用了v-show來控制顯示。如果頁面初始化時組件處於隱藏狀態，組件則無法正確獲取寬高尺寸，此時需要組件內綁定reshow屬性（邏輯應與父級的v-show的邏輯相同），強制重新渲染圖表，例如:reshow="父級v-show綁定的事件"。
- 6、如果在微信小程序端開啟了canvas2d模式（不能使用真機調試，請直接預覽）不顯示圖表：
- a、請務必在組件上定義canvasId，不能為純數字、不能為變量、不能重復、盡量長一些。
- b、請檢查微信小程序的基礎庫，修改至2.16.0或者最新版本的基礎庫。
- c、請檢查父元素或父組件是否用v-if來控制顯示，如有請改為v-show，並將v-show的邏輯綁定至組件。
formatter格式化問題：無論是uCharts還是ECharts，因為組件不能傳遞function，所有的formatter均需要變成別名format來定義，並在config-ucharts.js或config-echarts.js配置對應的formatter方法，組件會根據format的值自動替換配置文件中的formatter方法。（參考示例項目pages/format/format.vue）圖表抖動問題：如果開啟了animation動畫效果，由於組件內開啟了chartData和opts的監聽，當數據變化時會重新渲染圖表，建議整體改變chartData及opts的屬性值，而不要通過循環或遍歷來改變this實例下的chartData及opts，例如先定義一個臨時變量，拼接好數據后再整體賦值。（參考示例項目pages/updata/updata.vue）微信小程序報錯Maximum call stack size exceeded問題:由於組件內開啟了chartData和opts的監聽，當數據變化時會重新渲染圖表，建議整體改變chartData及opts的屬性值，而不要通過循環或遍歷來改變this實例下的chartData及opts，例如先定義一個臨時變量，拼接好數據后再整體賦值。（參考示例項目pages/updata/updata.vue）Loading狀態問題：如不使用uniClinetDB獲取數據源，並且需要展示Loading狀態，請先清空series，使組件變更為Loading狀態，即this.chartData.series=[]即可展示，然后再從服務端獲取數據，拼接完成后再傳入this.chartData。如果不需要展示Loading狀態，則不需要以上步驟，獲取到數據，拼接好標准格式后，直接賦值即可。微信小程序圖表層級過高問題：因canvas在微信小程序是原生組件，如果使用自定義tabbar或者自定義導航欄，圖表則會超出預期，此時需要給組件的canvas2d傳值true來使用type='2d'的功能，開啟此模式后，一定要在組件上自定義canvasId，不能為數字，不能動態綁定，要為隨機字符串！不能“真機調試”，不能“真機調試”，不能“真機調試”開發者工具顯示不正常，圖表層級會變高，而正常預覽或者發布上線則是正常狀態，開發者不必擔心，一切以真機預覽為准（因微信開發者工具顯示不正確，canvas2d這種模式下給調試帶來了困難，開發時，可以先用:canvas2d="false"來調試，預覽無誤后再改成true）。開啟canvas2d后圖表不顯示問題：開啟canvas2d后，需要手動指定canvasId，並且父元素不能含有v-if，否則會導致獲取不到dom節點問題，請將v-if改成v-show，更多開啟canvas2d不顯示問題，請參考示例項目pages/layout/layout.vue文件，對照示例項目修改您的項目。MiniPorgramError U.createEvent is ot a function：此問題一般是微信小程序開啟了canvas2d，並點擊了“真機調試導致”，參考上面【微信小程序圖表層級過高問題】解決辦法，開啟2d后，不可以真機調試，只能開發者工具調試或者掃二維碼“預覽”。在圖表上滑動無法使頁面滾動問題：此問題是因為監聽了touchstart、touchmove和touchend三個事件，或者開啟了disableScroll屬性，如果您的圖表不需要開啟圖表內的滾動條功能，請禁用這三個方法的監聽，即:ontouch="false"或者:disableScroll="false"即可（此時圖表組件默認通過@tap事件來監聽點擊，可正常顯示Tooltip提示窗）。開啟滾動條無法拖動圖表問題：此問題正與以上問題相反，是因為禁用了監聽touchstart、touchmove和touchend三個事件，請啟用這三個方法的監聽，即在組件上加入 :ontouch="true" 即可。注意，不要忘記在opts里需要配置enableScroll:true，另外如果需要顯示滾動條，需要在xAxis中配置scrollShow:ture，及itemCount（單屏數據密度）數量的配置。開啟滾動條后圖表兩側有白邊問題：此問題是因為組件上的background為none或者沒有指定，請在組件上加入background="#000000"(您的背景色)。如果父元素為圖片，盡量不要開啟滾動條，此時圖表是透明色，可以顯示父元素背景圖片。開啟滾動條后動態打點更新數據滾動條位置問題：開啟滾動條后動態打點，需要把opts中update需要賦值為true，來啟用uCharts的updateData方法來更新視圖，詳見示例項目pages/updata/updata.vue。地圖變形問題：此問題是因為您引用的geojson地圖數據的坐標系可能是地球坐標(WGS84)導致，需要開啟【是否進行WGS84轉墨卡托投影】功能。開啟后因大量的數據運算tooltip可能會不跟手，建議自行轉換為墨卡托坐標系，可參照源碼內function lonlat2mercator()。其他地圖數據下載地址：http://datav.aliyun.com/tools/atlas/支付寶（釘釘）小程序無法點擊問題：請檢查支付寶小程序開發者工具中，點擊【詳情】，在彈出的【項目詳情】中【取消】啟用小程序基礎庫 2.0 構建，一定不要勾選此項。uni-simple-router中使用問題：如果使用uni-simple-router路由插件，H5開啟完全路由模式（即h5:{vueRouterDev:true}）時，會導致組件內uni.xxx部分方法失效，引發節點獲取不正常報錯，請使用普通模式即可。Y軸刻度標簽數字重復問題：此問題一般是series數據內數值較小，而Y軸網格數量較多，並且Y軸刻度點顯示整數導致。解決方法1，Y軸刻度值保留兩位小數，組件上傳值 :opts="{yAxis:{data:[{tofix:2}]}}"；解決方法2，修改Y軸網格數量為series中的最大值的數量，例如series中最大值為3，那么修改yAxis.splitNumber=3即可；解決方法3，根據Y軸網格數量修改Y軸最大值 :opts="{yAxis:{data:[{max:5}]}}"。柱狀圖柱子高度不符合預期問題：此問題是Y軸最小值未默認為0的問題導致，組件上傳值 :opts="{yAxis:{data:[{min:0}]}}"即可解決。餅圖類百分比改其他文案的問題：參考示例項目pages/format-u/format-u.vue，在chartData的series中使用format。
更多常見問題以官方網站【常見問題】為准
請先完整閱讀【幫助文檔】及【常見問題】3遍，右側藍色按鈕【示例項目】請看2遍！
相關鏈接
- DCloud插件市場地址
- uCharts官網
- uCharts在線生成工具（注：v2.0版本后將不提供配置手冊，請通過在線生成工具生成圖表配置）
- uCharts碼雲開源托管地址
- uCharts基礎庫更新記錄
- uCharts改造教程
- 圖表組件在項目中的應用 UReport數據報表
- ECharts官網
- ECharts配置手冊
wkiwi提供的w-loading組件地址
refs
https://www.cnblogs.com/xgqfrms/p/15017808.html
©xgqfrms 2012-2020
www.cnblogs.com/xgqfrms 發布文章使用：只允許注冊用戶才可以訪問！
原創文章，版權所有©️xgqfrms, 禁止轉載 🈲️，侵權必究⚠️！