Skip to Content
🎉 Univer 0.8.3 版本已发布。查看详情 →
GuidesUniver Sheets功能图表Pro

图表 0.5.0+

Facade API可付费升级需要 Univer 服务端Univer on Node.jsPreset
-UniverSheetsAdvancedPreset

图表提供了在表格中基于区域数据插入浮动图表的功能。

该功能包含以下插件包:

Presets 安装

按照 打印功能 中的引导安装即可。

手动组合安装

npm install @univerjs-pro/engine-chart @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
import { LocaleType, merge, Univer } from '@univerjs/core'; import { defaultTheme } from "@univerjs/design"; import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'; import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN'; import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'; import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN'; import '@univerjs-pro/sheets-chart-ui/facade'; import '@univerjs-pro/sheets-chart-ui/lib/index.css'; const univer = new Univer({ theme: defaultTheme, locale: LocaleType.ZH_CN, locales: { [LocaleType.ZH_CN]: merge( SheetsChartZhCN, SheetsChartUIZhCN ), }, }); univer.registerPlugin(UniverSheetsChartPlugin); univer.registerPlugin(UniverSheetsChartUIPlugin);

Univer on Node.js 手动组合安装

npm install @univerjs-pro/engine-chart @univerjs-pro/sheets-chart
import { LocaleType, merge, Univer } from '@univerjs/core'; import { defaultTheme } from "@univerjs/design"; import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'; import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN'; const univer = new Univer({ theme: defaultTheme, locale: LocaleType.ZH_CN, locales: { [LocaleType.ZH_CN]: merge( SheetsChartZhCN, ), }, }); univer.registerPlugin(UniverSheetsChartPlugin);

图表简介

图表是一种可视化数据的方式,可以帮助用户更直观地理解数据。在 Sheets 中,您可以使用图表功能将数据转换为图表,以便更好地展示数据的关系和趋势。

我们提供一下几种图表类型:

  • 折线图:折线图用于展示数据的变化趋势,适用于时间序列数据。
  • 柱状图:柱状图用于展示数据的大小关系,适用于比较数据。
  • 饼图/环形图/玫瑰图:饼图用于展示数据的占比关系,适用于展示数据的相对比例。
  • 散点图:散点图用于展示数据的分布关系,适用于展示数据的相关性。
  • 面积图:面积图用于展示数据的累积关系,适用于展示数据的变化趋势。
  • 条形图/堆叠条形图/百分比堆叠条形图:条形图用于展示数据的大小关系,适用于比较数据。
  • 雷达图:雷达图用于展示数据的多维关系,适用于展示数据的多维分析。
  • 组合图:组合图用于展示多组数据的关系,适用于展示多组数据的比较。

在 Sheets 中,您可以根据需要选择不同的图表类型,以便更好地展示数据。我们会根据用户的反馈,不断优化图表功能,提供更多的图表类型,以便更好地满足用户的需求。

以下是Univer chart的枚举类型,您可以通过查看这些枚举来了解我们支持的图表类型和配置项:

显示枚举

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 0.5.2+

完整 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(); console.log(charts);

以下是 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]); console.log(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);
Last updated on