图表

GitHub在 GitHub 上编辑
预设信息
@univerjs/preset-sheets-advanced
需要服务端支持

图表是数据可视化的重要工具,可以帮助用户更直观地理解和分析数据。在 Univer Sheets 中,图表功能提供了多种类型的图表,包括柱状图、折线图、饼图等,用户可以根据需要选择合适的图表类型来展示数据。

预设模式

图表功能被包含在 @univerjs/preset-sheets-advanced 预设中。

安装

@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset 预设在运行时依赖 UniverSheetsDrawingPreset 预设,请先安装 @univerjs/preset-sheets-drawing。

npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

使用

import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'
import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css'
import '@univerjs/preset-sheets-advanced/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDrawingZhCN, 
      UniverPresetSheetsAdvancedZhCN, 
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), 
    UniverSheetsAdvancedPreset(), 
  ],
})

如果你拥有 Univer 的商业许可证,请参考在客户端使用许可证进行配置。

插件模式

安装

npm install @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui

使用

import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'
import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN'
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN'
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-chart-ui/facade'

import '@univerjs-pro/sheets-chart-ui/lib/index.css'

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsChartZhCN, 
      SheetsChartUIZhCN, 
    ),
  },
})

univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)

如果你拥有 Univer 的商业许可证,请参考在客户端使用许可证进行配置。

枚举

显示枚举
export enum ChartAttributeBits {
  Stack = 1 << 30,
  PercentStack = 1 << 29 | ChartAttributeBits.Stack,
  Horizontal = 1 << 28,
}

export enum ChartTypeBits {
  None = 0,
  Line = 1 << 1,
  Column = 1 << 2,
  ColumnStacked = ChartTypeBits.Column | ChartAttributeBits.Stack,
  ColumnPercentStacked = ChartTypeBits.Column | ChartAttributeBits.PercentStack,
  Bar = 1 << 2 | ChartAttributeBits.Horizontal,
  BarStacked = ChartTypeBits.Bar | ChartAttributeBits.Stack,
  BarPercentStacked = ChartTypeBits.Bar | ChartAttributeBits.PercentStack,
  Pie = 1 << 3,
  Doughnut = 1 << 8 | ChartTypeBits.Pie,
  Area = 1 << 4,
  AreaStacked = ChartTypeBits.Area | ChartAttributeBits.Stack,
  AreaPercentStacked = ChartTypeBits.Area | ChartAttributeBits.PercentStack,
  Radar = 1 << 5,
  Scatter = 1 << 6,
  Combination = 1 << 7,
}

Facade API

完整 Facade API 类型定义,请查看 FacadeAPI

在 Univer Sheets 中,您可以使用 Facade API 来创建、配置和管理图表。Facade API 是一种图表的编程接口,可以帮助您更方便地使用图表功能。

插入图表

FWorksheet.newChart() 方法用于创建一个图表构建器,返回一个 FChartBuilderBase 实例,您可以通过链式调用方法来设置图表的各种属性。

然后调用 build() 生成 IChartBuilderInfo 对象,通过 FWorksheet.insertChart(chartBuildInfo: IChartBuilderInfo) 方法将图表插入到表格中。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个柱状图,数据源为 A1:D6。
// 开始位置为单元格 B2 的左上角。
// 图表的宽度为 600,高度为 400。
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .setWidth(600)
  .setHeight(400)
  .build()
await fWorksheet.insertChart(chartInfo)

以下是 FChartBuilderBase 上的一些成员方法:

方法描述
addRange指定图表数据源范围
setPosition以 row,col 锚点方式设置图表位置
setAbsolutePosition以像素方式设置图表位置
setChartType设置图表类型
setWidth设置图表宽度
setHeight设置图标高度
setOptions设置图表配置项
setTransposeRowsAndColumns行列转换
setTheme设置主题
setXAxisTitle设置X轴标题
setYAxisTitle设置Y轴标题
setRightYAxisTitle设置右轴标题
setXAxisTextStyle设置X轴标题样式
setYAxisTextStyle设置Y轴标题样式
setRightYAxisTextStyle设置右轴标题样式
setInvalidValueStrategy设置空单元格显示方式
setAxisPointerStyle设置指示线样式
setALLSeriesStyle设置所有系列样式
setSeriesStyle设置系列样式
build生成 builder info,用于插入/更新图表

目前我们支持以下的配置项,您可以通过查阅 IChartBuildOptions 来获取对应的配置:

显示配置
export interface IChartBuildOptions {
  /**
   * @property {string} [title] The title of the chart.
   */
  title?: {
    /**
     * @property {string} [titlePosition] The position of the chart title.
     */
    position?: TitlePositionEnum
  } & IChartTextStyle
  /**
   * @property {string} [legend] The legend of the chart.
   */
  legend?: {
    /**
     * @property {string} [legendPosition] The position of the legend.The possible values are 'top', 'bottom', 'left', 'right' & 'hide'.
     */
    position?: LegendPositionEnum
    /**
     * @property {number} [fontSize] The font size of the legend.
     */
    fontSize?: number
    /**
     * @property {string} [color] The font color of the legend.
     */
    color?: string
    /**
     * @property {string} [bold] The font style of the legend.
     */
    bold?: boolean
    /**
     * @property {string} [italic] The font weight of the legend.
     */
    italic?: boolean
    /**
     * @property {SelectModeEnum} [selectMode] The select mode of the legend.The possible values are 'single', 'multiple' & 'close'.
     */
    selectMode?: SelectModeEnum
  }
  /**
   * @property {string} [xAxisTitle] The x-axis title of the chart.
   * @example
   * ```typescript
   * chartBuilder.setOptions('xAxisTitle.content', 'xAxis Title text')
   * .setOptions('xAxisTitle.font', 1)
   * .setOptions('xAxisTitle.fontSize', 12)
   * .setOptions('xAxisTitle.fontColor', '#ff0000')
   * .build();
   * ```
   */
  xAxisTitle?: IChartTextStyle
  /**
   * @property {string} [rightYAxisTitle] The right y-axis title of the chart.
   */
  yAxisTitle?: IChartTextStyle
  /**
   * @property {string} [rightYAxisTitle] The right y-axis title of the chart.
   */
  rightYAxisTitle?: IChartTextStyle
  xAxis?: IAxisOptions
  yAxis?: IAxisOptions
  yRightAxis?: IAxisOptions
  axisPointer?: {
    /**
     * @property {string} [indicatorLineType] The line type of the axis pointer.
     */
    indicatorLineType?: string
    /**
     * @property {ChartBorderDashType} [indicatorLineColor] The line color of the axis pointer.The maybe values are 'solid', 'dotted', 'dashed'.
     */
    indicatorLineColor?: ChartBorderDashType
    /**
     * @property {string} [indicatorLabelColor] The line width of the axis pointer.
     */
    indicatorLabelColor?: string
    /**
     * @property {string} [indicatorLabelTextColor] The font color of the axis pointer.
     */
    indicatorLabelTextColor?: string
  }
  allSeriesStyle?: IAllSeriesStyle
  seriesStyleMap?: {
    [id: string]: ISeriesStyle
  }
  /**
   * @property {string} [area] The area of line/area chart.
   */
  area?: {
    lineStyle: AreaLineStyle
  }
  /**
   * @property {string} [backgroundColor] The background color of the chart.
   */
  backgroundColor?: string
  /**
   * @property {string} [borderColor] The border color of the chart.
   */
  borderColor?: string
  /**
   * @property {boolean} [gradientFill] Whether to use gradient fill.This property does not work in line charts.
   */
  gradientFill?: boolean
  /**
   * @property {string} [theme] The theme of the chart.
   */
  theme?: string
  /**
   * @property {InvalidValueType} [invalidValueType] The display mode for empty cells.
   */
  invalidValueType?: InvalidValueType
}

配置项通过 setOptions 方法来设置,有以下两种方式:

  • setOptions(optionPath, optionVal): setOptions('legend.color', '#ff0000')
  • setOptions('', IChartBuildOptions): setOptions('', { legend: { color: '#ff0000', bold: true } })
创建一个折线图示例
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个折线图
const chartInfo = fWorksheet.newChart()
  // 折线图
  .asLineChart()
  // 设置数据源 A1:D6
  .addRange('A1:D6')
  // 设置起始位置 B2 单元格左上角
  .setPosition(1, 1, 0, 0)
  // 设置指示线样式
  .setAxisPointerStyle({
    indicatorLabelColor: '#ff0000',
    indicatorLineType: univerAPI.Enum.ChartBorderDashType.Solid,
    indicatorLineColor: '#00ff00',
    indicatorLabelTextColor: '#0000ff',
  })
  // 设置数据点大小 10
  .setDataPointSize(10)
  // 设置数据点形状为圆形
  .setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
  // 生成 builder info
  .build()
const fChart = await fWorksheet.insertChart(chartInfo)

// 3 秒后更新图表
setTimeout(() => {
  if (fChart) {
    // 获取第一个系列数据
    const first = fChart.getSeriesData()[0]
    // 设置第一个系列颜色为红色
    const newChartInfo = fWorksheet.newChart(fChart)
      .setSeriesStyle(first.index, {
        color: '#ff0000',
      })
      .build()
    // 更新图表
    fSheet.updateChart(newChartInfo)
  }
}, 3000)

目前我们还提供了以下的 builder 来创建对应的图表,这些 builder 都可以通过类似 fWorkSheet.newChart().asLineChart() 来创建,他们派生自 FChartBuilderBase 并且具有一些特有的配置:

const lineChartBuilder = fWorkSheet.newChart().asLineChart()
const pieChartBuilder = fWorkSheet.newChart().asPieChart()
const radarChartBuilder = fWorkSheet.newChart().asRadarChart()

// 也可以通过下面的方式来创建
const chartBuilder = fWorkSheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
方法描述
setLineStyle设置折线的平滑度,'line'- 折线 , 'smooth'- 平滑, 'step' -阶梯
setDataPointShape设置数据点形状,可以通过 LinePointShape 来查看支持的形状类型
setDataPointColor设置数据点颜色
setDataPointSize设置数据点大小
build生成 builder info,用于插入/更新图表
方法描述
setDoughnutHole设置饼图空心大小,该参数范围为 0-1
setBorderColor设置饼图扇区的色值
setHasPaddingAngle设置饼图扇区的是否有夹角(分离)
setIsHalfPie是不是半饼
setRosePie是不是玫瑰图
setShowLabelLine显示标签线
build生成 builder info,用于插入/更新图表
方法描述
setShape设置雷达图默认形状,目前支持的值为:'polygon'-多边形,'circle'-圆形
setFill是否填充雷达图
build生成 builder info,用于插入/更新图表

获取图表

FWorksheet.getCharts() 方法用于获取当前工作表中的所有图表,返回一个 FChart[] 数组。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()

以下是 FChart 上的一些成员方法:

方法描述
getRange获取图表数据源范围
getSeriesData获取图表系列数据
getCategoryData获取图表类别数据
updateRange更新图表数据源范围

更新图表

FWorksheet.updateChart(chartBuildInfo: IChartBuilderInfo) 方法用于更新图表,传入一个 IChartBuilderInfo 对象,用于更新图表的配置。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个柱状图,数据源为 A1:D6.
// 起始位置为单元格 B2 的左上角.
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build()
await fWorksheet.insertChart(chartInfo)

// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()

// 3 秒后更新第一个图表
setTimeout(() => {
  const newChartInfo = fWorksheet.newChart(charts[0])
    .asLineChart()
    .setOptions('legend.position', univerAPI.Enum.LegendPositionEnum.Right)
    .build()
  fWorksheet.updateChart(newChartInfo)
}, 3000)

删除图表

FWorksheet.removeChart(chart: FChart) 方法用于删除图表,传入一个 FChart 对象,用于删除指定的图表。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个柱状图,数据源为 A1:D6.
// 起始位置为单元格 B2 的左上角.
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build()
await fWorksheet.insertChart(chartInfo)

// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()

// 3 秒后删除第一个图表
setTimeout(async () => {
  await fWorksheet.removeChart(charts[0])
  fWorksheet.getCharts()
}, 3000)

图表主题

FWorksheet.registerChartTheme(themeName: string, theme: IEchartTheme) 方法用于注册图表主题,传入一个主题名称和主题对象,用于注册自定义主题。

Univer chart 是基于 echarts 的图表库实现的,因此可以借助 echart 的主题构建工具来构建您的自定制主题。 您可以在该网站构建您自己的主题并下载成为配置文件,使用以下 API 来使用您的自定义主题:

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 注册您的主题
const theme = { // 您的主题配置
  version: 1,
  themeName: 'myTheme',
  theme: {
    // ... 为了简洁,省略了一些代码
    color: [
      '#893448',
      '#d95850',
      '#eb8146',
      '#ffb248',
      '#f2d643',
      '#ebdba4',
    ],
    // ... 为了简洁,省略了一些代码
    visualMapColor: [
      '#893448',
      '#d95850',
      '#eb8146',
      '#ffb248',
      '#f2d643',
      'rgb(247,238,173)',
    ],
    // ... 为了简洁,省略了一些代码
    axes: [],
    // ... 为了简洁,省略了一些代码
  },
}
fWorksheet.registerChartTheme('myTheme', theme)

// 使用您的主题创建一个折线图
const chartInfo = fWorksheet.newChart()
  .asLineChart()
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .setTheme('myTheme')
  .build()
await fWorksheet.insertChart(chartInfo)

你觉得这篇文档如何?