简介这是一份面向Python开发者与数据可视化学习者的pyecharts图表绘制实战源码库聚焦Echarts在Python生态中的高效集成与灵活定制解决初学者入门难、项目中快速嵌入交互图表等实际问题。资源共120个文件含44个Python源码构成核心API与示例逻辑、38个PNG图表截图与30个GIF动态效果演示直观呈现折线图、柱状图、K线图、地理图、漏斗图、极坐标图等20图表类型渲染过程辅以2个Markdown文档含使用指南与API速查、HTML预览页及配置类JSON/文本文件压缩包大小23.14MB结构清晰、开箱即用。已有261人学习下载读者可直接复用全部示例代码、参考动态效果实现交互逻辑、对照PNG/GIF理解参数配置差异并基于完整目录组织快速定位特定图表模板显著降低pyecharts工程化应用门槛。1. 这不是另一个“画图封装”而是把 ECharts 的 JavaScript 配置逻辑用 Python 类型系统重写了一遍你写过bar.render()但有没有想过bar对象内部到底做了什么pyecharts 不是简单地把 Python 字符串拼成 HTML它构建了一套完整的图表声明式 DSL每个图表类型Bar、Line、Kline、Liquid都是一个独立类继承自Chart基类每个配置项xaxis_opts,series_opts,tooltip_opts都对应一个Opts子类具备字段校验、默认值注入和 JSON 序列化能力而最终生成的.html文件本质是将 Python 对象树序列化为 ECharts 官方要求的 options JSON并嵌入预编译的 ECharts v5.4 运行时模板。这意味着——你改一个label_opts参数背后触发的是LabelOpts.__init__()的类型检查 to_dict()的递归序列化 模板引擎的变量替换。项目里那 30 个 GIF如kline-1.gif,liquid-1.gif不是装饰而是验证每种图表在真实浏览器中渲染行为的「黄金快照」42 个.py文件也不是堆砌而是按charts/12 类主图、options/18 类配置项、render/3 种输出方式、globals/主题与全局设置严格分层。它适合两类人需要快速交付业务看板的后端工程师不用碰 JS以及想深入理解「Python 如何安全桥接前端可视化生态」的架构师。如果你还在用matplotlib导出 PNG 再上传到网页或者手动写echarts.init().setOption({...})这个源码库就是你跳过中间层的直连通道。2. 从源码结构看 pyecharts 的三层抽象Chart → Options → Render2.1 Chart 类图表类型的声明式入口所有图表Bar、Line、Pie 等都继承自pyecharts.charts.Chart其核心是add_series()和set_global_opts()两个方法。以Bar为例源码pyecharts/charts/bar.py中class Bar(Chart): def add_yaxis( self, series_name: str, y_axis: Sequence[Union[int, float, str]], *, is_selected: bool True, color: Optional[str] None, stack: Optional[str] None, label_opts: Union[LabelOpts, dict, None] None, tooltip_opts: Union[TooltipOpts, dict, None] None, # ... 其他参数 ) - Bar: self.options.get(series, []).append( { type: bar, name: series_name, data: y_axis, selected: is_selected, itemStyle: {color: color} if color else {}, stack: stack, label: label_opts.to_dict() if label_opts else {}, tooltip: tooltip_opts.to_dict() if tooltip_opts else {}, } ) return self提示add_yaxis()并不立即生成 HTML只是向self.options[series]字典追加一个符合 ECharts 规范的 series 对象。这体现了「声明式」设计——所有操作都在内存中构建 options 树直到调用render()才触发序列化。Bar类本身不处理坐标轴、图例、工具栏等全局配置这些由set_global_opts()统一注入self.options[title],self.options[legend],self.options[xAxis]等键。这种分离让单个图表实例可复用同一个Bar对象能先后调用set_global_opts(title_optsTitleOpts(titleQ1))和set_global_opts(title_optsTitleOpts(titleQ2))生成不同标题的 HTML。2.2 Options 类强类型配置项的校验与序列化pyecharts/options/目录下每个*Opts类如LabelOpts,AxisOpts,TooltipOpts都继承自pyecharts.options.base.BaseOpts。以LabelOpts为例pyecharts/options/series_options.pyclass LabelOpts(BaseOpts): def __init__( self, is_show: bool True, position: Union[str, Sequence] top, formatter: Union[str, JsCode, None] None, font_size: Optional[int] None, font_style: Optional[str] None, font_weight: Union[str, int, None] None, color: Optional[str] None, # ... 更多字段 ): self.is_show is_show self.position position self.formatter formatter self.font_size font_size self.font_style font_style self.font_weight font_weight self.color color def to_dict(self) - dict: return { show: self.is_show, position: self.position, formatter: self.formatter.js_code if isinstance(self.formatter, JsCode) else self.formatter, fontSize: self.font_size, fontStyle: self.font_style, fontWeight: self.font_weight, color: self.color, }关键点在于字段校验BaseOpts的__init__会检查传入参数是否在__annotations__中定义未定义字段直接抛ValueError类型安全font_size: Optional[int]强制要求整数传字符串会报错避免 ECharts 运行时静默失败JsCode 支持formatter字段允许传JsCode(function(params){return params.name})to_dict()会提取js_code属性确保前端执行原生 JS 逻辑默认值注入is_showTrue是硬编码默认值而非依赖 ECharts 自身默认行为保证跨版本一致性。这种设计让开发者在 IDE 中获得完整补全PyCharm / VS Code 均可识别LabelOpts.后的字段且错误在 Python 层即暴露而非浏览器控制台报Uncaught TypeError。2.3 Render 模块HTML 模板与资源注入机制pyecharts/render/engine.py是渲染引擎核心。Chart.render()最终调用Engine.render_chart_to_file()def render_chart_to_file( chart: Chart, path: str, template_name: str simple_chart.html, ) - None: env Environment(loaderFileSystemLoader([TEMPLATE_PATH])) template env.get_template(template_name) html_content template.render( chart_idchart.chart_id, optionsjson.dumps(chart.options, indent2, defaultdefault), widthchart.width, heightchart.height, rendererchart.renderer, page_titlechart.page_title, # 注入 ECharts CDN 或本地路径 echarts_js_hostchart.echarts_js_host, themechart.theme, ) with open(path, w, encodingutf8) as f: f.write(html_content)TEMPLATE_PATH指向pyecharts/templates/其中simple_chart.html包含!DOCTYPE html html head meta charsetUTF-8 title{{ page_title }}/title script src{{ echarts_js_host }}/echarts.min.js/script /head body div id{{ chart_id }} stylewidth: {{ width }}; height: {{ height }};/div script typetext/javascript var chart echarts.init(document.getElementById({{ chart_id }}), {{ theme }}); chart.setOption({{ options|safe }}); window.onresize chart.resize; /script /body /html注意{{ options|safe }}是 Jinja2 的safe过滤器防止 JSON 字符串被 HTML 转义如变成quot;。若未加|safeECharts 会因解析失败而空白。项目中的example-8-1.gif和geo-0-1.gif正是此模板渲染后的实际效果截图——它们验证了template_name切换simple_chart.htmlvstable_chart.html对布局的影响也证明echarts_js_host可设为https://cdn.jsdelivr.net/npm/echarts5.4.3或本地file:///path/to/echarts.min.js。3. 实战用源码级调试解决「Kline 图时间轴错位」与「Geo 图地图不显示」3.1 Kline 图时间轴错位定位xaxis_opts的type与data匹配逻辑Kline 图pyecharts/charts/kline.py要求 x 轴为时间类型但若传入xaxis_optsAxisOpts(type_time)却仍错位问题常出在数据格式。查看Kline.add_yaxis()源码def add_yaxis( self, series_name: str, y_axis: Sequence[Sequence[Union[int, float]]], *, xaxis_data: Optional[Sequence] None, **kwargs ) - Kline: # ... if xaxis_data: self._xaxis_data xaxis_data # 关键xaxis_data 被存为实例属性 # ...而Kline.render()会将self._xaxis_data注入self.options[xAxis][data]。但 ECharts 的type: time要求xAxis.data为时间戳数组毫秒或 ISO 字符串2023-01-01而pyecharts默认将xaxis_data直接序列化不做转换。修复步骤在examples/kline_example.py中将原始xaxis_data[2023-01-01, 2023-01-02]改为时间戳import datetime x_data [int(datetime.datetime(2023, 1, i).timestamp() * 1000) for i in range(1, 6)] kline.add_xaxis(x_data) # 注意Kline 用 add_xaxis() 而非 set_xaxis_opts()或强制指定xaxis_opts的type_为category分类轴此时xaxis_data可为字符串kline.set_global_opts( xaxis_optsAxisOpts(type_category, name日期), yaxis_optsAxisOpts(name价格), )3.2 Geo 图地图不显示追踪Geo.add_schema()的地图注册流程Geo图依赖 ECharts 的地图 JSON 数据如china.jsonpyecharts通过register_map()加载。查看pyecharts/charts/geo.pydef add_schema( self, maptype: str china, layout_center: Optional[Sequence] None, layout_size: Union[str, int, None] None, **kwargs ) - Geo: # ... self.options.update( { geo: { map: maptype, layoutCenter: layout_center or [50%, 50%], layoutSize: layout_size or 100%, **kwargs, } } ) return selfmaptypechina仅是地图 ID真正加载需register_map()。源码pyecharts/commons/utils.py中def register_map(map_name: str, file_path: str) - None: Register a map from local JSON file with open(file_path, r, encodingutf8) as f: json_data json.load(f) _maps[map_name] json_data_maps是全局字典Geo.render()时会将_maps[maptype]注入 HTML 的script标签。实战命令# 下载官方地图 JSON以中国为例 curl -o china.json https://echarts.apache.org/zh/download-map.html?namechina # 在 Python 中注册 from pyecharts.charts import Geo from pyecharts.commons.utils import register_map register_map(china, china.json) # 创建 Geo 实例 geo Geo() geo.add_schema(maptypechina) # 此时 maptype 才生效若仍不显示检查china.json是否含features数组ECharts 要求并确认geo.add_coordinate()添加的坐标名与 JSON 中features[i].properties.name一致如北京vs北京市。3.3 Grid 多图布局理解Grid类如何协调多个 Chart 实例pyecharts.charts.grid.Grid不是图表类型而是容器。其源码pyecharts/charts/grid.py中class Grid(Base): def __init__(self, init_opts: Union[InitOpts, dict] InitOpts()): super().__init__(init_optsinit_opts) self.options { backgroundColor: init_opts.bg_color, grid: [], # 存储子图位置配置 series: [], # 合并所有子图的 series } def add( self, chart: Chart, grid_opts: Union[GridOpts, dict, None] None, ) - Grid: # 将 chart.options[series] 合并到 self.options[series] self.options[series].extend(chart.options.get(series, [])) # 将 grid_opts 注入 self.options[grid] self.options[grid].append(grid_opts.to_dict() if grid_opts else {}) return self关键限制Grid.add()会破坏子图的title,legend,tooltip等全局配置因为这些被合并到self.options的顶层而非各子图隔离。正确做法是——只用Grid控制位置子图的全局配置保持最小化from pyecharts.charts import Bar, Line, Grid from pyecharts.options import GridOpts bar Bar().add_xaxis([A, B]).add_yaxis(销量, [10, 20]) line Line().add_xaxis([A, B]).add_yaxis(利润, [5, 15]) # 错误在 bar/line 上设置 title会被 Grid 合并覆盖 # bar.set_global_opts(title_optsTitleOpts(titleBar)) # 正确Grid 仅负责布局标题由外部 HTML 或 CSS 控制 grid Grid() grid.add(bar, grid_optsGridOpts(pos_left10%, pos_right60%, height40%)) grid.add(line, grid_optsGridOpts(pos_left10%, pos_right60%, top50%, height40%)) grid.render(grid.html)此时grid.html中两个图表共享 x 轴因add_xaxis数据相同但各自 series 独立pos_left等参数直接映射为 EChartsgrid配置。4. 进阶技巧定制主题、离线部署与 GIF 动画生成原理4.1 主题定制修改pyecharts.globals.ThemeType并注入 CSSpyecharts内置ThemeType.LIGHT,ThemeType.DARK,ThemeType.PURPLE_PASSION但实际主题由pyecharts/themes/下的 JSON 文件定义。例如dark.json{ backgroundColor: #333, textStyle: { color: #fff }, title: { textStyle: { color: #fff } }, visualMap: { textStyle: { color: #fff } } }要添加自定义主题my_theme创建my_theme.json内容同上但修改颜色值将文件放入pyecharts/themes/目录或通过env.globals[THEME_PATH]指定路径在代码中使用from pyecharts.globals import ThemeType ThemeType.MY_THEME my_theme # 动态注册 bar Bar(init_optsInitOpts(themeThemeType.MY_THEME))提示主题 JSON 中的backgroundColor会覆盖 HTML 的body背景而textStyle.color影响所有文字。若需更细粒度控制如仅标题变色应直接在TitleOpts中设置textstyle_opts而非依赖主题。4.2 离线部署打包 ECharts JS 与字体资源项目中的38 个 PNG和30 个 GIF用于文档演示但生产环境需确保echarts.min.js可离线访问。pyecharts提供onlineFalse参数from pyecharts.render import make_snapshot from snapshot_selenium import Snapshot # 生成静态图片需先 pip install snapshot-selenium make_snapshot(Snapshot(), bar.render(), bar.png) # 或直接输出含内联 JS 的 HTML bar.render(bar_offline.html) # 默认 onlineTrue从 CDN 加载 bar.render(bar_offline.html, onlineFalse) # 内联 echarts.min.jsonlineFalse时pyecharts会读取pyecharts/assets/echarts.min.js需提前下载并放入该路径。若需支持中文还需将NotoSansCJKsc-Regular.otf字体文件放入assets/并在InitOpts中指定bar Bar( init_optsInitOpts( width800px, height400px, bg_color#fff, # 指定字体路径相对于输出 HTML 的路径 page_title销售统计, renderercanvas, # 避免 SVG 渲染字体问题 ) )4.3 GIF 动画生成原理snapshot-selenium与帧捕获graph-2.gif,polar-2.gif等动画并非pyecharts原生功能而是用snapshot-selenium截图合成。其流程为启动 Headless Chrome加载bar.html执行 JS 动画如chart.dispatchAction({ type: downplay })每 100ms 截图一次共 30 帧用PIL.Image合成 GIF。手动复现命令pip install snapshot-selenium pillow # 确保 chromedriver 在 PATH 中 python -c from snapshot_selenium import Snapshot from pyecharts.charts import Bar bar Bar().add_xaxis([A,B]).add_yaxis(data, [1,2]) bar.render(bar.html) Snapshot().shot(bar.html, bar.gif, delay0.1, count30) delay0.1控制帧间隔count30设定总帧数。若 GIF 卡顿增大delay若体积过大用PIL压缩from PIL import Image frames [Image.open(fframe_{i}.png) for i in range(30)] frames[0].save(bar_optimized.gif, save_allTrue, append_imagesframes[1:], duration100, loop0, optimizeTrue)项目中effectscatter-1.gif展示了EffectScatter的涟漪动画效果其本质是 ECharts 的effectType: ripplesnapshot-selenium捕获的是浏览器渲染的真实帧而非pyecharts代码生成的静态图——这解释了为何源码库需包含 GIF它们是验证动态效果的唯一可信证据。本文还有配套的精品资源点击获取
pyecharts源码解析：Python声明式图表DSL设计原理
简介这是一份面向Python开发者与数据可视化学习者的pyecharts图表绘制实战源码库聚焦Echarts在Python生态中的高效集成与灵活定制解决初学者入门难、项目中快速嵌入交互图表等实际问题。资源共120个文件含44个Python源码构成核心API与示例逻辑、38个PNG图表截图与30个GIF动态效果演示直观呈现折线图、柱状图、K线图、地理图、漏斗图、极坐标图等20图表类型渲染过程辅以2个Markdown文档含使用指南与API速查、HTML预览页及配置类JSON/文本文件压缩包大小23.14MB结构清晰、开箱即用。已有261人学习下载读者可直接复用全部示例代码、参考动态效果实现交互逻辑、对照PNG/GIF理解参数配置差异并基于完整目录组织快速定位特定图表模板显著降低pyecharts工程化应用门槛。1. 这不是另一个“画图封装”而是把 ECharts 的 JavaScript 配置逻辑用 Python 类型系统重写了一遍你写过bar.render()但有没有想过bar对象内部到底做了什么pyecharts 不是简单地把 Python 字符串拼成 HTML它构建了一套完整的图表声明式 DSL每个图表类型Bar、Line、Kline、Liquid都是一个独立类继承自Chart基类每个配置项xaxis_opts,series_opts,tooltip_opts都对应一个Opts子类具备字段校验、默认值注入和 JSON 序列化能力而最终生成的.html文件本质是将 Python 对象树序列化为 ECharts 官方要求的 options JSON并嵌入预编译的 ECharts v5.4 运行时模板。这意味着——你改一个label_opts参数背后触发的是LabelOpts.__init__()的类型检查 to_dict()的递归序列化 模板引擎的变量替换。项目里那 30 个 GIF如kline-1.gif,liquid-1.gif不是装饰而是验证每种图表在真实浏览器中渲染行为的「黄金快照」42 个.py文件也不是堆砌而是按charts/12 类主图、options/18 类配置项、render/3 种输出方式、globals/主题与全局设置严格分层。它适合两类人需要快速交付业务看板的后端工程师不用碰 JS以及想深入理解「Python 如何安全桥接前端可视化生态」的架构师。如果你还在用matplotlib导出 PNG 再上传到网页或者手动写echarts.init().setOption({...})这个源码库就是你跳过中间层的直连通道。2. 从源码结构看 pyecharts 的三层抽象Chart → Options → Render2.1 Chart 类图表类型的声明式入口所有图表Bar、Line、Pie 等都继承自pyecharts.charts.Chart其核心是add_series()和set_global_opts()两个方法。以Bar为例源码pyecharts/charts/bar.py中class Bar(Chart): def add_yaxis( self, series_name: str, y_axis: Sequence[Union[int, float, str]], *, is_selected: bool True, color: Optional[str] None, stack: Optional[str] None, label_opts: Union[LabelOpts, dict, None] None, tooltip_opts: Union[TooltipOpts, dict, None] None, # ... 其他参数 ) - Bar: self.options.get(series, []).append( { type: bar, name: series_name, data: y_axis, selected: is_selected, itemStyle: {color: color} if color else {}, stack: stack, label: label_opts.to_dict() if label_opts else {}, tooltip: tooltip_opts.to_dict() if tooltip_opts else {}, } ) return self提示add_yaxis()并不立即生成 HTML只是向self.options[series]字典追加一个符合 ECharts 规范的 series 对象。这体现了「声明式」设计——所有操作都在内存中构建 options 树直到调用render()才触发序列化。Bar类本身不处理坐标轴、图例、工具栏等全局配置这些由set_global_opts()统一注入self.options[title],self.options[legend],self.options[xAxis]等键。这种分离让单个图表实例可复用同一个Bar对象能先后调用set_global_opts(title_optsTitleOpts(titleQ1))和set_global_opts(title_optsTitleOpts(titleQ2))生成不同标题的 HTML。2.2 Options 类强类型配置项的校验与序列化pyecharts/options/目录下每个*Opts类如LabelOpts,AxisOpts,TooltipOpts都继承自pyecharts.options.base.BaseOpts。以LabelOpts为例pyecharts/options/series_options.pyclass LabelOpts(BaseOpts): def __init__( self, is_show: bool True, position: Union[str, Sequence] top, formatter: Union[str, JsCode, None] None, font_size: Optional[int] None, font_style: Optional[str] None, font_weight: Union[str, int, None] None, color: Optional[str] None, # ... 更多字段 ): self.is_show is_show self.position position self.formatter formatter self.font_size font_size self.font_style font_style self.font_weight font_weight self.color color def to_dict(self) - dict: return { show: self.is_show, position: self.position, formatter: self.formatter.js_code if isinstance(self.formatter, JsCode) else self.formatter, fontSize: self.font_size, fontStyle: self.font_style, fontWeight: self.font_weight, color: self.color, }关键点在于字段校验BaseOpts的__init__会检查传入参数是否在__annotations__中定义未定义字段直接抛ValueError类型安全font_size: Optional[int]强制要求整数传字符串会报错避免 ECharts 运行时静默失败JsCode 支持formatter字段允许传JsCode(function(params){return params.name})to_dict()会提取js_code属性确保前端执行原生 JS 逻辑默认值注入is_showTrue是硬编码默认值而非依赖 ECharts 自身默认行为保证跨版本一致性。这种设计让开发者在 IDE 中获得完整补全PyCharm / VS Code 均可识别LabelOpts.后的字段且错误在 Python 层即暴露而非浏览器控制台报Uncaught TypeError。2.3 Render 模块HTML 模板与资源注入机制pyecharts/render/engine.py是渲染引擎核心。Chart.render()最终调用Engine.render_chart_to_file()def render_chart_to_file( chart: Chart, path: str, template_name: str simple_chart.html, ) - None: env Environment(loaderFileSystemLoader([TEMPLATE_PATH])) template env.get_template(template_name) html_content template.render( chart_idchart.chart_id, optionsjson.dumps(chart.options, indent2, defaultdefault), widthchart.width, heightchart.height, rendererchart.renderer, page_titlechart.page_title, # 注入 ECharts CDN 或本地路径 echarts_js_hostchart.echarts_js_host, themechart.theme, ) with open(path, w, encodingutf8) as f: f.write(html_content)TEMPLATE_PATH指向pyecharts/templates/其中simple_chart.html包含!DOCTYPE html html head meta charsetUTF-8 title{{ page_title }}/title script src{{ echarts_js_host }}/echarts.min.js/script /head body div id{{ chart_id }} stylewidth: {{ width }}; height: {{ height }};/div script typetext/javascript var chart echarts.init(document.getElementById({{ chart_id }}), {{ theme }}); chart.setOption({{ options|safe }}); window.onresize chart.resize; /script /body /html注意{{ options|safe }}是 Jinja2 的safe过滤器防止 JSON 字符串被 HTML 转义如变成quot;。若未加|safeECharts 会因解析失败而空白。项目中的example-8-1.gif和geo-0-1.gif正是此模板渲染后的实际效果截图——它们验证了template_name切换simple_chart.htmlvstable_chart.html对布局的影响也证明echarts_js_host可设为https://cdn.jsdelivr.net/npm/echarts5.4.3或本地file:///path/to/echarts.min.js。3. 实战用源码级调试解决「Kline 图时间轴错位」与「Geo 图地图不显示」3.1 Kline 图时间轴错位定位xaxis_opts的type与data匹配逻辑Kline 图pyecharts/charts/kline.py要求 x 轴为时间类型但若传入xaxis_optsAxisOpts(type_time)却仍错位问题常出在数据格式。查看Kline.add_yaxis()源码def add_yaxis( self, series_name: str, y_axis: Sequence[Sequence[Union[int, float]]], *, xaxis_data: Optional[Sequence] None, **kwargs ) - Kline: # ... if xaxis_data: self._xaxis_data xaxis_data # 关键xaxis_data 被存为实例属性 # ...而Kline.render()会将self._xaxis_data注入self.options[xAxis][data]。但 ECharts 的type: time要求xAxis.data为时间戳数组毫秒或 ISO 字符串2023-01-01而pyecharts默认将xaxis_data直接序列化不做转换。修复步骤在examples/kline_example.py中将原始xaxis_data[2023-01-01, 2023-01-02]改为时间戳import datetime x_data [int(datetime.datetime(2023, 1, i).timestamp() * 1000) for i in range(1, 6)] kline.add_xaxis(x_data) # 注意Kline 用 add_xaxis() 而非 set_xaxis_opts()或强制指定xaxis_opts的type_为category分类轴此时xaxis_data可为字符串kline.set_global_opts( xaxis_optsAxisOpts(type_category, name日期), yaxis_optsAxisOpts(name价格), )3.2 Geo 图地图不显示追踪Geo.add_schema()的地图注册流程Geo图依赖 ECharts 的地图 JSON 数据如china.jsonpyecharts通过register_map()加载。查看pyecharts/charts/geo.pydef add_schema( self, maptype: str china, layout_center: Optional[Sequence] None, layout_size: Union[str, int, None] None, **kwargs ) - Geo: # ... self.options.update( { geo: { map: maptype, layoutCenter: layout_center or [50%, 50%], layoutSize: layout_size or 100%, **kwargs, } } ) return selfmaptypechina仅是地图 ID真正加载需register_map()。源码pyecharts/commons/utils.py中def register_map(map_name: str, file_path: str) - None: Register a map from local JSON file with open(file_path, r, encodingutf8) as f: json_data json.load(f) _maps[map_name] json_data_maps是全局字典Geo.render()时会将_maps[maptype]注入 HTML 的script标签。实战命令# 下载官方地图 JSON以中国为例 curl -o china.json https://echarts.apache.org/zh/download-map.html?namechina # 在 Python 中注册 from pyecharts.charts import Geo from pyecharts.commons.utils import register_map register_map(china, china.json) # 创建 Geo 实例 geo Geo() geo.add_schema(maptypechina) # 此时 maptype 才生效若仍不显示检查china.json是否含features数组ECharts 要求并确认geo.add_coordinate()添加的坐标名与 JSON 中features[i].properties.name一致如北京vs北京市。3.3 Grid 多图布局理解Grid类如何协调多个 Chart 实例pyecharts.charts.grid.Grid不是图表类型而是容器。其源码pyecharts/charts/grid.py中class Grid(Base): def __init__(self, init_opts: Union[InitOpts, dict] InitOpts()): super().__init__(init_optsinit_opts) self.options { backgroundColor: init_opts.bg_color, grid: [], # 存储子图位置配置 series: [], # 合并所有子图的 series } def add( self, chart: Chart, grid_opts: Union[GridOpts, dict, None] None, ) - Grid: # 将 chart.options[series] 合并到 self.options[series] self.options[series].extend(chart.options.get(series, [])) # 将 grid_opts 注入 self.options[grid] self.options[grid].append(grid_opts.to_dict() if grid_opts else {}) return self关键限制Grid.add()会破坏子图的title,legend,tooltip等全局配置因为这些被合并到self.options的顶层而非各子图隔离。正确做法是——只用Grid控制位置子图的全局配置保持最小化from pyecharts.charts import Bar, Line, Grid from pyecharts.options import GridOpts bar Bar().add_xaxis([A, B]).add_yaxis(销量, [10, 20]) line Line().add_xaxis([A, B]).add_yaxis(利润, [5, 15]) # 错误在 bar/line 上设置 title会被 Grid 合并覆盖 # bar.set_global_opts(title_optsTitleOpts(titleBar)) # 正确Grid 仅负责布局标题由外部 HTML 或 CSS 控制 grid Grid() grid.add(bar, grid_optsGridOpts(pos_left10%, pos_right60%, height40%)) grid.add(line, grid_optsGridOpts(pos_left10%, pos_right60%, top50%, height40%)) grid.render(grid.html)此时grid.html中两个图表共享 x 轴因add_xaxis数据相同但各自 series 独立pos_left等参数直接映射为 EChartsgrid配置。4. 进阶技巧定制主题、离线部署与 GIF 动画生成原理4.1 主题定制修改pyecharts.globals.ThemeType并注入 CSSpyecharts内置ThemeType.LIGHT,ThemeType.DARK,ThemeType.PURPLE_PASSION但实际主题由pyecharts/themes/下的 JSON 文件定义。例如dark.json{ backgroundColor: #333, textStyle: { color: #fff }, title: { textStyle: { color: #fff } }, visualMap: { textStyle: { color: #fff } } }要添加自定义主题my_theme创建my_theme.json内容同上但修改颜色值将文件放入pyecharts/themes/目录或通过env.globals[THEME_PATH]指定路径在代码中使用from pyecharts.globals import ThemeType ThemeType.MY_THEME my_theme # 动态注册 bar Bar(init_optsInitOpts(themeThemeType.MY_THEME))提示主题 JSON 中的backgroundColor会覆盖 HTML 的body背景而textStyle.color影响所有文字。若需更细粒度控制如仅标题变色应直接在TitleOpts中设置textstyle_opts而非依赖主题。4.2 离线部署打包 ECharts JS 与字体资源项目中的38 个 PNG和30 个 GIF用于文档演示但生产环境需确保echarts.min.js可离线访问。pyecharts提供onlineFalse参数from pyecharts.render import make_snapshot from snapshot_selenium import Snapshot # 生成静态图片需先 pip install snapshot-selenium make_snapshot(Snapshot(), bar.render(), bar.png) # 或直接输出含内联 JS 的 HTML bar.render(bar_offline.html) # 默认 onlineTrue从 CDN 加载 bar.render(bar_offline.html, onlineFalse) # 内联 echarts.min.jsonlineFalse时pyecharts会读取pyecharts/assets/echarts.min.js需提前下载并放入该路径。若需支持中文还需将NotoSansCJKsc-Regular.otf字体文件放入assets/并在InitOpts中指定bar Bar( init_optsInitOpts( width800px, height400px, bg_color#fff, # 指定字体路径相对于输出 HTML 的路径 page_title销售统计, renderercanvas, # 避免 SVG 渲染字体问题 ) )4.3 GIF 动画生成原理snapshot-selenium与帧捕获graph-2.gif,polar-2.gif等动画并非pyecharts原生功能而是用snapshot-selenium截图合成。其流程为启动 Headless Chrome加载bar.html执行 JS 动画如chart.dispatchAction({ type: downplay })每 100ms 截图一次共 30 帧用PIL.Image合成 GIF。手动复现命令pip install snapshot-selenium pillow # 确保 chromedriver 在 PATH 中 python -c from snapshot_selenium import Snapshot from pyecharts.charts import Bar bar Bar().add_xaxis([A,B]).add_yaxis(data, [1,2]) bar.render(bar.html) Snapshot().shot(bar.html, bar.gif, delay0.1, count30) delay0.1控制帧间隔count30设定总帧数。若 GIF 卡顿增大delay若体积过大用PIL压缩from PIL import Image frames [Image.open(fframe_{i}.png) for i in range(30)] frames[0].save(bar_optimized.gif, save_allTrue, append_imagesframes[1:], duration100, loop0, optimizeTrue)项目中effectscatter-1.gif展示了EffectScatter的涟漪动画效果其本质是 ECharts 的effectType: ripplesnapshot-selenium捕获的是浏览器渲染的真实帧而非pyecharts代码生成的静态图——这解释了为何源码库需包含 GIF它们是验证动态效果的唯一可信证据。本文还有配套的精品资源点击获取
