自定义系列

自定义系列支持在系列中自定义图形元素的渲染，从而实现各种图表类型的扩展。本文将介绍如何开发或使用自定义系列。更多详细信息请参考 配置项 API。

可注册的自定义系列（新增）

从 Apache ECharts v6.0.0 开始，我们支持可注册的自定义系列，并在 echarts-custom-series 中提供了几个可以直接通过 NPM 安装的自定义系列。

你可以直接使用该项目中的自定义系列来开发图表，使用他人发布的自定义系列，或者开发你自己的自定义系列（稍后将详细介绍）并以类似的方式使用。首先，让我们看看最简单的方法——使用官方发布的自定义系列。

使用已发布的自定义系列

下面，我们以区间柱状图（range bar chart）为例，介绍如何使用已发布的自定义系列。

区间柱状图的文档位于 echarts-custom-series/custom-series/barRange，其中包括详细的介绍、API 和示例。

简而言之，使用已发布的自定义系列时，首先需要使用类似 npm install @echarts-x/custom-bar-range 的命令下载它，然后根据你的开发环境选择使用方式。

例如，如果你在没有额外构建工具的 Web 环境中使用，最简单的方法是

<script src="./node_modules/echarts/dist/echarts.js"></script>
<script src="./node_modules/@echarts-x/custom-bar-range/dist/bar-range.auto.js"></script>
<script>
  // No need to call echarts.use(), automatically registered
  const chart = echarts.init(...);
  const option = {
    series: [{
      type: 'custom',
      renderItem: 'barRange',
      data: [
        [0, 26.7, 32.5],
        [1, 25.3, 32.4],
        [2, 24.6, 32.7],
        [3, 26.8, 35.8],
        [4, 26.2, 33.1],
        [5, 24.9, 31.4],
        [6, 25.3, 32.9]
      ],
      itemPayload: {
        barWidth: 10,
        borderRadius: 5,
      },
      encode: {
        x: 0,
        y: [1, 2],
        tooltip: [1, 2],
      }
    }]
  };
  chart.setOption(option);
</script>

bar-range.auto.js 中的 auto 意味着加载时，它会自动将自定义系列注册到 echarts 全局变量中。开发者无需手动注册；只需在 setOption 中指定 type: 'custom'，并通过 renderItem: 'barRange' 指定所使用的自定义系列名称。

你通常需要通过 itemPayload 向自定义系列传递参数。你可以在每个自定义系列的 README 中找到其可配置参数。

请注意，你通常需要配置 encode 来指定数据映射。你可以在每个自定义系列的 README 和示例中找到推荐用法。

开发你自己的自定义系列

你可以参考 echarts-custom-series 的源码来学习如何开发自定义系列。建议 fork 该项目并使用 npm run generate xxx 生成一个新的自定义系列框架。它还提供了编译、文档、示例等脚手架，可以帮助你快速开发新的自定义系列。

主要的开发任务是实现一个 renderItem。相关文档请参阅 配置手册。

如果你开发了一个通用的自定义系列，建议通过 Pull Request 提交，以便更多开发者可以使用。

不可注册的自定义系列

如果你开发的自定义系列不打算复用，也可以直接在 renderItem 中实现自定义系列的渲染算法。你可以在 官方自定义系列示例 中找到许多示例并以此为基础进行开发。

贡献者 在 GitHub 上编辑此页

Ovilia Ovilia