Docx Kit

ECharts ​

将 ECharts 图表渲染为嵌入 Word 文档的图片，支持柱状图、折线图、饼图、散点图、雷达图、热力图等全部 ECharts 图表类型。

导入 ​

ts
import { echartsPlugin, type EChartsPluginOptions } from 'docx-kit'

依赖 ​

需要 echarts 对等依赖：

bash
pnpm add echarts

平台说明： ECharts 渲染需要浏览器 DOM 环境。Node.js 中会抛出错误，提示提供服务端 canvas 方案。

选项 ​

选项类型默认值说明
optionEChartsOption必填完整 ECharts 配置对象（series、坐标轴、标题等）
widthnumber640图表宽度，单位为像素
heightnumber360图表高度，单位为像素
renderer'canvas' | 'svg''canvas'ECharts 渲染引擎
imageType'png' | 'svg''png'输出图片格式
captionstring—图表下方的可选题注

示例 ​

柱状图 ​

ts
import {
  createDocx,
  echartsPlugin,
  type DocxBuilder,
} from 'docx-kit'

async function downloadDocx(doc: DocxBuilder, filename: string) {
  const url = URL.createObjectURL(await doc.toBlob())
  const anchor = document.createElement('a')
  anchor.href = url
  anchor.download = filename
  anchor.click()
  URL.revokeObjectURL(url)
}

const doc = createDocx()
  .use(echartsPlugin())
  .h1('Monthly Revenue')
  .plugin('echarts', {
    option: {
      title: { text: 'Monthly Revenue 2026' },
      tooltip: {},
      xAxis: {
        type: 'category',
        data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
      },
      yAxis: { type: 'value' },
      series: [{
        name: 'Revenue',
        type: 'bar',
        data: [120, 200, 150, 80, 70, 110],
        itemStyle: { color: '#2563eb' },
      }],
    },
    width: 640,
    height: 360,
    caption: 'Figure 1: Monthly revenue by product line',
  })

await downloadDocx(doc, 'bar-chart.docx')

折线图 ​

ts
const doc = createDocx()
  .use(echartsPlugin())
  .h1('User Growth')
  .plugin('echarts', {
    option: {
      title: { text: 'User Growth Trend' },
      tooltip: { trigger: 'axis' },
      legend: { data: ['Users', 'Active'] },
      xAxis: { type: 'category', data: ['Jan', 'Feb', 'Mar', 'Apr', 'May'] },
      yAxis: { type: 'value' },
      series: [
        {
          name: 'Users',
          type: 'line',
          data: [150, 230, 224, 218, 335],
          smooth: true,
          itemStyle: { color: '#2563eb' },
        },
        {
          name: 'Active',
          type: 'line',
          data: [120, 182, 191, 234, 290],
          smooth: true,
          itemStyle: { color: '#16a34a' },
        },
      ],
    },
    caption: 'Figure 1: Monthly user growth and active users',
  })

await downloadDocx(doc, 'line-chart.docx')

饼图 ​

ts
const doc = createDocx()
  .use(echartsPlugin())
  .h1('Market Share Analysis')
  .plugin('echarts', {
    option: {
      title: { text: 'Revenue by Product' },
      tooltip: { trigger: 'item' },
      legend: { orient: 'vertical', left: 'left' },
      series: [{
        name: 'Revenue Share',
        type: 'pie',
        radius: '60%',
        data: [
          { name: 'Product A', value: 1048 },
          { name: 'Product B', value: 735 },
          { name: 'Product C', value: 580 },
          { name: 'Product D', value: 484 },
          { name: 'Product E', value: 300 },
        ],
        emphasis: {
          itemStyle: {
            shadowBlur: 10,
            shadowOffsetX: 0,
            shadowColor: 'rgba(0, 0, 0, 0.5)',
          },
        },
      }],
    },
    caption: 'Figure 2: Revenue distribution across product lines',
  })

await downloadDocx(doc, 'pie-chart.docx')

散点图 ​

ts
const doc = createDocx()
  .use(echartsPlugin())
  .h1('Correlation Analysis')
  .plugin('echarts', {
    option: {
      title: { text: 'Height vs Weight Correlation' },
      xAxis: { name: 'Height (cm)', type: 'value' },
      yAxis: { name: 'Weight (kg)', type: 'value' },
      series: [{
        type: 'scatter',
        data: [
          [160, 55], [165, 60], [170, 65], [175, 70],
          [180, 75], [185, 80], [190, 85], [155, 50],
          [162, 58], [168, 63], [172, 68], [178, 72],
        ],
        itemStyle: { color: '#2563eb' },
      }],
    },
    caption: 'Figure 3: Height vs weight scatter plot (n = 12)',
  })

await downloadDocx(doc, 'scatter-chart.docx')

多图表报告 ​

ts
const doc = createDocx()
  .use(echartsPlugin())
  .h1('Q2 Analytics Report')

  // Bar chart — revenue
  .h2('Revenue by Quarter')
  .plugin('echarts', {
    option: {
      title: { text: 'Quarterly Revenue' },
      xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
      yAxis: { type: 'value' },
      series: [{
        type: 'bar',
        data: [820, 932, 901, 1347],
        itemStyle: { color: '#2563eb' },
      }],
    },
    caption: 'Figure 1: Quarterly revenue (in thousands)',
  })

  .pageBreak()

  // Line chart — growth
  .h2('Monthly Growth Rate')
  .plugin('echarts', {
    option: {
      title: { text: 'Monthly Growth Rate' },
      xAxis: { type: 'category', data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] },
      yAxis: { type: 'value', axisLabel: { formatter: '{value}%' } },
      series: [{
        type: 'line',
        data: [5.2, 3.8, 7.1, 4.9, 6.3, 8.5],
        smooth: true,
        areaStyle: { color: 'rgba(37, 99, 235, 0.1)' },
        itemStyle: { color: '#2563eb' },
      }],
    },
    caption: 'Figure 2: Month-over-month growth rate',
  })

  .pageBreak()

  // Pie chart — distribution
  .h2('Revenue by Region')
  .plugin('echarts', {
    option: {
      title: { text: 'Revenue by Region' },
      series: [{
        type: 'pie',
        radius: ['40%', '70%'],
        data: [
          { name: 'North America', value: 45 },
          { name: 'Europe', value: 25 },
          { name: 'Asia Pacific', value: 20 },
          { name: 'Others', value: 10 },
        ],
      }],
    },
    caption: 'Figure 3: Regional revenue distribution',
  })

await downloadDocx(doc, 'analytics-report.docx')

自定义尺寸 ​

ts
const doc = createDocx()
  .use(echartsPlugin())
  .h1('Wide Chart')
  .plugin('echarts', {
    option: {
      title: { text: '12-Month Trend' },
      xAxis: {
        type: 'category',
        data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
               'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
      },
      yAxis: { type: 'value' },
      series: [{
        type: 'line',
        data: [100, 120, 115, 140, 160, 180, 200, 190, 210, 230, 220, 250],
      }],
    },
    width: 800,
    height: 300,
  })

await downloadDocx(doc, 'wide-chart.docx')

样式定制 ​

工厂的 { styles } 设置实例默认值，options.styles 覆盖单次调用。插件包与 docx-kit 入口导出 EChartsConfig 和 EChartsStyles。优先级：内置/主题默认值 → 初始化 styles → 通用 style → 单次部位 styles。嵌套字段合并，数组整体替换，undefined 沿用默认，0 / false 生效；支持单位与 $colors.primary 等主题 token。

部位样式类型范围
captionTextStyleRule文字排版
captionParagraph, imageParagraphParagraphStyleRule段落背景、边框、对齐、间距和分页

ECharts 仍仅支持浏览器。图表内容与尺寸使用 option、width、height，这里的样式控制外围段落与题注。

工厂及类型从 docx-kit（浏览器）或 @docxkit/plugin-echarts 导入。

ts
echartsPlugin({
  styles: { caption: { color: '#2563EB', fontSize: 14 } },
})

单次调用在 options.styles 中使用相同部位名。JSON DSL、AI 工具 schema 与 MCP 校验共享这些契约；未知部位与放错部位的属性会被拒绝。

Released under the MIT License.

Copyright © ntnyq