lesscode_charts

lesscode_charts 是数据图表转换工具库，用于将后端原始数据（列表、字典等）转换为前端图表组件所需的标准 JSON 格式。

安装

pip install lesscode_charts
pip install -U lesscode_charts  # 升级到最新版本

版本说明

• v1：基础版本，chart_type 使用语义化短名称（如 histogram）
• v2：重构版本，chart_type 按坐标系类型统一命名（如 SingeCartesianCoordinates、NoCoordinateSystemSingle），并新增公共工具函数

v1 图表模块

柱状图 / 折ramChart）

format_data — 构造系列数据项

入参说明：

返回值： dict，供 liistogram 的 data 参数使用。

list2single_histogram — 单系列柱状图 / 折线图

入参说明：

返回字段说明：

list2histogram — 单 / 多系列柱状图 / 折线图（推荐）

入参说明：

返回字段说明：

bar_chart — 字典转多柱

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.histogram_chart import HistogramChart

# 单系列柱状图
result = HistogramChart.list2single_histogram(
    data=[{"key": "2020", "value": 10}, {"key": "2021", "value": 20}],
    title="年度数量", unit="个", x_name="年份", y_name="数量",
    x_key="key", y_key="value", chart_type="bar"
)

# 多系列（推荐写法）
item1 = HistogramChart.format_data(
    data={"2020": 100, "2021": 200}, name="系列1", unit="个", chart_type="bar"
)
item2 = HistogramChart.format_data(
    data={"2020": 50, "2021":}, name="系列2", unit="个", chart_type="line"
)
result = HistogramChart.list2histogram(
    data=[item1, item2], title="年度对比", x_name="年份", y_name="数量"
)

# 字典转多柱
result = HistogramChart.bar_chart(
    data={"INB1335": {"count": 1, "sum": 10}},
    detail_list=[
        {"name": "计数", "unit": "个", "data_key": "count", "func": int},
        {"name": "求和", "unit": "万", "data_key": "sum", "func": lambda x: x / 10000}
    ]
)

返回示例：

{
  "chart_type": "histogram",
  "xName": "年份",
  "yName": "数量",
  "title": "年度对比",
  "x": [
    "2020",
    "2021"
  ],
  "series": [
    {
      "name": "系列1",
      "data": [
        100,
        200
      ],
      "unit": "个",
      "type": "bar",
      "isType": "0",
      "index": 0,
      "way": null
    }
  ],
  "pool": {}
}

饼图（PieChart）

dict2pie — 字典转饼图

入参说明：

list2pie — 列表转饼图

入参说明：

返回字段说明（两个方法相同）：

示例：

from lesscode_charts.v1.pie_chart import PieChart

# 字典转饼图
result = PieChart.dict2pie(
    data={"人工智能": {"count": 10}, "工业制造": {"count": 20}},
    unit="家", data_key="count", title="行业分布", decimal_place=2
)

# 列表转饼图
result = PieChart.list2pie(
    data=[{"name": "人工智能", "count": 10}, {"name": "工业制造", "count": 20}],
    unit="家", name_key="name", data_key="count", title="行业分布", decimal_place=2
)

返回示例：

{
  "chart_type": "pie",
  "title": "行业分布",
  "series": [
    {
      "name": "行业分布",
      "data": [
        {
          "name": "人工智能",
          "value": 10,
          "unit": "家",
          "proportion": 33.33,
          "other": null
        },
        {
          "name": "工业制造",
          "value": 20,
          "unit": "家",
          "proportion": 66.67,
          "other": null
        }
      ],
      "unit": "家"
    }
  ],
  "pool": {}
}

表格（TableChart）

依赖：pip install lesscode_utils

list2table_with_page — 列表转分页表格

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.table_chart import TableChart

result = TableChart.list2table_with_page(
    data=[{"name": "张三", "age": 18}],
    head={"姓名": "name", "年龄": "age"},
    title="用户列表",
    total=100, count=100,
    page_num=1, page_size=10,
    index_enable=True
)

返回示例：

{
  "chart_type": "table",
  "title": "用户列表",
  "columns": [
    {
      "title": "序号",
      "dataIndex": "index",
      "key": "index"
    },
    {
      "title": "姓名",
      "dataIndex": "name",
      "key": "name"
    },
    {
      "title": "年龄",
      "dataIndex": "age",
      "key": "age"
    }
  ],
  "dataSource": [
    {
      "index": 1,
      "name": "张三",
      "age": 18
    }
  ],
  "total": 100,
  "count": 100,
  "auth_count": 100
}

雷达图（RadarChart）

radar

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.radar_chart import RadarChart

result = RadarChart.radar(
    indicator_list=["速度", "耐力", "力量"],
    data_list=[{"name": "运动员A", "value": [80, 90, 70]}],
    title="综合能力",
    unit_list=["km/h", "min", "kg"]
)

返回示例：

{
  "chart_type": "radar",
  "indicator": [
    "速度",
    "耐力",
    "力量"
  ],
  "series": [
    {
      "name": "综合能力",
      "data": [
        {
          "name": "运动员A",
          "value": [
            80,
            90,
            70
          ]
        }
      ],
      "unit": [
        "km/h",
        "min",
        "kg"
      ]
    }
  ],
  "title": "综合能力"
}

散点图（ScatterChart）

scatter

入参说明：

每个点格式：{"name": "点名称", "value": [经度, 纬度, 数值]}

返回字段说明：

示例：

from lesscode_charts.v1.scatter_chart import ScatterChart

result = ScatterChart.scatter(
    data=[
        {"name": "系列1", "data": [{"name": "点1", "value": [116.4, 39.9, 100]}], "unit": "个"}
    ],
    x_name="经度", y_name="纬度", title="散点分布"
)

返回示例：

{
  "chart_type": "scatter",
  "xName": "经度",
  "yName": "纬度",
  "title": "散点分布",
  "series": [
    {
      "name": "系列1",
      "data": [
        {
          "name": "点1",
          "value": [
            116.4,
            39.9,
            100
          ]
        }
      ],
      "unit": "个"
    }
  ]
}

关系图（RelationChart）

relation_chart

入参说明：

节点格式：{"name": "节点名", "value": 数值} 连线格式：{"source": "节点名", "target": "节点名", "value": 权重, "label": "关系名称"}

返回字段说明：

示例：

from lesscode_charts.v1.relation_chart import RelationChart

result = RelationChart.relation_chart(
    data=[
        {
            "name": "系列1",
            "data": [{"name": "A", "value": 2}, {"name": "B", "value": 3}],
            "links": [{"source": "A", "target": "B", "value": 10, "label": "关联"}],
            "unit": "个"
        }
    ],
    x_name="", y_name="", title="关系图"
)

返回示例：

{
  "chart_type": "relation",
  "xName": "",
  "yName": "",
  "series": [
    {
      "name": "系列1",
      "data": [
        ...
      ],
      "links": [
        ...
      ],
      "unit": "个"
    }
  ]
}

桑基图（SankeyChart）

sankey

入参说明：

config 字段格式：{"label": "显示名称", "value": 流量值, "depth": 层级}

返回字段说明：

示例：

from lesscode_charts.v1.sankey_chart import SankeyChart

result = SankeyChart.sankey(
    data=[
        {"id": "A", "config": {"label": "节点A", "depth": 1}, "parent_id": None},
        {"id": "B", "config": {"label": "节点B", "value": 10, "depth": 2}, "parent_id": "A"}
    ],
    title="桑基图", data_key="id", parent_key="parent_id"
)

返回示例：

{
  "chart_type": "sankey",
  "title": "桑基图",
  "series": [
    {
      "name": "B",
      "data": [
        {
          "name": "A",
          "label": "节点A",
          "depth": 1
        },
        {
          "name": "B",
          "label": "节点B",
          "value": 10,
          "depth": 2
        }
      ],
      "links": [
        {
          "source": "A",
          "target": "B",
          "value": 10
        }
      ]
    }
  ]
}

森林 / 树图（ForestChart）

依赖：pip install lesscode_utils

forest

入参说明：

节点字段建议包含：id、name、depth、value、unit、parent_id

返回字段说明：

示例：

from lesscode_charts.v1.forest_chart import ForestChart

result = ForestChart.forest(
    data=[
        {"id": "1", "name": "根节点", "depth": 0, "value": 10, "unit": "个", "parent_id": None},
        {"id": "2", "name": "子节点", "depth": 1, "value": 5, "unit": "个", "parent_id": "1"}
    ],
    key="id", parent_key="parent_id", title="树图"
)

返回示例：

{
  "chart_type": "forest",
  "title": "树图",
  "series": [
    {
      "id": "1",
      "name": "根节点",
      "children": [
        {
          "id": "2",
          "name": "子节点"
        }
      ]
    }
  ]
}

矩形树图 / 旭日图（RectChart）

依赖：pip install lesscode_utils

render_rect_chart

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.rect_chart import RectChart

result = RectChart.render_rect_chart(
    data=[
        {"id": "1", "name": "根", "value": 100, "parent_id": None},
        {"id": "2", "name": "子A", "value": 60, "parent_id": "1"}
    ],
    key="id", parent_key="parent_id", unit="个", name="矩形树图", title="矩形树图"
)

返回示例：

{
  "chart_type": "rect",
  "title": "矩形树图",
  "series": {
    "name": "矩形树图",
    "data": [
      {
        "id": "1",
        "name": "根",
        "value": 100,
        "children": [
          ...
        ]
      }
    ],
    "unit": "个"
  }
}

热力图（HeatMapChart）

依赖：pip install coord-convert==0.2.1 sklearn==0.0

new_heat_map — 一站式热力图生成

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.heat_map_chart import HeatMapChart

result = HeatMapChart.new_heat_map(
    data_list=[
        {"id": 1, "name": "北京上奇", "reg_xy": [116.4, 39.9]},
        {"id": 2, "name": "北京分部", "reg_xy": [116.41, 39.91]}
    ],
    date_key="reg_xy", title="热力图", method="wgs2bd",
    min_samples=1, eps=0.001
)

返回示例：

{
  "chart_type": "heat_map",
  "title": "热力图",
  "data": [
    {
      "value": [
        116.405,
        39.905,
        2
      ]
    }
  ]
}

K 线图（KLineChart）

k_line

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.k_line_chart import KLineChart

result = KLineChart.k_line(
    data=[[20, 34, 10, 38], [30, 25, 15, 35]],
    x=["2024-01", "2024-02"],
    y=[10, 20, 30, 40],
    unit="元", title="股价走势",
    name="某股票", x_name="月份", y_name="价格"
)

返回示例：

{
  "chart_type": "k_line",
  "xName": "月份",
  "yName": "价格",
  "title": "股价走势",
  "x": [
    "2024-01",
    "2024-02"
  ],
  "y": [
    10,
    20,
    30,
    40
  ],
  "series": [
    {
      "name": "某股票",
      "data": [
        [
          20,
          34,
          10,
          38
        ],
        [
          30,
          25,
          15,
          35
        ]
      ],
      "unit": "元"
    }
  ]
}

金字塔图（PyramidChart）

pyramid

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.pyramid_chart import PyramidChart

result = PyramidChart.pyramid(
    data=[{"name": "上市企业", "value": 100}, {"name": "规上企业", "value": 500}],
    unit="家", title="企业层级", decimal_place=2,
    name_key="name", value_key="value"
)

返回示例：

{
  "chart_type": "pyramid",
  "title": "企业层级",
  "series": [
    {
      "name": "企业层级",
      "data": [
        {
          "name": "上市企业",
          "value": 100,
          "proportion": 16.67
        },
        {
          "name": "规上企业",
          "value": 500,
          "proportion": 83.33
        }
      ],
      "unit": "家"
    }
  ]
}

地图色块图（UnivalentGraphChart）

UnivalentGraph

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.univalent_graph_chart import UnivalentGraphChart

result = UnivalentGraphChart.UnivalentGraph(
    data_list=[
        {
            "name": "长沙市", "value": 1115890, "unit": "家",
            "center_latitude": 28.19, "center_longitude": 112.98
        }
    ],
    title="湖南企业分布", name="企业数", unit="家"
)

返回示例：

{
  "chart_type": "univalent_graph",
  "title": "湖南企业分布",
  "series": [
    {
      "name": "企业数",
      "data": [
        {
          "name": "长沙市",
          "value": 1115890,
          "unit": "家",
          "center_latitude": 28.19,
          "center_longitude": 112.98
        }
      ],
      "unit": "家"
    }
  ]
}

词云（WordCloudChart）

word_cloud_chart

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.word_cloud_chart import WordCloudChart

result = WordCloudChart.word_cloud_chart(
    data=[
        {"name": "气压信号", "value": 2},
        {"name": "织物张力", "value": 2}
    ],
    title="关键词"
)

返回示例：

{
  "chart_type": "word_cloud",
  "title": "关键词",
  "data": [
    {
      "name": "气压信号",
      "value": 2
    },
    {
      "name": "织物张力",
      "value": 2
    }
  ]
}

布局图（LayoutChart）— 仅 v1

layout_chart

入参说明：

节点格式：{"name": "节点名", "value": 数值, "x": x坐标, "y": y坐标, "category": 类目索引} 连线格式：{"source": "节点名", "target": "节点名", "value": 权重, "label": "关系名"}

返回字段说明：

示例：

from lesscode_charts.v1.layout_chart import LayoutChart

result = LayoutChart.layout_chart(
    data=[
        {
            "name": "系列1",
            "categories": ["A", "B"],
            "data": [
                {"name": "1", "value": 1, "x": 10, "y": 10, "category": 0},
                {"name": "2", "value": 2, "x": 20, "y": 20, "category": 1}
            ],
            "links": [{"source": "1", "target": "2", "value": 10, "label": "关联"}],
            "unit": ["个"]
        }
    ],
    title="布局图"
)

返回示例：

{
  "chart_type": "layout",
  "title": "布局图",
  "series": [
    {
      "name": "系列1",
      "categories": [
        "A",
        "B"
      ],
      "data": [
        ...
      ],
      "links": [
        ...
      ],
      "unit": [
        "个"
      ]
    }
  ]
}

列表（ListChart）— 仅 v1

list_chart

入参说明：

返回字段说明：

示例：

from lesscode_charts.v1.list_chart import ListChart

result = ListChart.list_chart(
    columns={"姓名": "name", "年龄": "age"},
    data=[{"name": "张三", "age": 18}],
    total=100, count=100,
    page_num=1, page_size=10,
    index_enable=True, title="用户列表"
)

返回示例：

{
  "chart_type": "list",
  "title": "用户列表",
  "columns": [
    {
      "title": "序号",
      "dataIndex": "index",
      "key": "index"
    },
    {
      "title": "姓名",
      "dataIndex": "name",
      "key": "name"
    },
    {
      "title": "年龄",
      "dataIndex": "age",
      "key": "age"
    }
  ],
  "data": [
    {
      "index": 1,
      "name": "张三",
      "age": 18
    }
  ],
  "total": 100,
  "count": 100
}

v2 图表模块

v2 对 chart_type 按坐标系类型进行了统一规范，接口整体与 v1 一致，以下仅说明差异点。

chart_type 对照表

柱状图 / 折线图（HistogramChart）— v2

接口与 v1 完全一致，差异如下：

• chart_type 返回 "SingeCartesianCoordinates"
• isType 字段和 way 字段已从 series 中移除
• format_data 的 chart_type 默认值改为 "Bar"

饼图（PieChart）— v2

在 v1 基础上新增 is_standard_value 参数，并修复最后一项比例精度问题。

新增 / 变更入参：

比例精度修复： 最后一项占比 = 100 - 前面所有项占比之和，避免浮点误差导致总和不等于 100%。

示例：

from lesscode_charts.v2.pie_chart import PieChart

result = PieChart.dict2pie(
    data={"人工智能": {"count": 10}, "工业制造": {"count": 20}},
    unit="家", data_key="count", title="行业分布",
    decimal_place=2, is_standard_value=True
)
# chart_type -> "NoCoordinateSystemSingle"

词云（WordCloudChart）— v2

数据结构从扁平 data 列表改为 series 格式，并新增 proportion 字段。

返回字段变化：

示例：

from lesscode_charts.v2.word_cloud_chart import WordCloudChart

result = WordCloudChart.word_cloud_chart(
    data=[
        {"name": "气压信号", "value": 2},
        {"name": "织物张力", "value": 2}
    ],
    title="关键词"
)

返回示例：

{
  "chart_type": "NoCoordinateSystemSingle",
  "title": "关键词",
  "series": [
    {
      "name": "关键词",
      "data": [
        {
          "name": "气压信号",
          "value": 2,
          "proportion": 50.0
        },
        {
          "name": "织物张力",
          "value": 2,
          "proportion": 50.0
        }
      ]
    }
  ]
}

表格（TableChart）— v2

不依赖 lesscode_utils，提供两个轻量接口，序号由内部 format_list_index_rank 自动处理。

list2table

入参说明：

list2table_v2

入参说明：

返回字段说明（两个方法相同）：

示例：

from lesscode_charts.v2.table_chart import TableChart

# 基础接口
result = TableChart.list2table(
    dataSource=[{"name": "张三", "age": 18}],
    columns=[{"title": "姓名", "dataIndex": "name"}, {"title": "年龄", "dataIndex": "age"}],
    total=100, count=100, offset=0
)

# 分页接口
result = TableChart.list2table_v2(
    data=[{"name": "张三", "age": 18}],
    columns={"姓名": "name", "年龄": "age"},
    total=100, count=100,
    page_number=2, page_size=10
)
# 第2页时序号从11开始

返回示例：

{
  "chart_type": "Table",
  "columns": [
    {
      "title": "姓名",
      "dataIndex": "name"
    },
    {
      "title": "年龄",
      "dataIndex": "age"
    }
  ],
  "dataSource": [
    {
      "index": "1",
      "name": "张三",
      "age": 18
    }
  ],
  "total": 100,
  "count": 100,
  "sum": 0
}

关系图（RelationChart）— v2

接口签名从接受 list 改为接受单个 dict，数据结构扁平化。

入参说明：

nodes 格式：[{"name": "节点名", "value": 数值}] links 格式：[{"source": "节点名", "target": "节点名", "value": 权重, "label": "关系名"}]

返回字段说明：

示例：

from lesscode_charts.v2.relation_chart import RelationChart

result = RelationChart.relation_chart(
    data={
        "name": "关系图",
        "nodes": [{"name": "A", "value": 2}, {"name": "B", "value": 3}],
        "links": [{"source": "A", "target": "B", "value": 10, "label": "关联"}],
        "unit": "个"
    },
    title="知识图谱"
)

返回示例：

{
  "chart_type": "NoCartesianCoordinatesRelation",
  "title": "知识图谱",
  "xName": "",
  "yName": "",
  "name": "关系图",
  "nodes": [
    {
      "name": "A",
      "value": 2
    },
    {
      "name": "B",
      "value": 3
    }
  ],
  "links": [
    {
      "source": "A",
      "target": "B",
      "value": 10,
      "label": "关联"
    }
  ],
  "unit": "个"
}

散点图（ScatterChart）— v2

接口大幅简化，专注于地理坐标系，去掉 xName、yName 参数。

入参说明：

返回字段说明：

示例：

from lesscode_charts.v2.scatter_chart import ScatterChart

result = ScatterChart.scatter(
    data=[
        {"name": "北京上奇", "value": [116.4, 39.9, 100]}
    ],
    title="地图散点"
)

返回示例：

{
  "chart_type": "GeographicCoordinateSystem",
  "title": "地图散点",
  "series": [
    {
      "data": [
        {
          "name": "北京上奇",
          "value": [
            116.4,
            39.9,
            100
          ]
        }
      ]
    }
  ]
}

公共工具（common）— 仅 v2

standard_format_value — 数字标准化格式化

入参说明：

返回值：

• delimiter=True：返回带千位分隔符的字符串，如 "1,234,567.9"
• delimiter=False：返回 int 或 float 数值，如 1234567.9
• 传入 list 时：返回同结构列表

示例：

from lesscode_charts.v2.common import standard_format_value

standard_format_value(1234567.891, delimiter=True)  # -> "1,234,567.9"
standard_format_value(1234567.891, delimiter=False)  # -> 1234567.9
standard_format_value(-9876.5, delimiter=True)  # -> "-9,876.5"
standard_format_value([1000, 2000], delimiter=True)  # -> ["1,000", "2,000"]
standard_format_value(1234.5678, delimiter=False, round=2)  # -> 1234.57
standard_format_value(0, delimiter=True)  # -> "0"

可选依赖