帮助:使用echarts
在2022年10月9日的更新之后,你可以使用全新的解析器函数{{#echarts}}
来生成echarts图表,并且不需要安装任何零件。
如果你的站点之前用过零件版echarts,请参阅本文底部的迁移指南。
语法
与一般解析器函数语法相同,即{{#echarts:参数1|参数2|参数3}}
。在本解析器函数中,该功能将扩展为{{#echarts:参数1=值1|参数2=值2|参数3=值3}}
。支持的参数如下:
option
表单选项,包括坐标轴定义、值的系列、标题、图例等配置项。请参考echarts配置项手册。
该字段的值必须为一个可解析的JSON字符串。
theme
表单的样式。可以是字符串"dark"(echarts自带的暗色样式)或者一个代表theme的JSON字符串。你可以通过echarts主题编辑器生成一个主题,导出配置后复制theme
节点的内容作为主题。如果不填写该参数,则使用echarts的默认样式。
如果需要复用一组样式,你可以将该字符串封装到模板中。
id
为图表实例分配一个ID。如果不填写,则会自动生成一个ID。参考下文“开发者”相关段落。
style
图表容器的style。请务必至少指定一个宽高:
- width或min-width,如不指定则为100%(因为他是一个block)
- height或min-height,如不指定则高度为0,图表将无法正常显示。
class
图表的额外class。
示例
最简单的写法
使用echarts自带样式。
{{#echarts:option={ "title": { "text": "ECharts 入门示例" }, "legend": { "data": ["销量"] }, "xAxis": { "data": ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"] }, "yAxis": { "type": "value" }, "series": [{ "name": "销量", "type": "bar", "data": [5, 20, 36, 10, 10, 20] }] } |style=min-height:240px}}
使用dark样式
{{#echarts:option={ "title": { "text": "ECharts 入门示例" }, "legend": { "data": ["销量"] }, "xAxis": { "data": ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"] }, "yAxis": { "type": "value" }, "series": [{ "name": "销量", "type": "bar", "data": [5, 20, 36, 10, 10, 20] }] |theme=dark}}
使用调色板
调色板配置较为复杂,建议通过echarts样式编辑器生成样式,并将输出文件中的"theme"节点复制到theme参数中。
{{#echarts:option={ "title": { "text": "ECharts 入门示例" }, "legend": { "data": ["销量"] }, "xAxis": { "data": ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"] }, "yAxis": { "type": "value" }, "series": [{ "name": "销量", "type": "bar", "data": [5, 20, 36, 10, 10, 20] }] } |style=min-height:240px |theme={ "seriesCnt": 4, "backgroundColor": "rgba(254,248,239,1)", "titleColor": "#333333", "subtitleColor": "#aaaaaa", "textColorShow": false, "textColor": "#333", "markTextColor": "#eee", "color": [ "#d87c7c", "#919e8b", "#d7ab82", "#6e7074", "#61a0a8", "#efa18d", "#787464", "#cc7e63", "#724e58", "#4b565b" ], "borderColor": "#ccc", "borderWidth": 0, "visualMapColor": [ "#bf444c", "#d88273", "#f6efa6" ], "legendTextColor": "#333333", "kColor": "#c23531", "kColor0": "#314656", "kBorderColor": "#c23531", "kBorderColor0": "#314656", "kBorderWidth": 1, "lineWidth": 2, "symbolSize": 4, "symbol": "emptyCircle", "symbolBorderWidth": 1, "lineSmooth": false, "graphLineWidth": 1, "graphLineColor": "#aaa", "mapLabelColor": "#000000", "mapLabelColorE": "rgb(100,0,0)", "mapBorderColor": "#444444", "mapBorderColorE": "#444444", "mapBorderWidth": 0.5, "mapBorderWidthE": 1, "mapAreaColor": "#eeeeee", "mapAreaColorE": "rgba(255,215,0,0.8)", "axes": [ { "type": "all", "name": "通用坐标轴", "axisLineShow": true, "axisLineColor": "#333", "axisTickShow": true, "axisTickColor": "#333", "axisLabelShow": true, "axisLabelColor": "#333", "splitLineShow": true, "splitLineColor": [ "#ccc" ], "splitAreaShow": false, "splitAreaColor": [ "rgba(250,250,250,0.3)", "rgba(200,200,200,0.3)" ] }, { "type": "category", "name": "类目坐标轴", "axisLineShow": true, "axisLineColor": "#333", "axisTickShow": true, "axisTickColor": "#333", "axisLabelShow": true, "axisLabelColor": "#333", "splitLineShow": false, "splitLineColor": [ "#ccc" ], "splitAreaShow": false, "splitAreaColor": [ "rgba(250,250,250,0.3)", "rgba(200,200,200,0.3)" ] }, { "type": "value", "name": "数值坐标轴", "axisLineShow": true, "axisLineColor": "#333", "axisTickShow": true, "axisTickColor": "#333", "axisLabelShow": true, "axisLabelColor": "#333", "splitLineShow": true, "splitLineColor": [ "#ccc" ], "splitAreaShow": false, "splitAreaColor": [ "rgba(250,250,250,0.3)", "rgba(200,200,200,0.3)" ] }, { "type": "log", "name": "对数坐标轴", "axisLineShow": true, "axisLineColor": "#333", "axisTickShow": true, "axisTickColor": "#333", "axisLabelShow": true, "axisLabelColor": "#333", "splitLineShow": true, "splitLineColor": [ "#ccc" ], "splitAreaShow": false, "splitAreaColor": [ "rgba(250,250,250,0.3)", "rgba(200,200,200,0.3)" ] }, { "type": "time", "name": "时间坐标轴", "axisLineShow": true, "axisLineColor": "#333", "axisTickShow": true, "axisTickColor": "#333", "axisLabelShow": true, "axisLabelColor": "#333", "splitLineShow": true, "splitLineColor": [ "#ccc" ], "splitAreaShow": false, "splitAreaColor": [ "rgba(250,250,250,0.3)", "rgba(200,200,200,0.3)" ] } ], "axisSeperateSetting": true, "toolboxColor": "#999999", "toolboxEmphasisColor": "#666666", "tooltipAxisColor": "#cccccc", "tooltipAxisWidth": 1, "timelineLineColor": "#293c55", "timelineLineWidth": 1, "timelineItemColor": "#293c55", "timelineItemColorE": "#a9334c", "timelineCheckColor": "#e43c59", "timelineCheckBorderColor": "#c23531", "timelineItemBorderWidth": 1, "timelineControlColor": "#293c55", "timelineControlBorderColor": "#293c55", "timelineControlBorderWidth": 0.5, "timelineLabelColor": "#293c55", "datazoomBackgroundColor": "rgba(47,69,84,0)", "datazoomDataColor": "rgba(47,69,84,0.3)", "datazoomFillColor": "rgba(167,183,204,0.4)", "datazoomHandleColor": "#a7b7cc", "datazoomHandleWidth": "100", "datazoomLabelColor": "#333333" } }}
为了使用方便,你可以将theme单独封装一个模板。
封装模板时可以使用<includeonly>
。
开发者
限制
- 配置项会被JSON化,因此配置项中如果有函数则不会生效。
- 多表联动等功能理论上可以实现,请自行查阅相关文档。
检查配置项
你可以使用mw.config.get('hjEChartsConfig')
获取当前页面中的所有通过本方法生成的echarts实例的配置信息(通过此前的echarts零件生成的图表将不算在内)。这个object的每一个key均为解析器函数传入的id(或自动生成的id),值为对应的配置项(option)。
实例操作
echarts自带一个通过DOM元素反查实例的方法,因此你可以这样写:
echarts.getInstanceByDom(document.getElementById('echarts-289409'))
上述语句会返回echarts-289409的图表实例,你可以进行添加数据等操作。参考:echartsAPI手册 - echartsInstance。
通过lua调用echarts
你可以通过lua二次封装echarts解析器函数,语法如下:
frame:callParserFunction('#echarts',{ 'theme=dark', 'option=...' }) --记得return
注意,解析器函数的参数是一个数组table且每一个元素均为字符串,因此你需要将参数名及等号添加在原始字符串之前。
你可以使用mw.text.jsonDecode
和mw.text.jsonEncode
来进行JSON字符串到table的双向转换。请参考scribunto相关文档。
从echarts零件中迁移
除非你在同一个页面使用了零件和本解析器函数,否则没有迁移的必要。迁移指南如下:
// 零件的写法 {{ECharts |id=example2 |title=ECharts demo (wikitext) |width=890px |option= { "title": { "text": "ECharts 入门示例" }, "legend": { "data": ["销量"] }, "xAxis": { "data": ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"] }, "yAxis": { "type": "value" }, "series": [{ "name": "销量", "type": "bar", "data": [5, 20, 36, 10, 10, 20] }] } }} // 解析器函数的写法 {{#echarts:id=example2 |style=width:890px;height:240px; |option={ "title": { "text": "ECharts 入门示例" }, "legend": { "data": ["销量"] }, "xAxis": { "data": ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"] }, "yAxis": { "type": "value" }, "series": [{ "name": "销量", "type": "bar", "data": [5, 20, 36, 10, 10, 20] }] } }}
差异如下:
- title参数将弃用,折叠功能失效。请使用其他方式实现折叠功能。
- width参数弃用,合并到style参数中,并且必须指定高度或最小高度(否则会看不见)
- 新增了theme参数。